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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description then adds genuinely useful non-annotation context: newest-first ordering, English field translation with units, the year-to-date cumulative convention for GDP, the basis_status "unresolved" fallback instead of guessing, and data_as_of. That is strong added value, but it omits pagination, rate limits, latency, and error behavior for bad indicator/series names beyond one mention.

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?

Despite being long, the description is front-loaded with what the tool returns, then the ordering behavior, then the source routing, then caveats. Every clause carries information an agent needs (indicator semantics, ordering, basis_status, route differences) and nothing is repeated from the schema fields verbatim.

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?

No output schema exists, so the description must explain returns, and it does: latest period first with a period label like "2026-09", then up to periods of history newest-first, every field translated to English with unit and index convention. It also covers the direct-route extras (period type, measure, base, data_as_of, basis_status) and the auth situation (keyless), leaving no major gap for a read-only multi-indicator 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 100%, so the baseline is 3; the description nonetheless adds meaning the schema does not carry, such as cpi being split national/urban/rural with y/y and m/m, pmi covering manufacturing plus non-manufacturing, GDP being published as YTD cumulative by sector, and money_supply being M0/M1/M2 outstanding plus growth. It also clarifies that the direct route adds extra indicator and region dimensions. It does not add anything beyond the schema for parameter formats or defaults like periods range.

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 (China NBS headline macro indicators) with a concrete verb of returning them, and enumerates the nine indicators (cpi, ppi, pmi, gdp, etc.) so an agent knows exactly what data set is behind it. It is clearly distinguishable from siblings like china_lpr, china_rates and china_house_prices, which cover narrower or different subjects.

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 concrete routing guidance: default to the republisher route, and pass source: "nbs" when typed series, provincial regions, urban_unemployment or capacity_utilization are needed. It also lists the kinds of questions it answers ("China's latest CPI", "China PMI history"). It stops short of explicitly naming sibling tools to use instead for LPR, rates or house prices.

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