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

Annotations already declare readOnlyHint/openWorldHint=false, but the description goes well beyond them: it enumerates exactly what is not done (no network request, fetch, money movement, message, sharing, configuration change or external write), discloses the paid access model (0.10 USDC per call on Base via x402 exact, 10 signed-wallet free calls per rolling 30 days), specifies the X-Wever-Wallet-Proof binding requirement to the exact JSON arguments and route, and notes the Ed25519-signed receipt. That is unusually rich behavioral context for a call with payment and auth implications.

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?

Purpose and verdict semantics are front-loaded, and the dense single paragraph is mostly load-bearing. There is some redundancy ('materially changed ... every material change itemized') and a tail of boilerplate (paid URL, contract path, human page URL) that adds length without helping tool selection, though the pricing detail is arguably useful to an autonomous caller.

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 four-required-parameter tool with nested objects and no output schema, the description supplies what is otherwise missing: the three possible verdicts (reapproval_required, non_material_changes, unchanged), the fact that non-material changes are each listed, and that a signed receipt comes back. An agent knows what to send, what it will learn, and what side effects will not occur.

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 80%, so the baseline is 3, but the description adds genuine semantics the schema cannot: it frames 'approved' and 'current' as two versions of the same document that must be compared, and enumerates the approval-record attributes that matter (who approved, version, amount, reference, SHA-256). The document_kind enum and the diff axis (amount, parties, scope, dates, terms) are also conveyed in prose, giving the agent a model of how the nested objects relate.

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 gives a specific verb and resource: submit an originally-approved document plus its approval record plus the current version, and receive a sentence-by-sentence diff verdict. It explicitly carves out scope against siblings by naming wever_contract-diff-check (redlining) and wever_invoice-payment-match (invoice-to-payment matching), so an agent can distinguish this tool without opening any schema.

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 states the selection condition clearly (use this when the question is whether an existing approval still covers a newer version of the same document) and routes adjacent needs to two named alternatives. What it lacks is an explicit when-not-to-use statement or a prerequisite checklist (e.g. that approved and current must be the same document), though that constraint is implied by 'the same document'.

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