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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the bar is low, yet the description still adds substantive behavior: no calldata is produced, the two possible SKIPPED variants and what each means (COMMITTED_SETTLED with claimed:true/amountAvailable:true vs NOT_CLAIMABLE_YET with both false), and the explicit warning that a zero amount in the pending case is an unavailable placeholder rather than a credited zero.

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?

Front-loaded with the key 'dry-run / nothing submitted' point, and the status semantics earn their space. However, the closing 'No transaction is submitted for a committed market' repeats the opening 'Nothing is submitted', and one sentence chains four status/flag combinations, making it denser than needed.

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?

An output schema exists, so return values need not be spelled out, and the description still documents the discriminating result flags the schema would not convey semantically. Only gap is input-side specifics (walletAddress defaults, batch limits), which the partial schema only partly covers.

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 50%, and the description never explains walletAddress, the 100-market cap, or what a markets entry must contain. It contributes one semantic constraint — claims only apply to onchain markets — which narrows valid input, but that does not fully compensate for the coverage gap, so this sits at the minimum viable level.

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?

States a specific verb and resource — 'Dry-run specified payout claims and return amounts and eligibility' — and immediately clarifies what it does not do ('Nothing is submitted and there is no calldata to hold — the settle calls do the submitting themselves'). It implicitly separates itself from prepare/settle siblings but never names them, so the differentiation requires inference from sibling names.

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?

Gives real routing context: 'Claim submission applies to onchain markets. Committed markets settle automatically at final resolution; GET /claims/receipts reports exact already-credited payouts' tells the agent when this tool is the wrong choice. Missing an explicit 'use this before calling prepare_claims' instruction, and the referenced receipts endpoint is not named as a sibling tool.

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