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

No annotations are provided, so the description carries the full burden — and it is exceptional: it discloses NULL handling ("SKIP NULLs and NULL means SUPPRESSED not zero"), the true population-weighted SUM(numerator)/SUM(denominator) semantics of weighted_rate versus avg's per-row rates, NULL sort placement ("sort LAST in either direction"), and output behaviors like aggregation_scope flagging source-published vs recomputed grains with coverage diagnostics so suppression is visible.

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 with purpose, then moves through agg semantics, shared-parameter cross-reference, output shape, and interpretation warnings. Every sentence earns its place — param semantics, weighted_rate vs avg, NULL behavior, aggregation_scope, and the allowlisting constraint are all non-redundant. The density is justified by 14 params and 0% schema coverage.

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?

For a 14-param tool with no annotations and a bare schema, this is complete: it covers all functional parameters, output structure (even exceeding the requirement since an output schema exists), interpretation of suppression, and the security model ("No raw SQL: all identifiers are contract-allowlisted"). Cross-references to describe_dataset, query_dataset, the advisory, and the contract give the agent precise next steps. Only main_topic and limit/offset are left implicit, which is acceptable.

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 is the sole source of parameter meaning and it compensates thoroughly: it enumerates all agg values, explains weighted_rate's formula, states that metric "DEFAULTS to the topic key_metric; ignored for count", defines group_by grain types with concrete FK examples (district_code, county_fips), and specifies order_by/order usage including 'value' and NULL ordering. Pagination params (limit/offset) are left implicit but are standard.

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?

"Compute a grouped aggregate over one topic — the aggregation-first path" names a specific verb (compute), a resource (grouped aggregate), and a scope (one topic). The "aggregation-first path" phrasing positions it against sibling query_dataset, and the detailed agg/group_by semantics make it clearly distinct from describe_dataset, distinct_values, and query_dataset.

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 rich routing guidance: "prefer it over `avg` for a rate across multiple places/years", "prefer source-published — see the advisory", and "Supports the same filters/year/year_min-year_max/detail as query_dataset", which cross-references the sibling and reuses its parameter semantics. However, it never states an explicit when-not-to-use rule against query_dataset (e.g., "use query_dataset for raw rows"), so it earns 4 rather than 5.

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