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

With no annotations, the description carries the full burden and does so well: it discloses the 24-hour veto window, the 7-day minimum release for escrow funded by card or card-bought balance, that a refund/dispute returns funds to the payer and never releases, and that the owner cannot be its own counterparty. Remaining gaps (auth requirements, what read/list return, list pagination) are secondary for this description's role.

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?

Despite covering eight actions, the text is front-loaded with the lifecycle summary before the per-action endpoint list, and uses a compact action: METHOD /path; body: ... pattern that wastes little. It is dense and slightly staccato but each clause carries dispatch or field information.

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 an eight-action, no-annotation, no-output-schema tool with a single action enum and a largely undocumented schema, the description supplies the lifecycle, endpoint, and body-field details an agent needs to select and invoke the right action. It stops short of return-value, error, or auth detail, but is otherwise complete for its complexity.

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 9%, so the description must compensate, and it does: it documents create's body fields (amount_usd, deadline_days, exactly one of criteria/template_id/contract_ref, optional counterparty_label, funding_rail), submit's fields (filename, content, payout_address or agent_key, optional mime, encoding), veto's reason, and the idempotency_key format and header mapping. Some schema properties (handle, wanted_id, transfer_id, etc.) remain undocumented, keeping this below a 5.

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 sentence names the exact operations (create, read, veto, refund, convert to rework bounty) on a clearly identified resource (a bilateral settlement), and each action is mapped to its method+path. This is far more specific than a tautology, though it doesn't explicitly contrast the tool against the many bounty/contract siblings it overlaps with.

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?

Usage context is implied through lifecycle facts (pass releases after the 24-hour veto window, flip converts to a rework bounty, card refund returns to payer), which lets an agent infer when actions apply. However there is no explicit when-to-use vs alternatives guidance, e.g. when to flip versus using the bounty tools directly, or when to veto versus refund.

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