assembly_votes

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

With no annotations at all, the description carries the full behavioral burden but discloses almost nothing: not that it is a read-only lookup, not whether party/member act as filters or grouping dimensions, not whether results are paginated or capped, and not what happens when a bill has no recorded vote. Only the data facets are stated.

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?

A single front-loaded sentence naming the resource first, then the returned facets. Zero filler, though the compressed noun-phrase style makes the parameter roles harder to parse than a short clause would.

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?

The description does substitute somewhat for the absent output schema by enumerating what comes back (tally plus party and member breakdowns). But for a 3-parameter read tool with no annotations and only one documented parameter, an agent is left guessing about filtering behavior and result shape.

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 coverage is 33% — only bill_id (의안ID, PRC_…) is documented. The description partially compensates by naming 정당별 and 의원별, which maps to the otherwise undocumented party and member parameters and implies they narrow or group results. It does not say whether they are filters or groupings, nor whether they can be combined.

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 names a specific resource and scope: plenary vote results, with per-bill yes/no tallies plus party-level and member-level breakdowns. An agent can tell this is the vote-record endpoint rather than a member, bill-text, or speech endpoint. It lacks an explicit verb and does not name a sibling it differs from, so it stops short of a 5.

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?

There is no guidance on when to use this versus alternatives, even though assembly_bill_detail plausibly also surfaces vote information for a bill. No prerequisites, no exclusions, no indication of whether bill_id is mandatory for all queries despite it being required in the schema.

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