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

Annotations already cover read-only/idempotent safety, and the description adds substantial behavior the annotations cannot: dedup requirements, non-additive category counts, the latest-complete-snapshot default for periods, and role-aware agency attribution. These are exactly the traits that prevent miscounting.

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

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

The first sentence is tightly front-loaded and earns its place, but the 'Interpretation rules' block is a dense wall of text that folds in cross-cutting grain, schedule/PID, and category rules beyond this tool's core scope. Useful, but oversized and hard to parse at a glance.

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

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

An output schema exists, so return formatting need not be described, and the remaining complexity (grain, dedup, roles, period basis, categories) is thoroughly addressed. An agent has enough to call and correctly interpret the result.

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

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

With 0% schema coverage the description carries the burden, and it covers most params: agency ('scopes to one agency'), agency_role ('owner vs builder lens'), group_by ('by managing_agency or category'), and period via the period_basis rules. metric's two values (total_budget/spend) are only implied by the opening wording rather than defined, so full compensation is slightly incomplete.

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

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

The opening sentence states a specific verb+resource ('Total budget / spend by managing_agency or category, deduped on (fms_id, managing_agency)') and even names the grouping grain, so an agent knows exactly what it returns. It routes to run_sql for richer cuts, but does not explicitly distinguish itself from the sibling schedule_breakdown, which the near-identical name makes risky.

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

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

It gives explicit alternative routing ('For richer cuts use run_sql') and clear when-not guidance ('fms_location, fms_sponsor and lifetime_budget_variance... use them for enrichment or lifetime figures, never as a single period's inventory'). It also states which lens to pick via agency_role and the semi-join rule for sponsor-scoped totals, leaving little to inference.

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

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.

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.

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.

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.

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.

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.

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

Annotations already declare readOnly, idempotent, closed-world, so the description adds substantial value by disclosing that this is local-only metadata rather than an upstream check and that the latest period may precede a partially published snapshot. That is genuine behavioral context about data staleness and scope that annotations don't cover.

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

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

Front-loads the summary line then two long bullet rules, which is reasonable, but the prose is dense and the rules are somewhat run-on, mixing several concepts per sentence. It is not excessively long but could be more scannable.

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

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

Given zero parameters, a rich output schema (so return format needn't be re-explained), and annotations covering safety, the description fills the remaining gap: how to interpret freshness and period basis. It is complete for the call itself, though it doesn't tie usage to specific sibling tools.

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

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

No parameters, so the schema carries nothing and the description correctly focuses on output semantics. It describes the freshness and period_basis caveats that shape how returned values should be interpreted, which is appropriate use of the space.

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

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

States a specific resource (per-dataset metadata) and enumerates what it returns (freshness, period, row counts, caveats). It's clearly distinct from sibling tools like describe_table or run_sql, though the phrasing 'Per-dataset' isn't further elaborated on what a dataset is.

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

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

The interpretation rules imply when to use the returned periods ('use them for enrichment or lifetime figures, never as a single period's inventory') and warn it is local metadata, not an upstream freshness check. But it never explicitly states when to call dataset_info versus alternatives in the sibling list, nor gives a directive like 'call this before any aggregation'.

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

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

Annotations already declare readOnly/idempotent/closed-world, so safety is covered. The description adds genuine behavioral detail beyond them: the coverage block contents with denominators, the variance_day>0 population rule, and the agency_role lens. It stops short of disclosing edge behavior like empty distributions or default period resolution timing, but adds meaningful context.

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

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

The tool's own description is front-loaded well, but the appended 'Interpretation rules' block is a large generic preamble covering reporting periods, agency roles, schedule coverage, and signed values that applies broadly across the toolkit rather than this tool. It buries the specific tool semantics and hurts scannability.

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

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

It provides the coverage block and enum behavior, and an output schema exists so return shape need not be explained. Yet for a tool whose core is a distribution, it omits what the aggregation is keyed on and leaves the 'period' and 'agency' parameters unexplained, so an agent still has gaps before calling correctly.

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

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

Schema description coverage is 0% across 4 parameters, so the description must carry the burden; it explains scope ('all_history' for lifetime, default current) and agency_role enum behavior ('auto'|'sponsor'|'managing' picks owner vs builder). It says nothing about the 'period' or 'agency' parameters, so half the params remain undocumented.

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

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

States a specific resource (distribution of reason-for-delay) and scope behavior. It establishes what is being counted, but without a title and amid many aggregate stats siblings, differentiation from tools like schedule_breakdown or budget_breakdown relies on inference. Purpose is clear but sibling differentiation is thin.

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

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

It states a usage condition ('only populated when variance>0') and the scope switch for all_history, which is real guidance. However, it never names when to prefer an alternative (e.g. schedule_changes) or when this distribution is not the right lens, leaving the routing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and closed-world, so the safety profile is covered. The description adds output content and confirms both filters are optional, but discloses no behavioral traits an agent needs at call time (result size, pagination, truncation, whether an unknown field name errors or returns empty). The long 'Interpretation rules' block is domain guidance about the underlying data, not behavior of this tool.

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

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

The opening paragraph is tight and front-loaded. But roughly 80% of the text is an 'Interpretation rules' section about data grain and project lifecycle that is tangential to invoking a two-parameter dictionary lookup and reads like reused domain context rather than tool documentation.

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

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

With an output schema present, return values need no explanation, and the description covers purpose, both filters, and the no-filter default. An agent can call this correctly from what is given; the surplus interpretation rules neither help nor hurt completeness for this specific tool.

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

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

Schema coverage is 0% and neither parameter is documented in the schema, so the description must carry the load — and it does: `field` accepts a column name or display name, `dataset` accepts a RAW table name or socrata_id, and both being omitted returns the full dictionary. That adds real meaning beyond the bare schema, though case-sensitivity and partial-name matching rules remain unstated.

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

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

Names a specific verb+resource ('describe_field' -> official field definitions / NYC Open Data data dictionary) and enumerates exactly what is returned: description, allowed values, primary/foreign key, limitations, notes. This is clearly distinguishable from siblings like describe_table and dataset_info, which cover whole tables/datasets rather than individual columns.

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

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

The description states how to scope the call ('Filter by `field` ... and/or `dataset` ... omit both for the full dictionary'), which is genuine usage guidance for the parameters. However it never says when to reach for this tool versus describe_table, dataset_info, or run_sql, so alternative selection is left to inference.

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

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.

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.

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.

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.

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.

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.

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

Adds far more than the readOnly/idempotent annotations: budget has no 'completed' state and spend%=100 does not prove completion, NULL milestones need not be missing, forecast_past_due is evaluated as of the observation period, and changes are strictly signed. It also warns that the combined source repeats rows and must be deduplicated before counting.

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

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

The purpose sentence is well front-loaded, but the body is roughly 2,000+ characters of dense, undifferentiated prose whose numbered categories read like a data dictionary rather than tool-specific usage. Substantial material (lifecycle phases, signed-value conventions) would serve better as shared reference documentation.

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

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 described, and the description thoroughly covers grain, population scope, baseline basis, and lifecycle caveats. The only real gap is parameter-level detail (managing_agency optionality and identifier format) left uncovered by a 0%-documented schema.

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

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 the parameter burden. It does clarify that (managing_agency, fms_id) jointly define the budget line and that the same FMS ID under different holders is a distinct line, but it never states fms_id's format or that managing_agency is optional and defaults to null.

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

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

The opening clause states a specific verb and resource: 'Budget (FMS line): total, spend, variance; lists linked schedules.' The [grain] rule explicitly separates it from schedule siblings by keying budget questions on (managing_agency, fms_id) while schedule questions use PID. It is clear but the crisp purpose statement is buried under a large block of interpretation rules.

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

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

Gives substantial situational guidance: default population_scope='latest_known' vs 'current', which key to use for which question grain, and instruction to list ALL linked counterparts rather than silently picking one. It never names sibling tools (budget_breakdown, budget_change) as alternatives, so it stops short of explicit routing.

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

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.

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.

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.

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.

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.

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.

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

Annotations already establish readOnly/idempotent/closed-world safety, so the bar is low, yet the description adds substantive behavior: forecast_past_due is evaluated as of the observation period (never for completed/cancelled), attributed_budget double-counts shared funding, and schedule totals use dashboard-aligned schedule_history. This is meaningful context beyond the annotations, though nothing on rate limits or pagination.

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

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

It is front-loaded with purpose and organized under bracketed headers ([relationships], [population], [lifecycle]), which aids scanning. However for a single-parameter read tool the volume is heavy and much of it reads as cross-cutting boilerplate likely shared across many sibling tools rather than tool-specific value.

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

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 re-explained, and the description instead supplies the interpretive domain context (lifecycle phases, funding basis, location inheritance) an agent needs to read the results correctly. It is close to complete for this tool's complexity, with the pid format being the main omission.

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

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

Only one input (pid) at 0% schema coverage, so the description must compensate. It does clarify PID identity in [relationships] ('PID identifies a SCHEDULE; FMS ID identifies a BUDGET'), which partly compensates, but it never states the pid format or expected value, and the population_scope referenced in the text is not actually in this schema.

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

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

The opener 'Schedule (PID): phase, lifecycle, signed variance, reason; lists linked budgets' states the resource and the main returned fields, so an agent knows this retrieves schedule state for a PID. It does not, however, explicitly distinguish itself from close siblings like schedule_breakdown, schedule_changes, or get_project_budget, so an agent still has to infer the boundary.

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

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

The interpretation rules convey how to use the output (state population_scope, report signed changes, don't trust attributed_budget as a project cost), which is real usage guidance. But there is no explicit when-to-use-this-vs-siblings statement, so tool selection among schedule_breakdown/schedule_changes/get_project_budget is left to inference.

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

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

Annotations already establish that this is a read-only, idempotent, closed-world tool. The description adds substantial behavioral context beyond that: how presence is determined, that there is no active flag, that historical presence is not current presence, and that role attribution and co-owner totals have non-obvious semantics.

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

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

The description is front-loaded and labeled with bracketed rules, but it is dense and jargon-heavy for a one-parameter dictionary tool. Many sentences carry useful domain caveats, though some could likely live in output schema documentation instead of invocation guidance.

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

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

An output schema exists, so return field structure need not be described. The description supplies rich domain semantics for interpreting results, but it completely omits the 'contains' parameter and offers no guidance on when to use this tool over related tools, leaving invocation context incomplete.

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

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

The input schema has one parameter, 'contains', with 0% schema description coverage, and the description never mentions it. No meaning, expected format, or filtering behavior is provided for the only invocation parameter.

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

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

The opening sentence identifies the resource as an 'Agency dictionary' with two specific returned fields: live CPD presence and a schedule-executor flag. That is more specific than a generic list tool, though the acronym CPD is unexplained and the description does not explicitly contrast the tool with siblings beyond domain notes.

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

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

The description gives extensive interpretation rules for returned data, but it does not explicitly say when to call list_agencies versus alternatives such as run_sql, dataset_info, or list_categories. The semi-join note is about downstream SQL usage, not about when this MCP tool should be selected.

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

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

With readOnlyHint/idempotentHint already covering the safety profile, the description still adds real behavioral context: categories are derived from specific fields, schedule counts are non-additive (a PID can appear in multiple categories), and rows must be deduplicated at the requested grain. These are non-obvious traits an agent could not infer from annotations or schema.

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

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

Purpose and routing are front-loaded, which is good. However, the dense interpretation-rules block runs long, mixing grain, period-basis, and category-derivation guidance into one tool entry; some of it reads as dataset-wide rules that could sit elsewhere, diluting scannability.

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

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 compensates by covering grain, category derivation, and period-basis caveats. It is largely complete for a no-param enumerator, though the volume of interpretive rules suggests some complexity is pushed onto the reader rather than resolved.

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

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

The tool takes zero parameters, so the schema carries no parameter semantics and the baseline is 4. The description instead spends its detail on grain and filtering conventions, which is appropriate for a parameterless enumerator.

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

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

The opening names a specific resource (program/facility categories) with concrete examples and states the returned data (budget-line counts and total budget). The routing line 'Use a category name as the category filter on rank_projects' cleanly separates this from sibling lookup tools.

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

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

It gives explicit context by naming the downstream consumer ('Use a category name as the category filter on rank_projects'), which implies when this tool is the right first step. It does not explicitly exclude alternatives like describe_table or list_agencies, so it stops short of full when-not guidance.

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

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.

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.

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.

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.

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.

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.

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

Annotations only cover safety (readOnly, idempotent, non-open-world; no destructiveHint). The description goes far beyond that, disclosing double-counting semantics of attributed_budget, that summary covers the FULL filtered set under two budget bases, the forecast_past_due definition, multi-borough matching, signed-value reporting conventions, and suppression rules for milestones. This is unusually deep behavioral disclosure for a read-only tool.

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

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

The purpose and parameter semantics are front-loaded effectively, but the body is nine dense interpretation blocks, much of which reads as dataset-wide doctrine rather than tool-specific guidance, and some of it restates itself (population_scope and presence are covered across three separate blocks). Justified by complexity, yet well past the point where every sentence clearly earns its place.

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

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 enumerated, and the description still identifies the key returned fields (schedule state, attributed_budget, forecast_past_due, reporting_period, current-snapshot presence). Given 9 parameters, 0% schema coverage, and a highly relational domain (PID vs FMS ID many-to-many), the interpretation rules close the gaps an agent would otherwise hit.

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

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

Schema coverage is 0%, so the schema contributes no meaning at all and the description must carry it. It explains borough (matches the PID's boroughs LIST, Citywide/Multiple precedence), category_scope, population_scope, agency + agency_role lens, and lifecycle_status enum values, but leaves 'community_board' as a bare filter name and says nothing about 'n' (row cap, max 500).

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

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

The first clause states a specific verb+resource ('Cross-section listing of projects (PIDs)') and enumerates the exact filters the agent can apply. It explicitly routes the reader elsewhere for enumerations ('see list_categories', 'list_agencies exposes is_schedule_executor') and implicitly contrasts with 'Detail tools' used for single-anchor lookups, so it is distinguishable from siblings such as rank_projects and get_project_schedule.

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

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

Rich contextual guidance: it names default population_scope, when to switch to 'current', the two category_scope modes, and how to obtain distinct totals (summary.line_budget_total vs summing attributed_budget). What it does not do is say explicitly when to choose this tool over rank_projects or schedule_breakdown, so the when-to-use-vs-sibling story is inferred rather than stated.

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

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

Annotations already declare readOnly/idempotent, so safety is covered. The description adds rich behavioral context (echoes ranked_entity, forecast_past_due semantics, population/presence rules), but this is extended interpretation content rather than the tool's own operation-level behavior.

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

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

The core operation is front-loaded but is immediately followed by a very long interpretation-rules block with many relationship/grain/presence nuances that go beyond invocation guidance. It is information-dense but not tightly scoped to the call.

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

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

Given 12 params, no schema descriptions, and an output schema present, the description covers the critical rank_by and scope semantics well. Some under-documented filters and the extensive interpretation rules leave minor gaps.

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

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: it defines rank_by options per entity, category/agency/agency_role/agency_scope semantics, population_scope, and category_scope. Several filters (n, direction, delayed_only, min/max_total_budget) remain only briefly covered.

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

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

States specific verb (rank) and resources (schedules/budgets by PID/FMS lines) and distinguishes entity modes for schedule vs budget. Sibling differentiation is implicit (e.g., vs schedule_breakdown/budget_breakdown) but not named, so it stops short of a 5.

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

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

Explains when to use each entity, population_scope, and category_scope, and clarifies rank_by must be native to the entity with the other domain filter-only. No explicit alternatives/exclusions, so not a 5.

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

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

Annotations already declare readOnly, idempotent, and closed-world behavior, but the description adds substantial domain behavior beyond that: PID vs. FMS ID ambiguity, many-to-many funding relationships, deduplication requirements, and presence semantics. This is exactly the kind of interpretation context that prevents misuse.

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

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

The first sentence front-loads the purpose and scope, and the bracketed interpretation rules are structured rather than rambling. It is long for a tool definition, with some repetition of the many-to-many point, but nearly every sentence carries actionable domain guidance.

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

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

Given the tool's high ambiguity (identifier resolution across schedules and budgets), the description supplies extensive interpretation rules that an agent needs to call it correctly. The existence of an output schema reduces the need to describe return values, and annotations cover the safety profile, so the remaining gaps are minor.

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

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. It explains the 'query' parameter accepts PID, FMS ID, name, or partial, and mentions pagination via next_offset, but it never explains what 'limit' or 'offset' control in this specific tool, leaving the parameter semantics partially covered.

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

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

The description states a specific verb (resolve) and resource (project identifier) and explicitly names its role: 'Call this first for any named-project question.' It distinguishes itself from sibling detail tools by clarifying that matches identify candidate entities rather than funding relationships, so an agent can tell it apart from get_project_schedule/get_project_budget without opening schemas.

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

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

It gives explicit routing guidance: call this first for named-project questions, then inspect linked_budgets/linked_schedules via detail tools. It also covers when to preserve multiple candidates, when to follow pagination, and when to disclose truncation, leaving little to inference.

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

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

Annotations (readOnlyHint=false, idempotent=false, destructive=false) are consistent with the disclosed side effect that 'csv'/'xlsx' 'writes a file, returns path'; the description reconciles the 'read-only SELECT' claim with that file write rather than hiding it. It also adds behavior annotations do not carry: rows are capped inline, truncation_note is echoed, latest_reporting_period/period_basis_note may be returned, and results can be truncated so CSV/XLSX should be used for full output.

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

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

Front-loaded correctly (purpose, then output modes, then preferred tables, then rules), but the body is a very large wall of text. Long stretches on lifecycle phases, location inheritance, presence semantics and category rules are domain knowledge that applies to many sibling tools, not to invoking run_sql, and dilute the actionable SQL-authoring guidance.

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

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

An output schema exists, so return-value documentation is not needed, and the description instead concentrates on the things an agent cannot infer: table grains, many-to-many PID/FMS linkage, period and population bases, funding double-counting, and the requirement to disclose truncation, population_scope and period basis. For a raw-SQL escape hatch this is about as complete as it can be.

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

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 both params. It fully explains the `output` enum (inline default with capped rows, csv, xlsx writes a file and returns a path), which is the one param with non-obvious behavior. The `query` param is a raw SQL string, so there is little semantic surface left, but the description compensates with grain/cast guidance ('Raw mirrors are all VARCHAR').

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

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

Opens with a specific verb+resource+constraint: 'Run a read-only SELECT against the local CPD DuckDB.' It also distinguishes itself from the many siblings by stating 'Prefer purpose-built tools for supported questions' and naming describe_table/describe_field as the SQL-authoring helpers, so an agent can tell it apart from get_project_budget, budget_breakdown, etc.

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

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

Gives explicit routing rules: prefer purpose-built tools for supported questions, fall back to run_sql for 'custom SQL', consult describe_table for grain/keying and describe_field for definitions, and prefer typed tables over RAW VARCHAR mirrors. It even states the boundary of its own guarantee ('enforces read-only access, not correct analytical grain').

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

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

Despite readOnlyHint/idempotentHint covering safety, the description adds substantial behavioral context: non-additive category counts, deduplication requirements at entity grain, signed variance direction conventions, defaulting to latest complete snapshot, and the distinction between schedule_history and source_schedule_history. This goes well beyond the annotations and is rich enough for a high score.

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

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

The description is very long with a dense block of interpretation rules that resembles internal documentation rather than tool-selection guidance. Critical scoping information is buried after the opening, and the bulk of the rules concerns data-model semantics that are not strictly needed before invoking the tool.

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

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

The tool has an output schema and rich annotations, but the description still supplies enough grain, period, and categorization semantics to call the tool correctly. It does not document the underlying data sources for the caller to reconcile beyond what it provides, leaving minor gaps for the six-parameter surface.

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

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

Schema description coverage is 0% and six parameters are undocumented in the schema, so the description must compensate. It does so for several key parameters — agency_role values and auto-routing rules, period defaulting to latest snapshot, and the non-additive behavior of category grouping. It does not clarify the metric/statistic enum semantics (e.g., what 'sum' means on a variance field), leaving a gap.

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

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

States specific verb (counts/averages) and resource (schedule metrics) plus the grouping dimensions for the scheduled breakdown. It is nearly indistinguishable in framing from the sibling budget_breakdown, but the schedule-metric focus and the explicit group_by dimensions differentiate it adequately for selection.

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

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

The interpretation rules give extensive when-to-use context (segment grain, period basis, agency roles, category behavior), effectively telling the agent which analytical framing to apply. However, there is no explicit routing to siblings like budget_breakdown or rank_projects, so the agent must infer when this tool is preferable to alternatives.

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

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.

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.

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.

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.

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.

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.