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

Annotations already cover read-only/idempotent/non-destructive, so the description earns credit for adding substantive behavior: status is derived rather than stored, the founding ballot e66aec80 tally is deliberately not public (with source post 1120 cited), and open ballots are pulled live from /api/ballots. The one murky note is 'Not split by segment', which sits uneasily beside a segment parameter and reads as a scoping caveat rather than a contradiction.

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?

Everything is packed into one long parenthetical-heavy sentence whose opening is an internal path fragment ('a/proposals') rather than the tool's purpose. The behavioral facts are valuable but the front-loading is weak and the internal jargon (POAScan, hand-kept ballot list, e66aec80) slows comprehension.

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 two-parameter read-only list with full schema descriptions and no output schema, the description supplies the missing conceptual layer: what statuses mean, where ballot data originates, and a known data-quality caveat. Only the return shape/ordering and the interplay between segment and the 'not split by segment' note remain unaddressed.

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%, so both limit and segment are already well documented, including the archived segment-1 epoch-repetition caveat. The description's only parameter-adjacent remark, 'Not split by segment', does not clarify anything the schema hasn't already said better. 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?

The description identifies the resource precisely (a/proposals posts) and explains the derived status model (ballot / discussion under 24h / posted), plus that it also returns the ballot list and open ballots from /api/ballots. It never states a clean verb+resource opening sentence, though, and doesn't contrast with any sibling — the closest neighbors (get_forum_activity, search, get_governance_overview) are not acknowledged.

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?

'Use it to see what is proposed and which posts are on a ballot' gives an affirmative use case, but there is no when-not guidance and no routing to alternatives such as search or get_forum_activity for raw posts. The agent must infer selection from context signals alone.

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