nyc-311-mcp

find_requests

List NYC 311 service requests in a community or council district, newest first, filtered by problem, agency, status or date, with per-status counts and resolution text.

Instructions

List the requests in a community or council district, newest first, with any status, paged with limit and offset. Each has its status, days to close or days open, address and the agency's resolution text; by_status counts each status and says in plain words what it means. Filter by problems, descriptions, agency, status, or statuses (the City's own values). For one address use address_history; for only what is still open, still_open. From BoardStat (BetaNYC, NYC Open Data, 2020 on); not an official City report. 311 counts are reports, not problems; 'closed' is not 'fixed'.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "find_requests"
  }
}

Input Schema

Name	Required	Description
`limit`	No	Rows to list (default 25).
`agency`	No	Agency code as 311 writes it, e.g. 'NYPD'.
`offset`	No	Rows to skip (default 0); for the next page, next_page.offset.
`status`	No	'not_closed' = any status but Closed.
`to_date`	No	End, YYYY-MM-DD, inclusive.
`problems`	No	BoardStat problem names, e.g. ['HEAT/HOT WATER']; any case.
`statuses`	No	The City's status values to keep (seen: Closed, Open, In Progress, Pending, Assigned, Started, Unspecified); any case.
`from_date`	No	Start, YYYY-MM-DD, inclusive.
`last_days`	No	The last N days of data, ending on the newest request's day (not today).
`data_as_of`	No	For the next page, next_page.data_as_of; a page from a newer build is refused.
`fiscal_year`	No	NYC fiscal year: 2027 or 'FY2027' = 2026-07-01 to 2027-06-30.
`descriptions`	No	311 descriptors, e.g. ['Blocked Bike Lane']; a missing one is '(none)'.
`council_district`	No	Council district, 1 to 51. Not with community_district.
`community_district`	No	306, BK06 or 'Brooklyn 6' (all forms: server instructions). Not with council_district.
`exclude_descriptions`	No	Leave out these descriptions instead of keeping only them.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.2.0Nov 12, 2026

TDQS

A4.4/5.0

Behavior3/5

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

No annotations are supplied, so the description carries the full burden, and it does disclose a lot: newest-first ordering, limit/offset paging, the per-row fields (status, days to close or days open, address, resolution text) and the by_status summary with plain-word meanings. What it omits is operational behavior an agent would want before calling: approximate response size at limit=200, whether by_status counts the whole filtered set or only the page, and cost/latency. So it is rich but not complete on the behavioral side.

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?

Front-loaded with the core action, ordering and paging; then output shape, then filters, then alternatives, then caveats. Roughly a hundred words for a 15-parameter tool with no annotations, and each sentence carries distinct information.

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?

Given 15 optional parameters, no output schema and no annotations, the description covers return fields, ordering, paging, alternatives and source caveats, which is most of what an agent needs. The gaps are the untouted parameters (fiscal_year, last_days, exclude_descriptions, data_as_of) and how the date filters interact, but the 100% schema coverage covers those adequately.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by grouping the filter family ('problems, descriptions, agency, status, or statuses (the City's own values)') and by flagging that status and statuses are different things - singular enum shorthand versus the City's own value list. It still leaves from_date/to_date/last_days/fiscal_year and exclude_descriptions to the schema alone.

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 and resource ('List the requests'), the scope (community or council district), the ordering (newest first), and the paging model. It explicitly names the sibling tools address_history and still_open as the alternatives for narrower jobs, so an agent can route without opening a schema.

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

Usage Guidelines5/5

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

Gives explicit routing rules: 'For one address use address_history; for only what is still open, still_open.' It also sets expectations about the data source and vintage (BoardStat, 2020 on, not an official City report), which tells the agent when its output is and isn't appropriate.

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