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

Annotations already cover the safety profile (readOnly, non-destructive, open-world, non-idempotent), and the description adds real context on top: the exact cost, that unpaid calls return isError with a fresh invoiceId, and the two accepted payment channels. The fresh-invoiceId behavior is consistent with idempotentHint=false. It stops short of describing the success payload's shape.

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?

The payment terms are stated three times across the title, the first sentence, and again in the parameter schema, while the actual lookup purpose appears mid-sentence. It is dense and information-rich but poorly front-loaded relative to what an agent needs first.

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?

Payment mechanics are exhaustively covered and the tool is simple (one query parameter, no output schema), so the bar is modest. Still missing is what q actually accepts and what the successful response contains beyond 'codes and short name', which an agent needs to call it correctly on the first paid attempt.

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?

The schema documents payment_signature thoroughly but leaves the required 'q' parameter completely undescribed (50% coverage). The description only hints that q relates to 'ISO 3166-1 codes and short name' without saying whether it accepts alpha-2, alpha-3, numeric, or a country name, and whether matching is case-insensitive — a meaningful gap for the one required 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?

The description does state a specific resource and outcome: 'ISO 3166-1 codes and short name from a bundled open code table.' However, the operative verb is buried under payment boilerplate, and it never distinguishes itself from lookups like currency_code or http_status, which are near-identical in shape.

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?

Usage guidance is entirely about the payment flow (call unpaid first, receive PaymentRequired, retry with signed payload), which is genuinely useful procedural direction. It gives no guidance on when to pick this over the sibling currency_code/iban_format/mime_ext lookups, so alternative selection is left to inference.

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