Release, refund or dispute an escrow

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

With no annotations, the description does the heavy lifting: it discloses that the dispute reason is written on chain publicly and permanently, that the wallet pays gas in ETH, that the call is rebuilt from the escrow id and rejected on mismatch, and that release/refund settle conditionally. It omits the reversibility of a completed release or refund and any error/return shape, so the mutation profile is strong but not fully closed.

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 text is dense but front-loaded: action semantics come first, then gating, then the deterministic calldata check and gas note. Every sentence carries information, though 'the call is rebuilt from the escrow id and refused if anything differs' is compressed enough to be slightly cryptic.

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 three-parameter, unannotated, output-schemaless mutation tool this is above average, covering risk, cost and preconditions. Gaps remain on reason requirements, on what a successful call returns, and on whether completed settlements can be undone — meaningful omissions given the entire specification burden falls on the description.

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 must compensate, and it does well for the action enum by defining all three values and their preconditions. It does not clarify whether 'reason' is mandatory only for dispute, is ignored for release/refund, or why it must be 10–1000 characters, nor does it add anything about order_id beyond the schema's uuid constraints.

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 names the resource (an order's escrow in the local wallet) and spells out three distinct verbs — release, refund, dispute — with what each does to the funds. This distinguishes it cleanly from siblings such as agoreum_pay_order, agoreum_deliver_order and agoreum_get_order without any schema inspection.

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?

Each action is paired with the condition that enables it: release when the buyer accepts work (or anyone once auto-release is due), refund on provider decline or buyer after an undelivered deadline, dispute to freeze for the arbiter. It also says the system reports whether an action is open to you and why not, but it never contrasts against sibling tools that move money, so the routing guidance stops short of explicit alternatives.

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