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

Annotations already declare readOnlyHint and destructiveHint=false, so the description's real contribution is pagination behavior: bounded stable pagination, default/max limit, and retaining dataset hashes across pages. It also discloses the return posture (units, source locators, estimates, unavailable values stay explicit), which goes beyond the annotations.

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?

Three tight sentences, front-loaded with the filter surface and followed by pagination and scope limits; no filler. Slightly telegraphic phrasing ('Retain dataset hashes across pages') costs a little readability but nothing is wasted.

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?

Output schema already documents the returned shape, so the description need not explain return values, and annotations cover the safety profile. What remains — filterable dimensions, pagination bounds and stability, and explicit scope exclusions — is all present, which is sufficient for a 9-parameter read 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?

With 0% schema description coverage across 9 parameters, the description carries the burden and largely succeeds: it names dataset, indicator, geography/geo, category, subgroup and the reference period (from/to) as filters, and clarifies the period is inclusive — a genuine semantic addition the schema's regex does not convey. Pagination parameters are also given default 200 / max 500 and cross-page stability, leaving only minor gaps such as the dataset enum values.

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 ('Filter') and resource ('published observations') plus the exact filter dimensions, which an agent can map onto the schema properties. It clearly separates itself from catalog/metadata siblings like get_market_catalog, though it names no sibling explicitly.

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 negative constraints ('No market-size aggregation, unit conversion or causal inference') tell the agent what this tool will not answer, which is useful routing signal. However, there is no positive when-to-use guidance relative to get_market_catalog or the other siblings, so the agent must infer that this is the row-level data retrieval tool.

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