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

Goes well beyond the annotations, disclosing that raw personal information is rejected, that both parties can read the evidence and its signed receipt, that fees are separate from locked principal and grant no resolution authority, that disputes expire after 14 days with timeout refunds, and the x402/wallet-proof auth model. These are exactly the mutation, auth, cost, and lifecycle traits an agent needs that the annotations cannot express.

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?

Front-loads the core action before the payment, expiry, and audit caveats, and most sentences carry operative constraints. It is dense and includes arguably boilerplate tails ('External custody and security audit remains pending. Company-authored.'), but little of it is strictly redundant.

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 complex, monetized, mutation tool with no output schema, the description supplies the missing behavioral and economic context (payment model, wallet proof, expiry/refund, contract pointer). It is only short on per-parameter detail, which the 0%-covered schema leaves as a gap.

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% and the description does not compensate. It conveys the gist that references are 'evidence hashes and URIs' and that no raw personal data is allowed, but says nothing about the dispute_id format, the idempotency_key semantics, or the 1-4 item bound. Two of three parameters are effectively unexplained in prose.

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 and resource: 'Either party submits bounded evidence hashes and URIs,' which is precise about what the tool does. It is distinguishable from siblings like dispute-open and dispute-resolve by the evidence-submission focus, though it never explicitly names those alternatives. Clear but not maximally differentiated.

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?

Provides an implicit precondition ('Closed or expired disputes reject evidence') and points to /api/dispute-contract for schemas and authorization, which implies usage context. However, it never states when to reach for this tool versus dispute-open, dispute-resolve, or dispute-status. Usage is inferable but not spelled out.

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