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

Annotations only declare readOnlyHint and openWorldHint; the description adds the material facts an agent cannot infer: a $0.001 USDC charge per successful call, the x402 payment rails (Base, Solana, Arc), and the crucial detail that failed calls are not billed. It also discloses coverage restrictions and explicitly names what is NOT returned, which prevents false expectations.

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?

Four tight sentences, front-loaded with the verb and resource, then coverage, then exclusions, then price. The duplicated ISO examples are minor waste, and the clause 'since no free source for them was used' is justification rather than operational information, but neither is costly.

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 two-parameter lookup with an output schema, an existing schema that fully documents inputs, and read-only annotations, the description covers everything else an agent needs: coverage limits, excluded output fields, data source, and the paid-call economics including the no-charge-on-failure guarantee. Nothing material is missing.

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 100%, with both parameters documented including ISO examples and the 2–12 character postal-code range. The description repeats the same ISO examples ('US, DE, TR, GB') but adds no format, normalization, or edge-case guidance beyond the schema, so the baseline of 3 applies.

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 (resolves) and resource (postal code in one country) and enumerates exactly what is returned: place names, state/province, latitude and longitude. The upstream source (Zippopotam.us) is named, so an agent knows precisely what data lineage to expect and can distinguish it from any sibling in this large, unrelated tool set.

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?

Explicitly scopes applicability with 'Covers only the countries that service publishes' and rules out use for time zone or administrative municipality lookups. That is strong negative guidance, but there is no explicit statement of when to reach for this versus a geocoding alternative (none exists among siblings), so it stops short of the top band.

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