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

Annotations only declare readOnlyHint=true, and the description earns credit beyond that: it discloses atomicity, that fees are claimed immediately before the clear, that Ve33 discards pending voter fees when weight goes to zero, and that a mismatched current_pool_key reverts the whole batch. It also states what is untouched (stake amount, lock end, NFT ownership), though it never explicitly says the output is unsigned calldata requiring signing and broadcast.

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 action and its mechanism are front-loaded, followed by the routing rule and the effects, then the docs pointer. It is dense but each sentence carries distinct information; the only mild compression cost is that the atomicity and revert warnings are packed into long clauses.

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 tool with an output schema, five parameters and only a readOnlyHint annotation, the description covers the behavioral consequences an agent needs: fee loss risk, all-or-nothing batching, and unaffected stake state. The remaining omission is that it does not describe the resulting transaction lifecycle (sign/broadcast) or the recipient default.

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 schema already documents most fields; the description still adds semantic weight by explaining why current_pool_key is mandatory (it drives the fee claim and a wrong key reverts the entire batch). The optional recipient parameter is not mentioned in the description at all, leaving that one gap to the schema.

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 names a specific verb and resource ('Remove the active vote from one or more ve-tokens') and immediately qualifies the mechanism ('claiming each stake's current pool fees immediately before its clearVote in one atomic batch'). It explicitly distinguishes itself from raw clearVote calldata and from prepare_ve33_reallocation, so an agent can select it without opening sibling schemas.

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 when to use it ('instead of raw clearVote calldata') and names the alternative with its selecting condition ('Prefer prepare_ve33_reallocation when votes move to other pools'). It also points to ekubo://docs/ve33-workflow for the broader procedure, leaving nothing to inference about routing.

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