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

The description does add real behavior beyond annotations: funds go to the payer, and refunding an OPEN escrow acts as a cancel rather than a transfer. But "(exactly-once)" asserts a retry-safe guarantee that conflicts with the supplied idempotentHint=false, creating a conflicting signal about whether a retried call double-refunds. Permissions, failure modes, and what happens to a DISPUTED escrow are also unstated.

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?

Two short sentences, zero filler, with the state constraint and the payer direction front-loaded before the OPEN-as-cancel nuance. Every clause carries information an agent would otherwise have to guess.

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?

An output schema exists, so return values need not be explained, and the destructive nature is covered by annotations. Still missing for a destructive, non-idempotent money-movement tool: authorization requirements, the DISPUTED-path behavior, and any parameter documentation at 0% schema coverage.

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 0% for both parameters, and the description says nothing about escrow_id or reason, so neither field's format or expected values is clarified anywhere. The eligible-state list marginally informs which escrow_id values are valid, but that is far short of compensating for the coverage gap.

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?

"Refund ... escrow to the payer" names a specific verb, resource, and money direction, and enumerates the eligible states (OPEN/FUNDED/DISPUTED), which is more than the title conveys. It does not explicitly differentiate itself from siblings like release_escrow or dispute_escrow, so an agent must infer that release pays the payee rather than the payer.

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?

The state list (OPEN/FUNDED/DISPUTED) implicitly defines when the tool is applicable and implicitly excludes other states such as RELEASED or already-REFUNDED. However, no alternative tool is named and no explicit when-not guidance is given, so routing versus release_escrow or dispute_escrow 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.