nyc-open-data-mcp

Overview Schema Source Related Servers Discussions Admin

Query a dataset (SoQL)

query_dataset

Read-onlyIdempotent

Run read-only SoQL queries against NYC Open Data datasets by ID to filter, sort, group, search, and page results for analysis.

Instructions

Run a read-only SoQL query against any NYC Open Data dataset by id. Supports select / where / order / group / full-text q, with limit (max 500) and offset paging; the response says when more rows exist. Get the dataset id and column names from search_datasets first. For counts, prefer select="count(*)" or a group-by over pulling raw rows.

Input Schema

TableJSON Schema

Name	Required	Description
`q`	No	Full-text search across all text columns.
`group`	No	SoQL $group, required when $select mixes aggregates and plain columns.
`limit`	No	Rows to return (1-500, default 100).
`order`	No	SoQL $order, e.g. "inspection_date DESC".
`where`	No	SoQL $where, e.g. "zipcode = '10003' AND grade = 'A'". Single-quote string literals; double any quote inside ('O''Brien').
`offset`	No	Rows to skip; pass next_offset from a previous call to page. Use a stable order when paging.
`select`	No	SoQL $select, e.g. "borough, count(*) as n". Default: all columns.
`dataset_id`	Yes	Socrata dataset id, e.g. 43nn-pn8j (restaurant inspections) or erm2-nwe9 (311).

Output Schema

TableJSON Schema

Name	Required	Description	Default
`note`	No
`rows`	Yes
`offset`	Yes
`has_more`	Yes
`returned`	Yes
`dataset_id`	Yes
`next_offset`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.0Oct 7, 2026

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context on top: the 500-row limit ceiling, offset-based paging, and that the response signals when more rows exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the core action and scope, followed by capabilities and then the routing tip. No filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return-value explanation is unnecessary, and the description still notes the paging signal in responses. The one omission is that it never routes users to the specialized restaurant/311 siblings, which an agent working in that domain would benefit from knowing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and each SoQL clause already carries its own documented example and quoting rules, so the schema does the heavy lifting. The description largely restates the clause list (select/where/order/group/q/limit/offset) and the max-500 limit, adding little syntax or format detail beyond it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (run) and resource (read-only SoQL query against any NYC Open Data dataset by id), and immediately scopes it as read-only. It is clearly distinguishable from search_datasets, which is named as the discovery step rather than the query execution tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit prerequisite guidance (get dataset id and column names from search_datasets first) and a concrete recommendation for count queries (select="count(*)" or group-by rather than raw rows). It stops short of explaining when to prefer the specialized restaurant_inspections and service_requests_311 siblings over a generic SoQL query, which is a real routing gap.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server