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

The description goes well beyond the readOnly/idempotent annotations by exposing two non-obvious failure modes: mid-epoch partial system weight inflating share percentages, and a live gauge weight of zero despite a full vote on chain. It also states that percentages use the last completed epoch, which is critical for correct interpretation.

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 description front-loads the core return value, then packs the caveats into a dense but purposeful warning, and ends with a concise access note. Every sentence contributes either to scope or to safe interpretation, with no filler or repetition beyond what annotations already provide.

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 one-parameter, read-only tool with no output schema, the description explains what is returned (allocation, epoch standing, emission rate), the denominator used, and the two traps that could mislead an agent. It does not enumerate concrete output field names, but the semantic contract is sufficient for invocation and interpretation.

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?

The only parameter, address, is already well documented in the input schema, including the default behavior when omitted. The description adds no extra parameter-level detail beyond identifying the wallet as the subject, so the high schema coverage carries the burden.

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 clearly states the tool's subject and action: reading a wallet's current gauge-vote allocation from VoterV5 on chain, plus epoch standing and live emission rate. The title's 'honest denominator' framing and the traps it names distinguish this tool from vote-submission, claim, or position tools without requiring schema inspection.

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?

The description gives clear context for when the tool is appropriate: when you need a wallet's current gauge-vote allocation with an honest share denominator and epoch context. It does not explicitly name alternatives or say when not to use it, but the read-only, wallet-specific scope is clear enough for an agent to route correctly.

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