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

Far beyond the annotations: it discloses that a voucher is signed only when the bar is met, that invocation reads unless claim is true, the once-per-identity / once-per-wallet limit, the 30-day same-address cooldown, the one-hour window to send the tx from the identity's owner wallet, and an explicit error list (bar not met, grant paused or empty, owner changed since link). The full bar criteria are spelled out, including anti-gaming rules for thin pools. This matches readOnlyHint=false being accurate only for the claim path and adds all the operational context annotations cannot carry.

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?

The scoping statement is front-loaded, but the body is a single dense block with long tangled clauses (e.g. 'realised gains ... closed in pools the index rates established (a pool of the agent's own making, or one thin enough to push, counts for nothing)'). The information is largely non-redundant, but the returns list, bar criteria, and error list run together without structure, making it slow to parse for a one-parameter tool.

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?

There is no output schema, so the description supplies the return fields (offered, ok, why[], daysAbove, bar, claimedBy, and with claim: voucher{agentId, to, deadline, signature} and tx). Combined with the eligibility criteria, error conditions, signing rule, and timing constraints, an agent has everything needed to call it correctly and interpret the result.

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 coverage is 100% and the single optional boolean is documented in the schema, so the baseline is 3. The description adds real meaning on top: what claim=true actually triggers (voucher + unsigned tx), the condition under which a voucher is signed, and the deadline for using it.

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 states a concrete dual purpose: report where the caller stands against the grant bar, and, when claim is true and the bar is met, return a signed voucher plus an unsigned claim transaction for 5 USDG + gas from the LoomGrant contract. That is a specific verb+resource with a named prerequisite sibling (agent_identity), so an agent can tell it apart from a mere identity lookup. The purpose is only slightly obscured by the dense prose in which it is wrapped.

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 explicitly distinguishes the two invocation modes — 'left out: reads where the caller stands' vs. 'With claim true and the bar met' — and gives the precondition (bar met) that selects the mutating path. It also flags the prerequisite read (agent_identity linking) and the cooldown. No alternative sibling tool is named, which is the only gap.

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