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

With annotations covering the destructive/open-world/idempotency hints, the description adds substantial behavioral context: the freeze-and-refund semantics, the normal state machine, the 25.00 USDC order cap, the 0.10 USDC x402 access fee with shared free calls, the mandatory X-Wever-Wallet-Proof binding to exact JSON args and path, and safety constraints (no private keys, no payee substitution, adapter grants no authority).

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 core action and its release-blocking effect are front-loaded in the first two sentences. The remaining content is dense and information-rich, though somewhat repetitive (repeated "under the existing" rail phrasing and authority disclaimers) for a single-operation tool.

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, so the description carries return/behavior burden; it covers auth, payment, escrow caps, state transitions, and the dispute effect, and points to /api/workorder-contract for schemas and recovery. An agent has enough to call it correctly, though exact response shape is left to the external contract.

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 only 25%, so the description must compensate. It adds meaning to evidence_reference ("bounded evidence in the proof inbox") and alludes to evidence bounds and proof binding, but does not clarify order_id, proof_hash, or idempotency_key semantics, deferring schemas to /api/workorder-contract.

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+effect: either authenticated party freezes the order, records bounded evidence, and this blocks further release. It clearly distinguishes dispute from the sibling release/deliver/accept flow. It stops short of naming a specific sibling alternative, so 4 rather than 5.

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 clear usage context: either authenticated party may invoke it, and only before release, with the expiry refund to the original hirer remaining available afterward. It notes arbitration UI is outside v1. No explicit alternatives or when-not exclusions are named, so 4.

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