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

Annotations only declare readOnlyHint=true, and the description adds real substance beyond that: proofs are folded into their Merkle root locally and the read bundle is checked against the on-chain root, so Merkl's API need not be trusted. It also conveys the batching behavior (all tokens for a chain in one claim). It stops short of saying what the prepared bundle contains or what signing/execution step follows, but an output schema exists to carry the return shape.

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?

Two tightly packed sentences, front-loaded with the action and scope, followed by the trust-model rationale and sibling disambiguation. The embedded API URL is informative about data provenance but slightly overstates the tool's own behavior given the caller must pass rewards in, costing a little precision.

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 prepare-style tool with full schema coverage, an output schema, and a minimal annotation set, the description supplies the missing trust model, batching scope, and sibling differentiation. Nothing an agent needs to select and invoke it correctly is absent.

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 100% and the schema already documents sender as the leaf user address, amount as cumulative rather than claimable delta, and proofs as ordered bytes32 values. The description reinforces the per-chain grouping ('one Distributor claim for every Merkl reward token... on a chain') but adds no new format or constraint detail beyond the schema, so the baseline 3 applies.

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 ('Prepare one Distributor claim for every Merkl reward token the sender holds on a chain'), including the per-chain/per-sender scope. It also explicitly names the sibling it is not (prepare_rewards_claim, Ekubo's own incentive drops), so an agent can distinguish it without opening a 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?

Gives a clear negative routing rule against prepare_rewards_claim and implies use when a sender has Merkl rewards to claim on a given chain. It does not cover the relationship to get_rewards_claims_by_owner or state prerequisites such as needing the summary fetched first, and the phrasing 'from amounts and proofs fetched from' the API is ambiguous about whether the tool fetches data or the caller must supply it (the schema requires the caller to supply `rewards`).

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