Skip to main content
Glama
Sign In
nyc-311-mcp

nyc-311-mcp

by BetaNYC
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

problem_trend

Compare monthly 311 request counts for one problem and district with the same period a year earlier to spot trends and year-over-year changes.

Instructions

Requests per month for one problem in one district, with the same days a year earlier. Optional description, agency and status filters. Months only partly covered are marked. 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

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": {
      "problem": "<problem>"
    },
    "name": "problem_trend"
  }
}

Input Schema

NameRequiredDescriptionDefault
agencyNoAgency code as 311 writes it, e.g. 'NYPD'.
statusNo'not_closed' = any status but Closed.
problemYesOne BoardStat problem name, e.g. 'HEAT/HOT WATER', 'Noise - Residential', 'Rodent'.
to_dateNoEnd, YYYY-MM-DD, inclusive.
from_dateNoStart, YYYY-MM-DD, inclusive.
last_daysNoThe last N days of data, ending on the newest request's day (not today).
fiscal_yearNoNYC fiscal year: 2027 or 'FY2027' = 2026-07-01 to 2027-06-30.
descriptionsNo311 descriptors, e.g. ['Blocked Bike Lane']; a missing one is '(none)'.
council_districtNoCouncil district, 1 to 51. Not with community_district.
community_districtNo306, BK06 or 'Brooklyn 6' (all forms: server instructions). Not with council_district.
exclude_descriptionsNoLeave out these descriptions instead of keeping only them.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.2.0

TDQS

A3.6/5.0
Behavior4/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 substantial work: it discloses the data provenance (BoardStat/BetaNYC, NYC Open Data, 2020 onward), warns it is not an official City report, flags that partly covered months are marked, and cautions that counts are reports rather than problems and 'closed' is not 'fixed'. These are real interpretation caveats an agent would not otherwise have. It omits any statement about result size, pagination, or the shape of the response.

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 core scope is front-loaded in the first sentence, followed by filters, caveats, and provenance in decreasing order of importance. Sentences are dense but each carries distinct information. The telegraphic phrasing ('311 counts are reports, not problems') is terse but not wasteful.

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

Completeness3/5

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

For an 11-parameter analytical tool with no annotations and no output schema, the description covers provenance and interpretation well but says nothing about the return structure (presumably monthly buckets with prior-year comparison) or how the multiple date-selection parameters should be chosen. It is adequate, not complete.

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 coverage is 100%, so the schema already documents all 11 parameters including date forms, fiscal year syntax, and the council/community district exclusion. The description only restates that description, agency and status filters are optional. It adds no guidance on how from_date, to_date, last_days and fiscal_year interact, leaving the baseline 3.

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

Purpose4/5

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

The first sentence states a specific verb and resource: monthly request counts for one problem in one district, paired with the same days a year earlier. That is far more precise than the tool name alone. It does not, however, name or differentiate itself from siblings such as cb_monthly_list or top_problems, so an agent must infer the boundary.

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

Usage Guidelines3/5

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

The description implies the use case (trend/seasonality comparison for a single problem in a single district) and notes the optional description, agency and status filters. It never states when to prefer this tool over sibling alternatives or what preconditions apply. Usage is inferable but not guided.

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

Deploy Server

Other Tools