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

The description carries real behavioral payload beyond readOnlyHint: weights are ratio-based, the allocation fully replaces the prior vote, a second vote in the same epoch reverts, and voting locks the NFT against withdrawal until reset. However, readOnlyHint=true is never reconciled with the imperative 'Cast one veNFT's gauge vote', which reads as a state-changing broadcast; it never says the tool only builds an unsigned transaction for later submission. This is a notable ambiguity for a tool with a single, minimal annotation.

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?

Four tight sentences, front-loaded with the action and mode, then the weight semantics, then the epoch revert, then the lock side effect. No filler and no repetition of the tool name or title.

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?

With an output schema present and full schema coverage, the description need not explain return values, and it supplies the epoch and lock constraints that no structured field carries. The one remaining hole is the prepare-vs-execute distinction, which matters for an agent chaining this into a signing flow.

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 every semantic point in the description — relative weights, full replacement, omitted pools voting zero, reset required before withdrawal — is already written into the corresponding schema property descriptions. The prose adds emphasis but no new parameter meaning, so it sits below the baseline rather than at 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 first sentence names the exact resource and scope: one veNFT's gauge vote, with the reset variant called out. The reader immediately knows the unit of operation (a single veNFT) and the two modes, so it is distinguishable from neighboring prepare_* tools even without opening the 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?

It states the operative constraints that drive usage: one vote per weekly epoch, a revert on a second attempt, and that the read bundle surfaces lastVoted plus gauge liveness so the caller can check preconditions first. What it lacks is an explicit pointer to the sibling to call for those reads or to prepare_ve33_vote for the Velodrome equivalent, so alternatives are only implied.

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