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

Annotations already cover the safety profile (readOnlyHint, openWorldHint, destructiveHint=false), yet the description adds substantial non-obvious context: per-call pricing ($0.0025 USDC), the x402 in-band payment mechanism and supported chains, automatic payment for x402 clients, and a free sample call. These are exactly the operational facts an agent needs before invoking a paid 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 purpose and coverage, then parameters, then pricing, with no filler sentences. The x402 payment paragraph is comparatively long, but it is decision-relevant information rather than padding, so the density is acceptable.

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 no output schema, the description carries the return-value burden and does so: it states that results are place names, state, and coordinates, or the full set of postal codes for a city+state input. Combined with the coverage caveat for GB/CA/IE and the pricing/sample details, an agent has everything needed to call it 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 50% (city and postal_code are undocumented in the schema), and the description compensates by naming all four parameters, flagging country as required and ISO2, clarifying state as an abbreviation, and — critically — disclosing the either/or relationship between postal_code and city+state that the schema does not express. It lacks format examples for city/postal_code beyond the single sample input.

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 ('Postal codes for 70 countries') and describes both resolution directions: postal code to place names/state/coordinates, and city+state to all postal codes. The data source (GeoNames via zippopotam.us) and country coverage are named, so it is clearly distinguishable from generic geocoding siblings.

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 the two valid input modes ('postal_code' OR 'city + state') and the country-specific limitation ('For GB, CA and IE only the outward part... is resolved'), which guides invocation well. It stops short of naming when to prefer this over a sibling like geocode, so it is clear context without explicit alternatives.

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