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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), it discloses that release is atomically credited once, that the treasury is order-scoped and simulated, that the order token is a capability rather than authentication, and hard limits (120 virtual USDC, 64 orders, 2 MiB, 24-hour expiry). It also states isolation from production custody/dispute records and that real escrow caps are unchanged.

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 main operation is front-loaded and every following sentence maps to a distinct concern (action routing, exclusion rules, simulation limits, isolation). It is dense and long, and the closing "Real escrow/dispute caps and all other tools are unchanged" is borderline filler, but there is little true redundancy.

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 five-action, eight-parameter tool with no output schema, the description covers the action surface, rejection conditions, simulation ceilings, and dispute semantics adequately. Gaps remain in describing what status reads return and how idempotency_key interacts with the atomic credit, which matters for a write-capable tool.

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%, so the description carries the burden, and it does name the key inputs: order_id, bearer order_token, delivery_reference, claim {reason_code, statement_sha256}, references, idempotency_key, and the action modes. It explains the role of each but not format constraints (base64-like sizes are reserved for patterns), so it compensates well without being exhaustive.

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 opening clause gives a precise verb+resource ("Confirm simulated delivery of a shipped order") and then enumerates the additional action modes (dispute, dispute-status, dispute-submit-evidence, status). It explicitly positions itself relative to the standalone dispute services ("invokes existing dispute-open service"), so an agent can tell this bridged simulation tool apart from wever_dispute-open / wever_dispute-resolve.

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 routes by action and states key conditions: disputed orders cannot release, resolution is operator-authorized and "not exposed by this bridge", and payment headers / simulation=false are rejected. It does not explicitly say when to prefer the standalone dispute tools over this bridge, so a small routing gap remains, but the context is clear.

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