democracy_bfs_get_vote_results

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's a safe read operation. The description adds valuable context: real-time updates on voting Sunday, the ability to fetch archive data, and the level of aggregation. No contradictions with annotations.

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 is brief and well-structured: a clear purpose statement, usage context, and a concise Args/Returns section. No unnecessary words; every sentence adds value.

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?

Given the tool's moderate complexity (dependent on another tool, multiple levels, real-time vs archive), the description covers the essential steps and behavior. It mentions the return format (JSON with results per proposal) and continuous updates. Could optionally describe error handling or structure of the JSON, but the presence of an output schema (indicated by context) mitigates this need.

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 description's Args section adds meaning beyond the input schema by explaining that result_url is specifically from democracy_bfs_list_vote_dates and that level determines aggregation granularity. While the schema has parameter descriptions, the tool description contextualizes their use and relationship.

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 retrieves real-time or archive voting results from BFS, explicitly linking it to the sibling tool democracy_bfs_list_vote_dates for the URL input. This distinguishes it from other voting-related tools like democracy_get_cantonal_results or democracy_get_party_positions.

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 explains the prerequisite of using democracy_bfs_list_vote_dates to obtain the result URL, and mentions the available levels (national, cantonal, municipal). It also notes real-time updates on voting Sunday. However, it does not explicitly state when not to use this tool or mention alternatives.

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