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

Annotations already cover read-only/idempotent, but the description adds non-obvious context: a paid-plan requirement, a warning not to reconstruct voting records from transcript segments (they under-report because they capture discussion not tally), and the claim that this is the only tool returning votes. These are genuinely valuable behavioral facts beyond the structured data.

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?

Front-loaded headline plus tightly organized WHEN/WHEN NOT/EXAMPLES sections; sentences are dense but each carries routing or caveat information. Slightly long, with some repetition between prose and examples, keeping it short of a 5.

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, annotations covering the safety profile, 100% schema coverage, and explicit cost/limitation caveats, an agent has everything needed to select and invoke it correctly. The dependency on list_officials for the UUID is called out.

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 the schema for topic/since/until already states optionality and the 'omit for complete record' guidance — so the description largely restates rather than extends it. The example payloads add marginal value by showing valid argument combinations, but the baseline of 3 applies when the schema does the heavy lifting.

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?

Opens with a concrete verb+resource ('The voting record of one elected official') and immediately scopes the return ('roll-call votes ... plus expressed stances, chronological'). It explicitly distinguishes itself from siblings — search_by_official for statements, whats_changed/search_meetings for topic-wide queries, list_officials for the ID.

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?

Has explicit WHEN / WHEN NOT blocks with literal example questions mapped to argument patterns ('How has X voted on housing?' → pass topic) and named alternatives for each adjacent case. No inference is required to route correctly.

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