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

No annotations exist, so the description carries the full burden: it discloses dual auth ('Accepts both NextAuth session and live bearer'), the server-side stake computation rule, the 422 stake_mismatch failure, and the below_dispute_floor refusal case. It stops short of describing what a successful dispute does to the claim/job or what is returned.

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 'When to use' lead is front-loaded, but the core sentence 'Open a dispute on a submitted/verified claim' is repeated verbatim after the ALIP-0054 paragraph, and the dense ALIP spec references (ALIP-0005 §A, ALIP-0054) consume space a reader must decode.

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 and no annotations, the description supplies the trigger, the stake rule, the auth modes, and two named failure codes, which is enough to invoke correctly. The main remaining gap is the post-call effect on the claim, which is not stated.

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 100%, so all four parameters are already documented, including stake_minor's micro-unit rule and the idempotency_key replay semantics. The description restates the stake omission/mismatch behavior but adds no syntax or format detail beyond the schema — baseline 3.

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 — 'Open a dispute on a submitted/verified claim' — and constrains the target to submitted/verified claims. It does not distinguish itself from siblings like submit_evidence, submit_review, or accept_claim, so an agent must infer the routing itself.

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 opens with an explicit 'When to use' heading and names a when-not path: small jobs under $5.00 in decline mode refuse with below_dispute_floor and the buyer should use the dashboard decline instead. The alternative is a UI path rather than a sibling tool, and no other exclusions are given.

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