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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description rightly spends its words elsewhere: distinct-bill counting, dedupe of repeated authors, and a prominent data-coverage caveat (~91% CO/PE vs ~28% BR/CL/DO, none VE). That caveat materially changes how an agent should present results, which is exactly the value-add expected when annotations carry the rest.

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 with the core ranking definition, then parameter behavior, then the warning — a sensible order with no wasted sentences. It is on the long side and restates one or two schema facts, but every paragraph carries distinct information.

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?

All seven optional parameters are addressed at the level an agent needs, the counting and window semantics are settled, and the output schema already documents the return shape. The coverage warning closes the one gap that could otherwise cause a misleading answer.

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 100%, so the baseline is 3; the description still adds real meaning by tying since/until to the bill's *filing* date and clarifying that omitting country_code means every accessible country. Some content (co_author_of exclusion, party ID discovery) duplicates the schema text rather than extending it, keeping this short of a 5.

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?

States a precise verb and ranking semantic ('legislators ranked by how many bills they filed in a window') and contrasts it with the naive alternative of paging a whole docket and tallying client-side, which separates it from list_bills and list_top_entities. An agent knows exactly what this returns before opening the schema.

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?

Explicitly names the question it answers, tells the agent when to switch modes via `co_author_of=<actor_id>`, and routes ID discovery to list_parties for parties. It also gives an exclusion rule (omit country_code for all accessible countries), which is real selection guidance rather than filler.

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