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

Annotations already declare readOnlyHint and openWorldHint=false, but the description adds substantial context beyond them: no page fetch, no account access, no merchant contact, no money movement, plus the commercial model (0.10 USDC per call on Base via x402, 10 signed-wallet free calls per rolling 30 days) and the X-Wever-Wallet-Proof binding requirement. It also discloses that the response is a report carrying an Ed25519 signed receipt, which is exactly the kind of behavioral detail annotations cannot convey.

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?

It is front-loaded correctly, with the input contract and the report contents before the operational detail. However, the tail of the description carries items of limited use to a caller choosing the tool (the contract path and the human-facing page URL), and the payment/wallet-proof sentences are dense enough that a reader must parse them twice.

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 paid, nested-input tool with no output schema, the description covers a lot: inputs, the report's substantive sections, the signed receipt, the payment and auth path, and a hard scope boundary. It does not address failure behavior (unparseable policy text, missing dates, payment/auth errors), which is the main remaining gap.

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 33% and the schema has 14 nested properties, so the description carries real weight; it enumerates the expected inputs (amount, currency, purchase and delivery dates, item, condition, final sale, optional request date and evidence on hand) and matches them to the nested purchase/claim objects. It adds little on the undocumented fields (merchant, order_id, category, payment_method, claim.reason) and gives no format or default guidance beyond what the schema already states.

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 first sentence names a concrete verb and resource (submit a purchase record plus a merchant refund policy) and the second states the output precisely: whether a claim fits the policy, deadline arithmetic, exclusions, fees, remedy and expected evidence. That scope separates it from narrower siblings such as wever_deadline-check or wever_claim-evidence-check, but no sibling is named explicitly, so it stops short of a 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?

Usage is implied by the input contract ('submit a purchase record ... and the merchant's refund policy text') and by the boundary statement that it reads only the material in the call, which tells an agent it must supply the policy itself. There is no explicit when-to-use/when-not-to-use guidance and no alternative named, e.g. when to prefer wever_policy-fit-check or wever_deadline-check.

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