Skip to main content
Glama
WillHsiaoNYC

NYC Open Data Capital Projects MCP Server

by WillHsiaoNYC
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

budget_change

Read-onlyIdempotent

Compare NYC capital project budgets or spending for an agency or FMS line between two periods, returning signed per-line changes with role-aware scope.

Instructions

Δ budget/spend for an agency ('agency:DEP') or FMS line ('fms:ABC') between two periods. For an agency target, agency_role ('auto'|'sponsor'|'managing') picks the lens; sponsor scope uses the latest-period owner set (as-of caveat in the result label). An FMS id held by several managing agencies is several distinct budget lines: the result then lists per-line deltas (never a cross-agency sum); pass managing_agency to scope to one line.

Interpretation rules:

  • [grain] Schedule questions use PID; budget questions use the BUDGET LINE key (managing_agency, fms_id). The same FMS ID under different holders is distinct lines. Schedule history is PID x reporting_period; budget history is budget line x reporting_period; fiscal-year budgets also key on fiscal_year. The schedule source has no fms_id; budget sources have no pid. The combined source repeats rows across PID-budget links and location splits: deduplicate at the requested entity grain before counting or summing. Never compare budgets using fms_id alone.

  • [period_basis] Reporting-period basis: state the returned period for every count, total or ranking and both periods for comparisons. Period aggregates default to the latest complete snapshot, which may precede a partially published newer period. fms_location, fms_sponsor and lifetime_budget_variance are all-history dimensions without reporting_period: use them for enrichment or lifetime figures, never as a single period's inventory.

  • [agency_roles] Agency attribution is role-aware: an agency's projects mean its sponsor (owner) view, except DDC/DCAS/EDC default to managing (builder). State the returned agency_scope. managing_agency is the executor on schedules and the budget-holder on budgets; a budget-only holder is not a schedule executor. list_agencies exposes is_schedule_executor. For sponsor-scoped budget totals, use a semi-join to fms_sponsor; a value-bearing join can multiply lines. Co-owner totals can overlap and must not be added together.

  • [budget_baseline] budget_variance is change from the previous reporting period; cumulative_budget_change is latest minus original. State which basis is used. original_budget prefers the adopted first budget, with first_snapshot as fallback: disclose original_budget_source. Adoption months are calendar months from a separate first-budget system, not reporting snapshots.

  • [signed_values] Report neutral, SIGNED changes: "moved 45 days later" or "budget decreased $2M". Do not echo loaded terms in the answer. "slippage" means positive schedule change and "overrun" means positive budget growth; neither includes the decreasing side. Preserve the returned direction and metric basis.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
metricNototal_budget
targetYes
to_periodYes
agency_roleNoauto
from_periodYes
managing_agencyNo

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
changeYes
targetYes
provenanceYes
interpretation_rulesYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.1.1
    • addedInput schema / properties / agency_role / enum
      Added value: +[
+  "auto",
+  "sponsor",
+  "managing"
+]
    • addedInput schema / properties / managing_agency
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Managing Agency"
+}
    • addedInput schema / properties / metric / enum
      Added value: +[
+  "total_budget",
+  "spend"
+]
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$defs": {
+    "InterpretationRule": {
+      "properties": {
+        "id": {
+          "description": "Stable identifier of the domain rule.",
+          "title": "Id",
+          "type": "string"
+        },
+        "text": {
+          "description": "Guidance for interpreting and reporting this tool's result.",
+          "title": "Text",
+          "type": "string"
+        }
+      },
+      "required": [
+        "id",
+        "text"
+      ],
+      "title": "InterpretationRule",
+      "type": "object"
+    }
+  },
+  "additionalProperties": true,
+  "properties": {
+    "change": {
+      "additionalProperties": true,
+      "title": "Change",
+      "type": "object"
+    },
+    "interpretation_rules": {
+      "items": {
+        "$ref": "#/$defs/InterpretationRule"
+      },
+      "title": "Interpretation Rules",
+      "type": "array"
+    },
+    "provenance": {
+      "additionalProperties": true,
+      "title": "Provenance",
+      "type": "object"
+    },
+    "target": {
+      "title": "Target",
+      "type": "string"
+    }
+  },
+  "required": [
+    "provenance",
+    "interpretation_rules",
+    "target",
+    "change"
+  ],
+  "title": "BudgetChangeResult",
+  "type": "object"
+}
  2. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/closed-world, and the description adds substantial behavioral context beyond them: as-of caveats and latest-snapshot defaults, explicit dedup warnings for the combined source, overlap warnings on co-owner totals, signed-value reporting conventions, and disclosure requirements (agency_scope, original_budget_source, period basis).

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 long, but it is front-loaded with the core operation and then organized into labeled rules, with no filler sentences. The density is justified by the domain complexity, though some interpretation rules read as output-guidance that could be trimmed.

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?

Given an output schema exists (so return formatting needn't be explained), the description covers the remaining complexity well: entity grain keying, period basis, agency-role attribution, budget baseline semantics, and signed-value direction. An agent has enough to call the tool and interpret results correctly.

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 description coverage is 0%, so the description must carry parameter meaning and largely does: target syntax ('agency:DEP' / 'fms:ABC'), agency_role lens values, managing_agency scoping, and metric semantics (budget vs spend). It is not fully exhaustive, though — the accepted format of from_period/to_period is never specified.

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 opening sentence gives a specific verb/operation ('Δ budget/spend'), names both resource types ('agency:DEP' or 'fms:ABC'), and states the temporal scope ('between two periods'). It is readily distinguishable from siblings like get_project_budget (single-project snapshot) or budget_breakdown (dimension breakdown) because it is framed strictly as a delta computation.

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?

It gives clear operating context: when to pass managing_agency to scope to one line, what agency_role does, and which grain/basis applies to budget vs schedule questions. However it never names an alternative tool (e.g., budget_breakdown or get_project_budget) or states when NOT to use this tool, so routing relies on inference.

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