nyc-311-mcp

how_to_report

Find how to report a NYC 311 problem from a plain description. Get relevant 311 articles, agency, problem type, next steps, and reporting options; does not file a report.

Instructions

Find how to report a problem to 311, from a plain description ('a pothole on my block', 'no heat in my apartment'). Returns the best 311 articles from the City's own 311 content (title, KA number, link on 311 Online), the agency and the 311 problem type each names (the problem type is NYC Open Data's complaint_type), what the article says to do and what happens next, and the ways to report (311 Online, the NYC311 app, phone 311 or 212-NEW-YORK, text 311-692), all from City text. Every answer starts with 'For informational purposes only. BetaNYC builds these answers from City data; they may contain errors. Check the City's 311 page before you report. If this is an emergency, or if you think this is an emergency, call 911.'; a description that suggests danger, and every no-match answer, leads with a 911 line, in the City's words only when the City article is that danger. IMPORTANT: danger detection here is keyword-based and will miss some emergencies. If anything the person says suggests someone may be in danger or need urgent medical help, tell them to call 911 first, even if this tool did not flag it. Matching is by keyword, done by BetaNYC, and reads only a few 311 categories (listed in searched). Give community_district or council_district to add how often that problem type was reported there (BoardStat). Does not file anything.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "description": "<description>"
    },
    "name": "how_to_report"
  }
}

Input Schema

Name	Required	Description
`limit`	No	How many articles to return (default 3).
`borough`	No	Optional. 311's articles are citywide, so this does not change the match; it is noted for the report.
`last_days`	No	With a district: count reports over the last N days of data (default 365).
`category_id`	No	Search only this 311 category (an id from list_311_categories, e.g. '311-12' for Noise).
`description`	Yes	The problem in plain words. Not stored and not sent anywhere: only the 311 content is fetched.
`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.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.2.0Nov 12, 2026

TDQS

A4.5/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so: it discloses the exact fixed disclaimer prefix every answer begins with, the 911-leading behavior for danger or no-match answers, the keyword-based matching method, and the explicit admission that the danger detection will miss some emergencies. It also states which related data (BoardStat counts) only appears when a district is supplied.

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

Conciseness3/5

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

Purpose and inputs are front-loaded, but the body is one dense block that embeds the full quoted disclaimer and a long sentence about the 911-line logic, making it harder to scan than a structured breakdown would be. Most sentences carry information, though the verbatim boilerplate text could have been compressed.

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

Completeness5/5

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

With no output schema, the description fully specifies what an answer contains: article title, KA number, 311 Online link, agency, complaint_type, remediation steps, next steps, and reporting channels. It also covers the fixed disclaimer and the conditional BoardStat enrichment, leaving nothing an agent needs to call it correctly unspecified.

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 schema already defines all seven parameters, but the description adds real meaning: it explains that borough does not change the citywide match (only noted in the report) and that district parameters conditionally unlock BoardStat frequency data. It also discloses the limitation that only a few 311 categories are searched, which no schema field conveys.

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 ('Find how to report a problem to 311') and immediately grounds it with concrete example inputs ('a pothole on my block', 'no heat in my apartment'). The closing 'Does not file anything' separates it from filing/drafting siblings like draft_311_report.

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 clear conditions for use: pass a plain-language description, optionally add community_district or council_district to enrich with BoardStat report counts, and note that it never files a report. It also instructs the agent to override keyword-based danger detection when a person may be at risk. It does not name a specific sibling to use when the user actually wants to file, so the alternative is implied rather than explicit.

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