NYC Open Data Capital Projects MCP Server

Overview Schema Source Related Servers Discussions Admin

get_project_history

Read-onlyIdempotent

Retrieve period-by-period schedule or budget history for one NYC capital project by PID or FMS ID, showing phases, forecasts, variances, delays, and spending.

Instructions

Period-by-period history for ONE project. Schedule lens (pid=…): each period's phase, forecast, signed variance, delay reason + a current-state header carrying agency_project_name, cumulative variance, and forecast_past_due (see get_project_schedule). Budget lens (fms_id=…, case-insensitive): each period's budget/spend/signed variance per (managing_agency, fms_id) line, the line-keyed fms_project_name, + the adopted original budget when recorded (adoption-only lines return header-only). Provide exactly one of pid/fms_id; managing_agency scopes a multi-agency FMS id to one line — otherwise ALL lines are listed.

Interpretation rules:

[relationships] "Project" is ambiguous: PID identifies a SCHEDULE; FMS ID identifies a BUDGET. They are MANY-TO-MANY: a budget can fund several PIDs and a PID can have several budgets. LIST ALL linked counterparts; never silently select one. One linked counterpart does not establish a 1:1 relationship in the reverse direction. A budget without a PID is normal before Design and for lines that do not require schedules; absence alone does not establish missing data. Source-only schedules can also lack dashboard funding links.
[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.
[population] Listings/rankings default to population_scope='latest_known' (each entity's own latest observation). Use population_scope='current' for the selected complete snapshot. State the population_scope and observation period; respect present_in_current_snapshot. Detail tools use latest-known state and each anchor's latest available link period; these links are not proof of presence in the current complete snapshot.
[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.
[schedule_coverage] Schedule totals and cumulative variance use dashboard-aligned schedule_history. source_schedule_history retains native observations absent from that population; schedule_source_coverage reconciles them. State the schedule universe and cumulative basis. Parenthesized phases are no-schedule reasons. Respect excluded variance artifacts and missing/invalid-duration counts; forward duration statistics exclude reversed dates.
[lifecycle] Lifecycle: Pre-Design -> Design -> Construction Procurement -> Construction -> Close-out. Schedule progression is reported from Design through Construction. Forecasts and most actual milestones can be suppressed outside those phases; actual_construction_end is the exception and means substantial completion. NULL milestones need not mean missing data. Budget spend%=100 does not prove completion. forecast_past_due is evaluated as of the observation period, not today's date.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`pid`	No
`fms_id`	No
`managing_agency`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`lines`	No
`anchor`	Yes
`periods`	No
`provenance`	Yes
`interpretation_rules`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.1.1Sep 12, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only cover safety (readOnly, idempotent, closed-world), while the description adds substantial operational context: many-to-many PID-FMS linking that must not be collapsed to 1:1, deduplication at the requested entity grain, adoption-only lines returning header-only, original_budget_source disclosure, and that forecast_past_due is evaluated as of the observation period rather than today. These are non-obvious behaviors that materially change how results are interpreted.

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?

The opening paragraph is well front-loaded and the '[rule]' structure is legible, but the description is very large for a three-parameter tool, with much of the tail consisting of general portfolio-wide interpretation guidance (population scopes, signed-value conventions, lifecycle definitions) that is not specific to this call. Signal is present but diluted.

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?

An output schema exists, so return values need not be explained, and the description nevertheless supplies everything an agent needs to query correctly: identifier selection, grain, deduplication expectations, and the two lens-specific column sets. Nothing essential is missing for a tool of this complexity.

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

Parameters5/5

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

Schema description coverage is 0% and all three parameters carry only bare titles, so the description must carry the burden — and it does. It defines pid as the schedule identifier, fms_id as a case-insensitive budget line key, managing_agency as a line-scoping filter, and enforces mutual exclusivity ('exactly one of pid/fms_id').

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 ('Period-by-period history for ONE project') and immediately splits the two lenses by identifier: pid selects the schedule view, fms_id the budget view. It distinguishes itself from siblings by pointing at get_project_schedule for the linked schedule lens, so an agent can tell what it returns without opening the output schema.

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 explicit invocation constraints — 'Provide exactly one of pid/fms_id' — and explains that managing_agency scopes a multi-agency FMS id to a single line. It also states the grain to use per question type (schedule=PID, budget=budget line). It stops short of telling the agent when to prefer this tool over get_project_schedule/get_project_budget, so it is clear context without explicit exclusions.

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

Deploy Server