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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral context: a five-year recency ceiling, no real-time data, a null-is-missing-never-zero convention, and an independence caveat. These are the kinds of data-semantics disclosures that prevent an agent from misinterpreting values.

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?

Six short front-loaded statements, each delivering a distinct fact about scope, sourcing, recency, output, null handling, and verification status. No sentence is redundant.

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 3-parameter read tool with no output schema and 0% schema coverage, the description covers output contents (units, definitions, producers, footnotes, provenance), recency, and null semantics. The only real gap is the undocumented language parameter.

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 description carries the burden. It compensates well for indicator by naming the same three metrics as the enum, and for country by pointing at three-character codes via list_countries, but the language parameter (en/fr) is never mentioned or explained.

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 the specific resource (annual population, GDP in current USD, CPI inflation) and its provenance (World Bank WDI, worldwide economies), so an agent knows exactly what data this returns. It does not name the retrieval verb explicitly and differentiates only from list_countries, not from get_record or catalog.

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 useful operating constraints ('Five completed years only, not real-time') and routes code lookup to list_countries, which is implied guidance. It never states when to choose this over get_record, get_evidence, or catalog, so the sibling selection guidance is incomplete.

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