NYC Open Data Capital Projects MCP Server

Overview Schema Source Related Servers Discussions Admin

describe_table

Read-onlyIdempotent

Retrieve live column schemas, types, grain, and keying notes for a DuckDB table, or catalog all queryable tables, to write correct SQL without blocked DESCRIBE/SHOW.

Instructions

Schema catalog for every queryable DuckDB table (typed analytics tables, dims, raw mirrors): live columns + types plus curated grain and keying notes. No arg → catalog of all tables; table= (case-insensitive) → full detail. Use this instead of DESCRIBE/SHOW (blocked in run_sql). Complements describe_field (official field semantics for the 4 raw datasets).

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.
[sql_usage] Prefer purpose-built tools for supported questions. For custom SQL, use describe_table for grain/keying and describe_field for field definitions, then prefer typed tables. Raw mirrors are VARCHAR and need casts. run_sql enforces read-only access, not correct analytical grain: the caller must prevent join fan-out and choose the period/population. Disclose truncated results; use CSV/XLSX for the full result when needed.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`table`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`table`	No
`tables`	No
`columns`	No
`provenance`	Yes
`interpretation_rules`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.1.1Sep 12, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already cover readOnly/idempotent, but the description adds real context beyond them: run_sql enforces read-only access but not analytical grain, the caller must prevent join fan-out, period aggregates default to a latest complete snapshot, and truncated results must be disclosed with CSV/XLSX fallback. This is genuinely non-obvious operational behavior.

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?

Purpose and both calling modes are front-loaded in the first two sentences, which is exactly right. The trailing 'Interpretation rules' block is long and includes domain guidance (e.g. 'Never compare budgets using fms_id alone') that is only indirectly about describing tables, though it is clearly labeled and structured.

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 needn't be spelled out, and the description instead supplies the grain/keying semantics, period-basis rules, and SQL-usage constraints an agent needs before trusting the catalog for custom queries. Nothing essential is missing.

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 coverage is 0%—the single 'table' property has no description—so the description carries the full burden and does: omitting the arg yields a catalog of all tables, and passing table=<name> (case-insensitive) yields full detail. That fully compensates for the empty schema.

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+resource ('Schema catalog for every queryable DuckDB table') and enumerates both modes ('No arg → catalog of all tables; table=<name> → full detail'). It also names the sibling it complements (describe_field) and the tools it substitutes for (DESCRIBE/SHOW blocked in run_sql), so an agent can tell it apart without opening a schema.

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

Usage Guidelines5/5

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

Explicit direction on when to use it: 'Use this instead of DESCRIBE/SHOW (blocked in run_sql)', 'Complements describe_field', and 'prefer typed tables' for custom SQL. It names alternatives and the conditions that select them (raw mirrors are VARCHAR and need casts).

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

Deploy Server