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

With no annotations, the description carries the full behavioral burden and does so well: it discloses the row fields (bills_sponsored, bills_primary, bills_passed, bills_primary_passed, pass_rate), defines the semantics of passed (status 4, 5 or 8), and reveals the default exclusion of committees. It omits pagination/limit behavior, auth requirements, and rate limits, which are minor gaps for a read-only stats endpoint.

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?

Four dense sentences with no filler, front-loaded with purpose first. Every sentence earns its place: purpose+endpoint, response fields+status semantics, usage recipes, then defaults+provenance. The length is justified by the tool's complexity (6 params, 3 enums) and nothing is redundant with the schema.

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 moderately complex tool with no output schema and no annotations, the description covers the essentials an agent needs before invoking: purpose, return fields, sort semantics, chamber filtering, the committee default, and where session_id comes from. Remaining gaps are non-critical: no mention of pagination behavior when limit is exceeded, and no access/auth context.

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, but the description genuinely adds value beyond the schema: it explains when to use sort=passed vs primary_passed ('count only bills they carried'), ties chamber+sort to a specific user question, and gives provenance for session_id ('from list_sessions'). These semantic recipes elevate it above the schema's bare enum labels.

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 opening phrase 'Legislators ranked by bills sponsored and passed in one session' states a specific verb (ranked), resource (legislators/bills), and scope (one session). It then distinguishes itself from siblings explicitly: 'This is the one call for who is most active or effective this session and which senator passed the most bills.' An agent can confidently separate it from list_session_legislators, get_session_dashboard, and get_session_breakdown.

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 gives clear when-to-use guidance via concrete recipes: 'set chamber and sort: passed (or primary_passed to count only bills they carried)' for the 'which senator passed the most bills' question, plus 'Get session_id from list_sessions' for workflow. It stops short of naming sibling alternatives or explicit when-not-to-use exclusions, which keeps it at a 4 rather than a 5.

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