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

Annotations already cover the read-only/idempotent/non-destructive profile, so the description earns credit for adding auth context ('no PIN required') and a real behavioral boundary (wallet-scoped lookup only). It does not, however, discuss rate limits, pagination, or any failure modes beyond that.

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?

Well front-loaded: the core action and accepted identifier forms come first, then status semantics, then the usage routing sentence. It is slightly dense with parenthetical asides but no sentence is truly wasted.

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 by describing the status vocabulary in plain terms, including refund state. Combined with the wallet-scope and no-PIN notes, an agent has everything needed to call and interpret this 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 both parameters are already documented, including the api_key OAuth omission rule. The description's restatement of the reference formats (0x… hash or request id) largely duplicates the schema and adds no new syntax or validation detail, so the baseline 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 concrete verb and resource ('Look up one payment by its reference') and enumerates the possible outcomes (delivered, confirming, failed, refunded), so the agent knows exactly what comes back. It is clearly separable from sibling tools like pay_bill and transaction_history.

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 routes the agent: 'Use this instead of paying again when a pay_bill result was lost,' naming the alternative and the triggering condition, which is precisely the ambiguity an agent faces here. It also states a scope constraint ('Only finds payments made by the linked wallet') that rules out cross-wallet lookups.

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