nyc-311-mcp

draft_311_report

Draft a ready-to-paste NYC 311 report from a problem description, including where and when, the City's reporting link, missing-detail questions, and next steps; submit it yourself.

Instructions

Draft a 311 report for the person to submit themselves: a short ready-to-paste text (problem, where, when, what they saw), the 311 Online article link to report it on, questions to ask them for anything missing (marked [add: …], never made up), Problem Detail options from the City's 2024 Service Level Agreements list (labeled old), what the City's article says about contact details and photos, and what happens next. Uses how_to_report's matching. Files nothing, sends nothing, and fills no form: the City does not publish each form's fields, so the form may ask for more. If the description suggests an emergency it does not draft and says to call 911. A description of two problems gets one draft each. Every answer and error 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." 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.

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": "draft_311_report"
  }
}

Input Schema

Name	Required	Description
`when`	No	When they saw it, in their words ('Nov 6 around 8 pm').
`borough`	No
`details`	No	Anything else they said about it.
`ongoing`	No	Whether it is still happening, has stopped, or keeps happening.
`location`	No	Where: a street address, two cross streets ('Broadway and W 96 St'), or a landmark. A ZIP code is left out.
`description`	Yes	The problem in the person's words. Goes into the draft; not stored or sent anywhere.
`include_contact`	No	Only if the person asked for their contact details to be in the draft. Otherwise leave out; the form asks for them.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.2.0Nov 12, 2026

TDQS

A4.4/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 behavioral burden and does so thoroughly. It discloses that the tool files nothing, sends nothing, and fills no form; that the form may ask for more fields; that keyword-based danger detection may miss emergencies; that every answer and error must include a specific disclaimer; and that two problems get one draft each. It also explains how missing details are marked rather than invented and labels old Problem Detail options.

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

Conciseness4/5

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

The description is front-loaded with the core purpose and output shape, then proceeds through limitations and safety behavior. It is long and includes repeated emergency guidance and a full disclaimer string, but the length is largely justified by the tool's safety-critical complexity. Structure could be tighter, but the content is relevant and readable.

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?

There is no output schema, so the description must explain what the tool returns, and it does: draft text, article link, missing-detail questions, Problem Detail options, contact/photo guidance, and next steps. It also covers safety, non-filing behavior, multiple-problem handling, disclaimer requirements, and source limitations. This is complete for a complex, safety-sensitive drafting tool.

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 86%, so the input schema already provides strong parameter-level documentation. The description reinforces the conceptual inputs ('problem, where, when, what they saw') and notes that contact details are included only when requested, but it adds little parameter-specific meaning beyond the schema. A baseline 3 is appropriate when the schema does the heavy lifting.

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?

The description opens with a specific verb and resource: 'Draft a 311 report for the person to submit themselves.' It then lists the concrete output components, including ready-to-paste text, the 311 Online article link, follow-up questions, Problem Detail options, contact/photo information, and next steps. It clearly distinguishes itself from filing or submitting tools by stating 'Files nothing, sends nothing, and fills no form.'

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?

The description makes clear this is for producing a draft the person submits themselves, not for filing a report or filling out a form. It names how_to_report as the matching source and states emergency exclusions, including not drafting when an emergency is suggested. It does not explicitly compare itself against other sibling tools, but the context and exclusions are clear.

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