NYC Open Data Capital Projects MCP Server

Overview Schema Source Related Servers Discussions Admin

project_duration_stats

Read-onlyIdempotent

Calculate duration statistics between actual design start and construction end for NYC capital projects, optionally grouped by agency, borough, or lifecycle status.

Instructions

Duration distribution between two ACTUAL milestones (requires both dates). Only forward actual_design_start to actual_construction_end is supported. Negative intervals are retained in invalid_intervals and excluded from statistics; missing-date and invalid-order counts reconcile to the full latest-known population. Optional group_by returns per-group stats instead of the citywide block.

Interpretation rules:

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

Input Schema

TableJSON Schema

Name	Required	Default
`group_by`	No
`to_milestone`	No	actual_construction_end
`from_milestone`	No	actual_design_start

Output Schema

TableJSON Schema

Name	Required	Description	Default
`stats`	No
`groups`	No
`n_projects`	Yes
`provenance`	Yes
`interpretation_rules`	Yes
`excluded_missing_dates`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv0.1.1Sep 12, 2026

addedInput schema / properties / from_milestone / enum

Added value: +[
+  "actual_design_start",
+  "actual_construction_end"
+]

changedInput schema / properties / group_by / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "enum": [
+      "managing_agency",
+      "borough",
+      "lifecycle_status"
+    ],
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / to_milestone / enum

Added value: +[
+  "actual_design_start",
+  "actual_construction_end"
+]

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": {
+    "excluded_missing_dates": {
+      "title": "Excluded Missing Dates",
+      "type": "integer"
+    },
+    "groups": {
+      "anyOf": [
+        {
+          "items": {
+            "additionalProperties": true,
+            "type": "object"
+          },
+          "type": "array"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Groups"
+    },
+    "interpretation_rules": {
+      "items": {
+        "$ref": "#/$defs/InterpretationRule"
+      },
+      "title": "Interpretation Rules",
+      "type": "array"
+    },
+    "n_projects": {
+      "title": "N Projects",
+      "type": "integer"
+    },
+    "provenance": {
+      "additionalProperties": true,
+      "title": "Provenance",
+      "type": "object"
+    },
+    "stats": {
+      "anyOf": [
+        {
+          "additionalProperties": true,
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Stats"
+    }
+  },
+  "required": [
+    "provenance",
+    "interpretation_rules",
+    "n_projects",
+    "excluded_missing_dates"
+  ],
+  "title": "DurationResult",
+  "type": "object"
+}

First observedv0.1.0Jun 13, 2026

TDQS

A4/5.0

Behavior5/5

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

Annotations cover the safe-read profile, and the description exceeds that bar substantially: lifecycle phase constraints, milestone suppression behavior, NULL semantics, forecast_past_due evaluation window, invalid_intervals handling, and population_scope reconciliation. This is unusually rich behavioral disclosure for a statistics tool.

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?

Front-loads the core behavior well, but the interpretation-rules block is dense and reads like internal analyst documentation compressed into three bracketed paragraphs. Every sentence carries substance, yet the volume is heavy for a 3-parameter stats tool and the structure is more reference-note than guidance.

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

Completeness4/5

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

Given an output schema exists, return values needn't be explained, and the description still manages to cover lifecycle phases, schedule coverage, and population_scope semantics – the key interpretive context an agent needs. References to schedule_source_coverage and invalid_intervals are dense but complete enough to call correctly.

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 0%, but the description explains the semantics of group_by (per-group stats instead of the citywide block) and the from/to milestone directionality. It doesn't explain the enum values managing_agency/borough/lifecycle_status or the observation-period interaction, so it partially compensates for the schema gap.

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?

States a specific verb+resource: duration distribution between two actual milestones, with a named constraint that only forward actual_design_start→actual_construction_end is supported. Distinct from siblings like schedule_breakdown or get_project_schedule, though it never explicitly names an alternative.

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?

Clarifies when the tool applies (requires both dates, only forward direction supported, negative intervals retained but excluded). Gives conditions and caveats but never contrasts against sibling tools like schedule_breakdown or delay_reason_stats, so the routing guidance is implicit rather than explicit.

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

Deploy Server