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

Annotations already flag destructive/idempotent/openWorld, and the description substantially extends them: durable nonces preventing duplicate movement on retries, a 100.00 USDC/UTC-day resolution cap, operator-signature requirement, x402 fee of 0.10 USDC plus free-call allowance, expiry-refund behavior with signed timeout receipt, and a pending external audit disclaimer. This is unusually rich disclosure consistent with destructiveHint=true.

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 signature/auth requirement is front-loaded, followed by outcomes, extension rules, pricing, and expiry. It is dense and information-heavy but nearly every sentence contributes operational facts; only the fee/free-call and audit-pending clauses feel like they could be trimmed from a tool-selection standpoint.

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?

No output schema exists, yet the description covers resolution modes, extension, expiry refunds, fee model, authorization, and caps, and points to /api/dispute-contract for schemas and recovery limits. For a 9-parameter destructive tool this is nearly complete, lacking only explicit per-parameter detail.

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 only 11% (just reason_uri), so the description must carry the load. It defines outcome values and the 'split amounts summing to the locked total' semantics for payee/payer_amount_atomic, and clarifies operator_authorization as a domain-bound signature, but dispute_id, reason_sha256, and idempotency_key are left to the reader.

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 states a specific verb+resource (resolving a dispute) and enumerates the three settlement outcomes (release/refund/split) plus the extend action, which cleanly separates it from siblings like dispute-open and dispute-status. It never names a sibling explicitly for differentiation, but the purpose is unmistakable.

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?

It gives conditional guidance on action=extend ('permits one operator-authorized 14-day extension before expiry') and routes schema questions to /api/dispute-contract, but there is no explicit when-to-use vs. siblings (e.g., dispute-open/submit-evidence) and no stated preconditions for choosing resolve vs. extend beyond timing.

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