Skip to main content
Glama
WillHsiaoNYC

NYC Open Data Capital Projects MCP Server

by WillHsiaoNYC
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

schedule_changes

Read-onlyIdempotent

Identify newly completed or delayed NYC capital projects between two reporting periods, optionally scoped by agency and role, to compare project timeline shifts.

Instructions

Newly completed (DR1) or newly delayed projects between two periods. agency scopes to one agency; agency_role ('auto'|'sponsor'|'managing') picks owner vs builder lens.

Interpretation rules:

  • [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.

  • [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.

  • [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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
agencyNo
to_periodYes
agency_roleNoauto
change_typeYes
from_periodYes
include_cancelledNo

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
changesYes
provenanceYes
interpretation_rulesYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.1.1
    • addedInput schema / properties / agency_role / enum
      Added value: +[
+  "auto",
+  "sponsor",
+  "managing"
+]
    • addedInput schema / properties / change_type / enum
      Added value: +[
+  "completed",
+  "delayed"
+]
    • 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": {
+    "changes": {
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "title": "Changes",
+      "type": "array"
+    },
+    "interpretation_rules": {
+      "items": {
+        "$ref": "#/$defs/InterpretationRule"
+      },
+      "title": "Interpretation Rules",
+      "type": "array"
+    },
+    "provenance": {
+      "additionalProperties": true,
+      "title": "Provenance",
+      "type": "object"
+    }
+  },
+  "required": [
+    "provenance",
+    "interpretation_rules",
+    "changes"
+  ],
+  "title": "ChangesResult",
+  "type": "object"
+}
  2. First observedv0.1.0

TDQS

C2.8/5.0
Behavior4/5

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

Annotations cover readOnly/idempotent, so the bar is lower, and the description adds substantial non-redundant behavior: period aggregates default to the latest complete snapshot, NULL milestones are not necessarily missing, forecast_past_due is evaluated as of the observation period, and budget spend%=100 does not prove completion. These are genuinely useful semantics beyond the annotations. It does not describe the return shape, but that is expected with an output schema present.

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

Conciseness2/5

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

The description is very long relative to a 6-parameter tool and front-loads only the first sentence; the interpretation rules read as internal documentation rather than agent-facing guidance, with bracketed labels and dense prose that a caller cannot always act on. Several rules (semi-join to fms_sponsor, co-owner overlap) are data-model trivia rather than call-instruction.

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?

There is an output schema, so return values need not be explained, and the period/lifecycle/agency semantics are unusually thorough. However, the tool does not clarify which fields are returned for the two change_type modes or give the period string format, leaving moderate gaps for a tool that is otherwise heavily annotated with interpretation rules.

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 compensate, and it does for agency ('scopes to one agency'), agency_role (defines 'auto'|'sponsor'|'managing' as owner vs builder lens and explains sponsor defaults) and change_type (completed/delayed via 'Newly completed (DR1) or newly delayed'). from_period/to_period are left without format guidance, and include_cancelled and the DR1 designation are not explained, keeping it from a 5.

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

Purpose2/5

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

The opening sentence does state the resource and scope: 'Newly completed (DR1) or newly delayed projects between two periods,' which maps change_type to a project set. However, the tool name is 'schedule_changes' while the description's first clause is about project completion/delay classification rather than schedule change magnitude. The bulk of the description is dense interpretation guidance that does not further clarify what the tool returns; the purpose is not clearly distinguished from siblings like schedule_breakdown, budget_change, or delay_reason_stats.

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

Usage Guidelines2/5

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

There is no explicit 'use this tool when...' statement nor any mention of sibling alternatives. The interpretation rules imply analytic usage but never name an alternative or exclusion. An agent must infer when to call this versus schedule_breakdown or rank_projects.

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