Legislation

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

With no annotations, the description carries the full burden of behavioral disclosure. It usefully reveals the HTTP method, the list-vs-single-measure behavior, and the returned fields. However, it does not mention pagination, the fact that 'state' is required even when fetching by number, or any rate-limit/authorization behavior, leaving meaningful gaps for a read tool.

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 a single, tight sentence that front-loads the endpoint and operation modes, then gives practical example queries. There is no redundant phrasing or filler; every clause contributes to selection and invocation.

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 read tool with no output schema and no annotations, the description covers purpose, return contents, and typical queries, but it omits important invocation details such as the required 'state' parameter, pagination behavior, and how optional filters interact. It is adequate for basic use but not fully self-sufficient.

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 67%, so the schema already documents most parameters. The description adds some semantic value by framing 'number' as the alternative to the state list mode, but it does not clarify 'q', 'type', 'limit', or 'offset' beyond their terse schema descriptions, and 'limit'/'offset' still lack any description.

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 identifies the resource ('Ballot measures (GET /v1/measures)') and the two distinct operations: listing measures for a state or fetching one measure by number. It also states what is returned ('full text, summary and official source URL'), making the tool's purpose unambiguous and easily distinguishable from the bill, candidate, and legislator siblings.

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 explicitly gives two concrete use cases: 'what's on the ballot in X' and 'what does Amendment N do'. This tells an agent when to invoke the tool. It does not mention when not to use it or name alternatives, but no sibling tool appears to cover ballot measures, so the omission is minor.

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

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

With no annotations provided, the description carries the full burden, and it delivers: it discloses the separate-API-call cost model, notes that analyses and citations are populated only for deeper-coverage states, and explains the detail:true shortcut. It does not mention rate limits, auth requirements, or error/not-found behavior, but for a read-only fetch tool it is substantially transparent.

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 long but dense, with the core purpose front-loaded and the include list serving a dual role of naming values and explaining them. The status_id mapping adds useful context, and there is little outright filler, though the single-paragraph format makes the enumeration harder to scan than bullet points 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?

For a complex tool with 12 sub-resources, 4 parameters, no output schema, and no annotations, the description covers most of what an agent needs: how to obtain bill_id, what each include means, when to use detail, and coverage caveats. Minor gaps remain, such as what a response with no include looks like and behavior for invalid bill_ids, but the description is still sufficient for correct selection and invocation.

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 adds real meaning beyond the schema: it defines each include value in context (e.g., 'citations (statutes the bill touches)', 'sast (same-as / similar-to companion bills)') and explains the cost difference between include and detail. It also provides status_id value mappings that help interpret results, though those are not input parameters.

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 opens with a specific verb+resource: 'Fetch a single bill by its numeric bill_id,' which clearly distinguishes it from siblings like get_bill_diff and get_bill_text. It also names the source of the required identifier (search_bills / semantic_search_bills), eliminating ambiguity about what the tool operates on.

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 context for choosing between include lists and detail:true, explicitly warning that each include is a separate API call and that detail:true is the cheapest one-round-trip alternative. It does not explicitly contrast this tool with sibling retrieval tools such as get_bill_text or get_roll_call, so it stops one step short of full when-not guidance.

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

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

No annotations are provided, so the description must disclose behavior. It mentions that diffs are precomputed and that the tool only returns results for bills with multiple versions, which is useful. However, it does not mention any side effects (though likely read-only) or rate limits. Given the complexity, it adds some behavioral context but lacks detail about response format or potential errors, hence a 3.

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 concise and well-structured. It front-loads the core purpose, then provides the API endpoint, then details how to get the parameters, and finally notes a key limitation. Every sentence earns its place without redundancy. Only minor issue is that it packs several pieces of info into a single paragraph, but it is still easy to scan.

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 (3 required parameters, no output schema) and no annotations, the description covers the essential steps: how to obtain version IDs and the limitation about multiple versions. It does not describe the output structure in detail, but since there is no output schema, some description of what is returned (unified diff, counts, highlights) is given. This is sufficient for an agent to call correctly, though additional error handling details could improve completeness.

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%, so all parameters have descriptions in the schema. The description adds clarity by explaining how to obtain the `from` and `to` parameters from get_bill, but it does not add much beyond that. Since the schema is already complete, the description adds marginal value, so the baseline 3 is appropriate.

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 explicitly states 'Compare two versions of a bill's text' with a clear verb and resource, and includes the API endpoint. It clearly distinguishes from siblings like get_bill_text and get_bill_text_history by focusing on diffing two specific versions. The purpose is unambiguous.

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 provides explicit 'when to use' guidance: 'Get the two version ids from get_bill with include:["texts"]' and explains how to obtain the required parameters. It also states a constraint: 'only bills that have more than one text version return one', which helps agents decide when this tool is applicable. This is exemplary usage guidance.

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

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

With no annotations, the description carries the full burden and does so well: it explains classification by touch type, the presence of current section text, and the resolution rule (resolved:true plus text only when the state's code is loaded, otherwise a bare citation). This is exactly the kind of return-behavior and coverage caveat an agent needs.

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 purpose, then usage, then coverage caveats, in three dense sentences with no filler. Every clause contributes operational 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?

Despite having no annotations and no output schema, the description covers what is returned, how resolution works, and where the parameter comes from. An agent has everything needed to call and interpret the result correctly.

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% and the single bill_id parameter is already documented as a numeric id from a search result. The description's 'get bill_id from search_bills' largely restates that, so the baseline of 3 applies.

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+resource: sections of existing law that a bill amends, creates, repeals or cites, plus the API route. It is clearly distinguishable from siblings like get_bill, get_bill_text and get_measure_statutes (the ballot-measure analogue) without opening any 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?

Gives an explicit trigger phrase ('what current law does this bill change') and a concrete prerequisite ('get bill_id from search_bills'). It does not explicitly name alternatives such as get_measure_statutes or get_statute, so it falls short of full when-not guidance.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It discloses that the text is cleaned, entities are decoded, and texts longer than 40,000 characters are clipped with a '[truncated]' marker. It does not cover error handling or authentication, but for a simple read-only tool these disclosed traits are substantial and useful.

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 only three sentences, front-loaded with the tool's purpose, then the usage prerequisite, then a key limitation. Every sentence provides necessary information with no filler or redundancy.

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 one-parameter read tool with no output schema, the description covers the return value (cleaned plain text ready to quote or summarize), how to obtain the parameter, and truncation behavior. It could be more explicit about the exact return type (string vs object), but overall it is sufficiently complete for correct invocation.

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 schema already states text_id comes from get_bill include:['texts'], and the description adds that each version has a date and type, which helps the agent select the correct text_id among multiple versions. This extra detail improves parameter comprehension beyond the schema's minimal description.

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 identifies the tool as returning 'the cleaned plain text of one bill-text version' and names the exact endpoint. It distinguishes this tool from siblings like get_bill_diff and get_bill_text_history by explicitly focusing on a single version's text rather than diffs or history.

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 provides clear contextual guidance: obtain text_id via get_bill with include:['texts'] and notes each version has a date and type for selection. However, it does not explicitly contrast this tool with alternatives such as get_bill_diff or get_bill_text_history, so it lacks explicit when-not-to-use direction.

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

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

No annotations are provided, so the description must carry behavioral context. It explains what the timeline contains (what changed, when, and how much) and notes the include_whitespace behavior only implicitly via the schema. It does not mention pagination, response size limits, or whether this is a read-only operation, but the GET semantics and schema are reasonably self-explanatory.

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?

Three compact sentences, each earning its place: the first defines the resource and endpoint, the second routes to a sibling, the third gives provenance for the required parameter. No filler.

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 simple two-parameter read tool with full schema coverage, the description is largely sufficient. It could add a note about the response shape or pagination, but no output schema exists and the GET semantics plus sibling routing make the tool usable as documented.

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 description does not need to repeat parameter definitions. The description adds helpful context that bill_id comes from search tools, and the title implies include_whitespace pertains to diff computation. This meets the baseline for full schema coverage.

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 specific verb ('get'), resource ('bill text history'), and scope ('all computed diffs between successive text versions of one bill'). It also distinguishes itself from get_bill_diff by noting it covers the full timeline rather than one specific pair.

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 get_bill_diff as the alternative for one specific pair of versions, and tells the agent where to obtain bill_id (search_bills or semantic_search_bills). This is clear routing guidance among siblings.

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

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

With no annotations, the description carries the full burden. It discloses that it is a read operation (GET), returns specific fields, and that people_id is conditionally present, indicating the candidate's voting record. It does not mention error handling or rate limits, but for a simple fetch this is adequate and transparent about what the agent can expect.

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 three sentences, with the core action and resource front-loaded. Each sentence adds value: the first defines the tool and its output, the second explains the conditional field and downstream tools, and the third gives the id source. No fluff or repetition.

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 single-parameter fetch with no output schema, the description covers purpose, expected data, related tools, and id provenance. It gives an agent everything needed to call the tool correctly and understand the result, even without annotations or an output schema.

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 schema already describes the id parameter as coming from list_candidates or get_midterms, which is 100% coverage. The description repeats the source ('Get an id from list_candidates') and adds the context about people_id, but that's about the response, not the parameter. Since the schema is fully descriptive, the description adds minimal extra semantic value, so baseline 3 is appropriate.

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 fetches a single candidate by id, specifies the endpoint, and lists the returned fields (party, office, district, cycle, FEC filer id, Bioguide id). It differentiates from siblings by naming related tools like get_legislator and list_candidates, so an agent can distinguish its role without ambiguity.

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?

It explicitly tells when to use this tool (to get a candidate's base data) and how to extend it: if people_id is present, pass it to get_legislator or get_legislator_scorecard for voting history. It also instructs where to obtain the id (list_candidates), giving clear guidance on the workflow and alternatives.

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

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

With no annotations provided, the description carries the full burden, and it does so thoroughly. It discloses that the tool returns null when no accepted portrait exists, that only official/licensed sources are used, and that attribution must be shown when the license requires it. This is far more behavioral context than is typical.

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 front-loaded with the core purpose and includes high-value guidance about null frequency, licensing, and fallback design. It is slightly dense and the parenthetical about the underlying GET endpoint could be seen as marginally redundant, but every sentence contributes useful 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?

For a simple one-parameter tool with no output schema, the description covers the key return behavior (URL or null) and critical edge cases. It could be more explicit about the exact response shape, especially how the license and attribution strings are returned, but the provided information is sufficient for an agent to invoke it correctly.

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 schema already documents candidate_id with 100% coverage, so the baseline is 3. The description adds that the tool should be invoked when only an id is available, which reinforces the parameter's purpose, but it doesn't add new format, constraint, or relationship details beyond the schema.

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 that the tool returns the URL of a candidate's official portrait, which is a specific resource with an explicit endpoint reference. It also distinguishes itself from sibling tools by noting that list_candidates and get_midterms already include photo_url, so this tool is only for when you have just an 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?

The description gives explicit when-to-use guidance: call this only when you have just an id, because candidate rows from list_candidates and get_midterms already include photo_url. It also warns that null is common and instructs the agent to design for an initials-avatar default, which is clear operational context.

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

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

With no annotations provided, the description carries the full burden for behavioral disclosure. It does well by revealing the near-real-time nature, the default time window, cursor semantics, and supported change reason types. It does not mention response shape or pagination behavior, which would add further transparency, but the core behavioral traits are clearly disclosed.

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?

Three compact sentences, each earning its place. The description opens with the tool's identity and endpoint, then gives cursor semantics, default behavior, supported reason types, and a usage example with an explicit alternative. There is no fluff or redundant restatement of schema details.

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?

Despite having no output schema and no annotations, the description gives an agent everything needed to select and invoke the tool correctly: endpoint, cursor mechanics, default window, state filtering, reason types, and the suitable use case. The only minor omission is the exact response structure, but the feed semantics are clear enough for a 4-parameter optional tool.

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 adds real value beyond the schema: it clarifies that `since` should be the newest already-seen timestamp, gives a concrete state example ('Florida' / FL), and enumerates meaningful reason types. `limit` is not elaborated in the description, but the schema already documents it clearly.

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 uses a specific verb and resource: 'Near-real-time feed of what changed (GET /v1/changes).' It clearly states the tool's scope and differentiates it from search_bills by positioning it as a changes feed rather than a search endpoint. An agent can immediately understand what this tool does and how it differs from siblings.

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 explicitly says when to use it: 'Use this for monitoring and incremental sync — "what moved in Florida since yesterday" — rather than re-scanning search_bills.' It also gives practical polling guidance with `since=<ISO timestamp>` and explains the default last-hour behavior, leaving no ambiguity about the intended use case.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses the HTTP method and endpoint, the optional merging behavior, and the semantic meaning of the merged sub-resources. While it does not discuss errors or auth, it gives a clear and accurate picture of what the tool does.

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 two sentences with no filler. The main behavior and endpoint are front-loaded, followed by optional behavior and a practical lookup pointer. Every sentence earns its place.

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 tool has no output schema and no annotations, so the description must be reasonably complete. It covers the core fetch behavior, optional includes, and how to obtain the required ID. It does not describe the exact return object shape or error handling, but for a simple GET-by-ID tool this is a minor gap.

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 adds real value beyond the schema by explaining that members is 'its roster, with roles' and hearings are 'its scheduled meetings.' It also connects committee_id to list_committees, which helps the agent supply a valid value.

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 action ('Fetch a committee'), the identifying parameter (committee_id), and the exact endpoint path. It also clarifies the optional sub-resources (members with roles, hearings as scheduled meetings), which distinguishes it from other get_* siblings.

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 tells the agent how to obtain a committee_id ('Find a committee_id with list_committees'), which is the key prerequisite for using this tool. It also explains when the include options are relevant, though it does not explicitly contrast this tool with sibling get_* tools.

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

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

With no annotations, the description carries the full burden, and it delivers: it discloses that data comes from a 'materialised snapshot', that `computed_at` indicates its age, and that low pct_with_votes usually reflects legislative behavior rather than a data gap. This goes well beyond a bare 'get coverage' statement and helps the agent avoid misinterpreting results.

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 dense but every sentence earns its place: definition, use case, interpretation caveat, and data-freshness disclosure. It is front-loaded with the core purpose and does not repeat schema 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?

The tool is simple (one optional parameter, no output schema), and the description provides enough context to call it and interpret its results: what metrics are included, what the ratios mean, that it is a snapshot, and how to check its age. Nothing essential for correct usage is missing.

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% for the single optional `max_items` parameter, so the schema already fully documents it. The description does not add parameter-specific detail, but the baseline of 3 applies because 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?

The description names a specific resource (per-state coverage) and a clear verb/function ('depth snapshot' showing how COMPLETE each jurisdiction's data is), and it enumerates concrete metrics: bill counts, share with votes/text/sponsor, and session status. This clearly distinguishes it from sibling tools like get_usage, get_session_breakdown, or list_states.

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?

It gives explicit guidance on when to use the tool: 'Use it before drawing conclusions from a thin result set, to tell no such bills apart from this state is thinly covered.' It also provides interpretive guidance (read ratios rather than raw percentages). It does not name alternative tools or state when not to use it, so it falls just short of a 5.

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

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

No annotations provided, so description carries the burden. It discloses the 2026-forward data range, the meaning of vote position codes, and sponsor types, and that votes come newest first. It doesn't mention auth, rate limits, or error behavior, which is acceptable for a simple GET but leaves some gaps.

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?

Two sentences, no waste. The main action and key parameter come first, then optional behavior, then how to find the ID. Perfectly front-loaded and compact.

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 single-resource fetch with no output schema, it explains the primary behavior, optional sub-resources, ordering, and data scope. It lacks explicit return field details, but that's a minor omission given the simplicity.

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 covers 100% of parameters, but the description adds interpretive value: it explains what 'votes' and 'bills' include and the meaning of their enum values, plus the int64 warning for people_id. This goes beyond the schema's terse descriptions.

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?

Clearly states it fetches a legislator's profile by people_id, names the endpoint, and describes optional merging of votes and bills. This distinguishes it from sibling tools like list_legislators and get_bill.

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?

Tells the agent how to find a people_id (via list_legislators or bill sponsors) and when to use the optional includes. It doesn't explicitly contrast with alternatives, but the single-resource fetch is self-evident.

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

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

With no annotations provided, the description carries the full transparency burden alert. It discloses that this is a one-call GET operation and describes the behavioral output in terms of participation, party-line alignment, bills sponsored/passed, and notable votes. It does not go into response format, pagination, or error behavior, but for a simple read-only lookup the provided behavioral context is reasonably rich.

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 compact and front-loaded: the first sentence identifies the endpoint and what it returns, the second gives use cases, and the third gives parameter sourcing. Every sentence adds value, with no filler or redundant restatements.

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 single-parameter tool with no output schema, the description provides enough context for an agent to call it correctly: the endpoint, the required people_id, where to find that ID, and a summary of the returned information. It could optionally mention how the scores are calculated or whether filters apply, but these are not essential for invocation.

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 schema already documents people_id as 'people_id from list_legislators', and the description reinforces and extends this by specifying how to obtain it: list_legislators with q=name. This adds meaningful retrieval guidance beyond the schema, though the parameter itself is simple and well-covered.

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 specific action and resource: it returns a legislator's voting and sponsorship scorecard. The description goes beyond the title by enumerating the profile contents (participation, party-line alignment, bills sponsored and passed, notable votes) and explicitly labels this as the tool for 'how does X vote' or 'is X effective', making its role distinct from sibling tools like get_legislator.

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?

Provides clear context for when to use the tool by mapping natural-language queries ('how does X vote', 'is X effective') to this tool. It also gives a concrete prerequisite and source for the parameter: get people_id from list_legislators using q=name. It does not explicitly state when not to use it or name alternatives, but the guidance is sufficient for correct selection.

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

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

With no annotations, the description carries the full burden and does: constitutional amendments cite the constitution (not loaded), unpublished measure text returns nothing, the list is a floor, only loaded state codes resolve to section text, and links carry resolved:true with text versus bare citation otherwise. This is unusually rich behavioral disclosure for a read tool.

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?

Purpose and endpoint are front-loaded in the first sentence, and the caveats follow in descending importance. The prose is dense with several chained clauses, but no sentence is wasted.

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?

No output schema and no annotations, so the description must explain return values itself, and it does: resolved:true with text versus a bare citation, plus the empty-result conditions. Nothing an agent needs to call or interpret this tool is missing.

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 baseline is 3, but the description adds real meaning: the state param is constrained by which codes are loaded, and the number must be as served by get_ballot_measure. It clarifies the resolution behavior tied to those params rather than restating the schema.

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 specific verb and resource: the sections of existing law a ballot measure amends, creates, repeals or cites, with the exact endpoint. This distinguishes it from get_bill_statutes (bills) and get_statute (single section) without opening either 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?

Gives an explicit use case ('which laws does Prop X / Question Y change') and routes to list_statute_coverage for the coverage question. It stops short of naming get_bill_statutes as the sibling for non-measure legislation, leaving the bill-vs-measure boundary to inference from the name.

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

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

No annotations exist, so the description carries the full burden. It discloses critical behavioral details: live_results has one entry per contest, closed primaries return parties separately, vote_pct is within-party, and warns against cross-contest comparisons. It also instructs to never call or project races and to report counts exactly, which is essential for correct data interpretation.

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?

Every sentence serves a purpose: purpose, data provenance, data interpretation rules, usage, and behavioral constraints. It is front-loaded with the core purpose and structured logically. No fluff or redundancy; dense but efficient.

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 no annotations and no output schema, the description must cover key usage nuances. It does so effectively, explaining the per-contest structure and vote_pct semantics. It does not explicitly mention pagination or parameter filtering, but those are fully described in the schema, so the description is sufficiently complete for correct invocation.

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% for all 7 parameters, so the baseline is 3. The description adds no parameter-specific meaning beyond the schema, but it does explain the data semantics of the result, which indirectly helps parameter use. No additional compensation needed given full schema coverage.

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 returns the 2026 midterm election slate: races, candidates, and ballot measures per state, with official results. It distinguishes from siblings like get_candidate (single candidate) and list_candidates (candidate list) by specifying the aggregated election-slate scope.

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 says 'Use for who is running for X and results questions,' giving a clear usage context. It does not explicitly list exclusions or alternative tools, but the guidance is sufficient to route the agent correctly among the many election-related siblings.

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

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

Since no annotations are provided, the description carries the full behavioral burden and handles it well. It discloses the GET endpoint, the default payload (tallies), the effect of include:['details'], and the numeric vote_id mapping. It omits error behavior and auth requirements, but for a read-only fetch the main behavioral traits are clearly covered.

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?

Three sentences, each with a distinct job: basic payload, optional include behavior, and ID provenance. The information is front-loaded, and no sentence is redundant with the schema or the title.

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 3-parameter fetch with no output schema and no annotations, the description covers what is returned, how to enrich the response, and how to obtain the required parameter. It omits edge cases like invalid IDs or response envelope details, but nothing an agent needs to choose or call the tool is missing.

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 adds real semantic value beyond the schema. It explains what 'details' returns, defines the vote_id code meanings, and tells the agent where to get a valid roll_call_id. This goes beyond the schema's basic descriptions and makes parameter usage more actionable.

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 states a specific verb ('Fetch'), a specific resource ('a roll call by roll_call_id'), and directly names the endpoint. It also lists exactly what fields are returned and explicitly positions the tool as the one for 'how did each legislator vote on this', distinguishing it from sibling tools like get_session_breakdown or get_bill.

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 provides a clear use case ('this is the tool for...') and tells the agent where to obtain the required roll_call_id (from get_bill with include:['votes']). It does not explicitly enumerate when to use alternative vote-related tools instead, so it stops short of full when-not-to-use guidance.

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

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

With no annotations, the description carries the behavioral burden. It adds valuable detail about the status_id ladder and aggregate buckets (passed, failed, alive), which goes beyond the schema. However, it does not disclose the response shape, pagination, or how subject values are sourced, so transparency is incomplete.

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 dense but well-structured: main behavior first, then endpoint, prerequisite, status mapping, and aggregate buckets. Every sentence adds useful information with no filler or redundancy.

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 simple count tool with two required parameters, the description covers the main behavior, parameter semantics, and a prerequisite. It lacks an explicit output shape and subject-id source, but the tool's purpose is simple enough that an agent can call it correctly with the provided information.

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 adds meaning beyond the schema by mapping status_id values to labels and defining aggregate buckets, which helps an agent construct correct queries. It does not elaborate on subject parameter values, but the enum and endpoint hint are sufficient.

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 returns bill counts grouped by status or subject for a single session, with explicit endpoint paths. It is specific enough to distinguish from sibling tools like get_session_dashboard or get_weekly_stage_breakdown, though it does not name any alternative directly.

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?

It provides a useful prerequisite ('Get session_id from list_sessions') and explains the two grouping modes, so an agent knows when this tool is relevant. However, it does not explicitly state when not to use it or which sibling tool might be preferred for other breakdowns, leaving some inference to the agent.

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

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

With no annotations, the description carries the burden. The 'GET' endpoint and 'headline counts' wording imply a read-only summary operation, and listing the specific metrics gives some behavioral context. However, it does not explicitly state read-only semantics, auth requirements, or what happens with an invalid session_id.

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 a single, front-loaded sentence that states what the tool does and the endpoint, then adds usage and source guidance. Every sentence earns its place with no filler.

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 single-parameter read-only dashboard tool with no output schema, the description sufficiently covers purpose, key returned metrics, the source of the session_id, and a concrete use case. Nothing essential is missing for correct invocation.

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 input schema already documents session_id with 100% coverage and note 'from list_sessions (filter by state)'. The description repeats 'Get session_id from list_sessions', adding no new semantic meaning beyond the schema, so a baseline score of 3 is appropriate.

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 states a specific verb and resource: 'Headline counts for one legislative session' with the endpoint, and enumerates the metrics (bills filed, passed, signed, vetoed, roll calls, active legislators). It does not explicitly name or contrast sibling tools like get_session_breakdown, so it falls just short of full differentiation.

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?

It gives an explicit starting point: 'Start here for how the 2026 Florida session is going', which tells the agent when to select this tool. It also tells the agent where to obtain the session_id ('Get session_id from list_sessions'), but it does not mention when to use a more detailed sibling tool instead.

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

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.

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

There are no annotations, so the description carries the full burden. It does reveal the core behavioral output (voted vs missed counts per legislator) and the GET nature of the request, but it does not describe response structure, pagination behavior, or exactly how 'missed' is defined.

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 two compact sentences with no filler. It front-loads the key behavior, includes the endpoint, and adds a practical usage note, with every sentence earning its place.

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 simple two-parameter read tool with no output schema, the description covers the essential information: what it returns, when to use it, and where to get the session_id. It stops short of describing the exact response fields and edge cases, but the tool is simple enough that an agent can invoke it correctly.

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%, so the baseline is 3. The description adds workflow guidance about obtaining session_id from list_sessions, which is useful, but it does not clarify the effect of the limit parameter on the returned legislator rows beyond what the schema already states.

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's function: counting how many roll calls each legislator voted in versus missed during one session, and includes the endpoint. It is more specific than a generic 'get session data' phrasing, though it does not explicitly contrast itself with sibling tools like get_session_breakdown or get_session_dashboard.

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 explicitly says 'Use for attendance questions,' giving a clear when-to-use signal. It also tells the agent where to obtain the required session_id (from list_sessions), but it does not mention when not to use it or name alternative tools.

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

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

With no annotations the description carries the full burden, and it discloses a real behavioral trait: only states whose code is loaded resolve to text, held sections carry resolved:true plus the text, otherwise only the citation is returned as written. It also explains the include_bills side effect. It omits auth, error, or pagination behavior, keeping it from a 5.

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-loads the core purpose and return semantics in the first clause before detailing inputs, and every sentence earns its place. The inline raw endpoint strings are slightly noisy and the single run-on paragraph reduces scannability.

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?

There is no output schema, so the description must cover return values, and it does: full text, place in the code, resolved:true vs citation-only fallback, and the optional bills payload. Complete enough for an agent to call correctly, though it leaves error/empty-result handling unaddressed.

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 adds genuine meaning beyond the schema: citation must be printed 'exactly as the code prints it' with concrete examples, section_id provenance, and the effect of include_bills (bills that amend/create/repeal/cite). Useful additions.

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 specific verb+resource: returns one statute section with full text and its place in the code, and it names both the section_id and citation entry points (with the underlying endpoints). It implicitly differentiates from search siblings by sourcing section_id 'from a search or a bill/measure link,' but never names search_statutes or get_bill_statutes explicitly, so sibling differentiation is inferred rather than stated.

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?

Gives clear when-to-use context: supply section_id from a search or bill/measure link, or state + citation exactly as the code prints it, and flags that only loaded states resolve (routing the agent to list_statute_coverage). No explicit exclusions or named alternative tools, so it stops short of a 5.

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

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

With no annotations provided, the description carries the full burden. It discloses the return format ('bill summaries with mention counts') and the underlying endpoint (GET /v1/trending), giving the agent a clear model of behavior. It omits details like pagination or error handling, but for a read-only, parameter-light tool the disclosure is sufficient.

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?

Two concise sentences, front-loaded with the core definition, followed by usage guidance and return-type info. No wasted words; the structure maximizes clarity per word.

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 simple tool with three optional params and no output schema, the description covers purpose, usage, return type, and points to get_bill for further detail. It doesn't mention default values (though schema does) or error behavior, but the agent has enough to invoke it correctly. Slightly more could be said about what 'bill summaries' include, but 'mention counts' clarifies that.

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%, so the schema already documents days, limit, and state. The description adds marginal context (e.g., 'optionally for one state' and 'mention counts'), but does not significantly extend beyond the schema's field descriptions. Baseline of 3 is appropriate when the schema handles parameter semantics.

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?

Description clearly identifies the resource ('Bills with the most news coverage') and the operation (retrieval), and explicitly distinguishes it from siblings by stating its use case ('what's in the news' or 'hot bills right now'). It also names the related tool for detail (get_bill), leaving no ambiguity about scope.

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?

Provides explicit use cases ('Use for 'what's in the news' or 'hot bills right now'') and directs the agent to call get_bill for detail, which implies when this tool is not appropriate (when full bill detail is needed). It doesn't enumerate all alternatives or exclusions, but for a simple trending tool this is adequate.

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

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

With no annotations, the description carries the full burden. It discloses that this is a GET meta endpoint reporting usage for the current key, which implies a safe read-only operation. It doesn't explicitly state 'has no side effects' or describe error behavior, but for a simple usage endpoint the core behavior is well covered.

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?

Two tight sentences with no filler. The first sentence front-loads the endpoint and returned data; the second gives concrete use cases. Every clause earns its place.

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 parameterless tool with no output schema, the description is complete: it names the resource, enumerates the returned fields, and specifies when to invoke it. An agent has enough to select, call, and interpret the result.

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?

There are zero parameters and schema coverage is 100%, so there is nothing for the description to add about inputs. The baseline for a parameterless tool applies; the description appropriately focuses on output and usage context instead.

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 states exactly what the tool returns: the current key's tier, monthly cap, requests used and remaining, and reset time. It also names the endpoint (GET /v1/_meta/usage), making the purpose unmistakable and clearly distinguishing it from the legislative data tools listed as siblings.

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 explicit trigger conditions: 'Call this when a request is rate-limited (HTTP 429) or the user asks about their plan.' This is direct, actionable guidance and no alternative sibling tool is relevant, so no exclusions are needed.

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

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

No annotations are provided, so the description carries the burden. It discloses the aggregation scope ('all jurisdictions combined'), the counting rule ('latest action landed there'), and that the result is aggregated counts per stage. It does not explicitly state read-only behavior, but the GET endpoint and counting semantics strongly imply it, leaving only minor gaps.

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?

Three short sentences deliver the row shape, aggregation scope, and usage guidance with no filler. The most important semantic detail ('latest action landed there') is front-loaded.

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 simple one-optional-parameter aggregation tool with no output schema, the description is complete enough: it specifies the row semantics, counting basis, jurisdiction scope, and when to choose a sibling instead. Nothing critical for a correct call is missing.

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 only parameter, days, is fully documented with default and range. The description adds no parameter-specific information beyond referring to 'the window,' so the schema already does the necessary work.

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 precisely defines the tool's purpose: one row per stage with the count of bills whose latest action landed in that stage within the window. It also distinguishes itself from get_session_dashboard via 'all jurisdictions combined' and names the endpoint, making the tool's role unambiguous.

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 explicitly states when to use this tool ('a national how much moved this week number') and directs the agent to get_session_dashboard for a single-state view. This gives clear selection criteria relative to at least one close sibling.

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

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

No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: term limit ('Up to 10 terms'), output shape ('Returns bill summaries plus pagination'), and corpus scope ('Corpus is 2026-forward only'). It also mentions the HTTP method and endpoint. While it doesn't cover error handling or auth, the essential behaviors are transparent.

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 concise (about 70 words) and front-loaded with the core purpose. It efficiently covers purpose, usage, constraints, and output in a logical order with no redundant sentences.

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 search tool with no output schema, the description covers the necessary context: output format (summary + pagination), term limit, and temporal scope. It also mentions the endpoint. It doesn't explicitly state behavior for no results or exceeding the term limit, but these are edge cases not essential for calling the tool correctly. Overall, it is complete enough.

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 input schema has 100% description coverage, with each parameter clearly described (e.g., keywords 'Terms that must all match'). The description adds little beyond what the schema already provides, except a concrete example of keyword usage. The description does not elaborate on parameter syntax or constraints, so the baseline 3 is appropriate.

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 states a specific verb and resource: 'Keyword search where EVERY term must appear (GET /v1/search/bills)'. It clearly differentiates from siblings by specifying the use case ('specific words that all have to be present') and gives an example. This distinguishes it from semantic_search_bills and search_bills without needing to inspect schemas.

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 explicitly says when to use this tool: 'Use when the user gives specific words that all have to be present'. It also names alternatives and their conditions: 'Prefer semantic_search_bills for questions and search_bills for structured filters'. This is direct guidance on tool selection.

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

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

With no annotations provided, the description carries the full burden. It discloses that classification is from action text (not status_id), that the tool is fleet-wide, and that stage values are lowercase. It does not mention pagination or response format, but the disclosed behaviors are relevant and add clarity beyond the schema.

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 dense but every sentence adds value. It front-loads the core purpose, then clarifies scope and classification, and ends with usage examples. No redundant or filler content; well-structured for an agent to parse quickly.

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 no output schema, the description does not explain the return format, but it covers the essential behavior, scope, and parameter semantics. It is complete enough for an agent to call the tool correctly, though pagination details are absent. This is a minor gap against the strong coverage of usage and behavior.

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 adds meaning to the 'stage' parameter by expanding on what each stage includes (e.g., executive with governor, signed, or vetoed) and emphasizes lowercase values. This goes beyond the schema's simple 'Lowercase stage name'.

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 lists bills whose latest action in a window falls in a specific stage, and enumerates the stage values. It also distinguishes itself by noting it is fleet-wide with no state filter, setting it apart from other bill-list tools. The purpose is unambiguous and specific.

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?

Provides explicit use cases ('what passed this week', 'what reached the governor') and notes the absence of a state filter, which helps the agent decide when to use this tool. It does not name a specific alternative, but the guidance is clear enough for selection.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It adds meaningful details: filters combine with AND, FEC and Bioguide ids are often null, rows may include people_id, and coverage includes state and federal candidates. It does not disclose return format or pagination behavior beyond schema fields, but the core behavioral traits are well covered.

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?

Five dense sentences, each earning its place: endpoint identification, filter behavior, id-null semantics, cross-tool linking, and scope. The most important scoping information is front-loaded, and there is no filler or repetition of schema details.

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 tool has 7 parametersjer, no annotations, and no output schema, so the description must do substantial work. It covers endpoint, filter semantics, id quirks, cross-links, and coverage. It stops short of describing the response shape or ordering, but the provided details are enough for an agent to invoke the tool and interpret the key fields correctly.

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 adds value beyond the schema by explaining that filters combine with AND, that FEC and Bioguide ids are null for many rows, and that people_id enables a link to legislative voting records. This enriches the meaning of the parameters without re-listing them.

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 opens with a specific verb and resource: 'Search the election-candidate directory (GET /v1/candidates): people running for office.' It clearly differentiates from sibling tools by stating it covers candidates, while get_candidate gets the full record and get_legislator reaches voting history via people_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?

The description provides clear routing context: pass a candidate id to get_candidate for the full recordcher, and pass people_id to get_legislator or get_legislator_scorecard. It implies this tool is for searching candidates, but it does not explicitly state when to prefer a sibling like list_legislators.

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

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

No annotations are present, so the description carries the burden. It does reveal the HTTP method/endpoint, filter behavior, and the fact that responses contain committee_id values needed by get_committee. Still, it omits details like output item shape beyond the ID, pagination behavior, or auth requirements, so it is only partially transparent.

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?

One concise sentence states the action, endpoint, filters, and output purpose, front-loading the core behavior. No filler or redundancy.

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 read-only list tool with four optional parameters and no output schema, the description covers what it returns (committee_ids) and how it can be filtered, which is enough to invoke it correctly. It does not describe full response rows or usage edge cases, but the schema covers parameter limits and defaults.

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?

With 100% schema coverage, the schema fully documents q, limit, state, and chamber, so the description doesn't need to repeat definitions. The description adds only a high-level mapping ('jurisdiction, chamber, or name search') that aliases state/chamber/q. That meets the baseline but adds no concrete nuance beyond the schema.

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 opens with a specific verb ('List') and resource ('legislative committees'), identifies the REST endpoint, and enumerates filtering dimensions (jurisdiction, chamber, name search). It also differentiates from the sibling get_committee by noting the output supplies committee_id values, so the tool's role is unambiguous.

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?

It gives clear context: this is the listing endpoint that produces the committee_id values which get_committee consumes, which tells an agent when to call it as a precursor. It doesn't explicitly name alternatives or exclusions, but for a list tool the chaining cue is sufficient guidance.

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

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

With no annotations, the description carries the behavioral burden. It discloses two non-obvious behaviors: boundary output is large and can be reduced via simplify, and district matching must be numeric rather than by label text. It does not mention side effects (though it appears read-only), auth, rate limits, or default return format, so coverage is partial.

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?

Three concise sentences, each with a distinct job: core metadata listing, boundary/simplify usage, and matching warning. Information is front-loaded with the resource and filters in the first sentence. No redundant or filler content.

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 7-parameter tool with no output schema and no annotations, the description explains the core modes and the non-obvious boundary behavior well. It leaves out the default response shape (list of district objects with fields like district_number) and pagination semantics (limit/offset), which an agent would need to fully rely on the tool.

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 71% and the description adds meaning beyond the raw schema: it enumerates the three district types, explains the boundary:true + district_id combination, gives a concrete simplify tolerance example, and warns about numeric matching. It does not address limit/offset, but those are conventional and the remaining parameters are well-covered.

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 states the tool exposes district metadata filtered by state and type, naming the three types (congressional, state senate, state house). It also describes the boundary-retrieval mode, making the two main behaviors clear, though it never explicitly says 'list' (the tool name supplies that verb) and doesn't contrast with sibling list tools.

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 explicit operational guidance for the boundary mode ('Pass district_id with boundary:true') and advises using simplify to shrink large geometries. It also warns to match districts numerically. However, it does not mention when to prefer this tool over siblings or provide any exclusion criteria, so an agent must infer that this is the only district-tool.

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

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

With no annotations, the description carries the behavioral disclosure burden. It communicates scope (across committees), filtering dimensions, and that hearings are scheduled, but does not mention ordering, pagination, default limits, or response shape. For a simple list tool this is adequate but not fully transparent.

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?

Three sentences, no filler. The core action and endpoint are front-loaded, followed by use cases and sibling routing. Every sentence earns its place.

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 simple list tool with fully documented parameters, the description covers scope, filters, endpoint, use cases, and alternatives. Minor gaps remain around result ordering and whether past hearings are included, but nothing critical is missing for correct invocation.

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%, so the schema already documents all three parameters. The description adds semantic labels like 'jurisdiction' and 'start date' that map to state and since, but does not add meaningfully beyond the schema.

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 lists 'scheduled committee hearings across committees' and gives the endpoint. It differentiates from siblings by explicitly noting it is not for one specific committee or bill, which are handled by get_committee and get_bill.

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?

It provides concrete use cases: answering 'what is being heard this week' and tracking when a committee next meets. It also gives explicit alternatives with parameters for committee-specific and bill-specific hearing lookups, leaving no ambiguity about when to choose this tool.

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

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

There are no annotations, so the description carries the burden of behavioral disclosure. It does state that filters combine with AND, which is genuinely useful behavioral info. However, it does not mention whether pagination is required for large result sets, whether the response is a flat list, or any rate-limiting or access considerations. The safety profile is entirely unaddressed (no read-only hint, no destructive hint), which is a gap for a listing tool.

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?

Two sentences, zero filler. The main action and endpoint are front-loaded, and the workflow pointer ('turns a name into people_id') is placed immediately after. Every sentence earns its place.

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?

This is a simple list/search tool with 100% parameter coverage and no output schema. The description covers the core purpose, the AND-combination behavior, and the primary downstream use. What is missing is a bit more return-value context (e.g., that results include people_id) and pagination guidance, but for a low-complexity tool this is nearly complete.

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%, so the schema already documents each parameter with a brief description. The description adds some context by naming the filter dimensions and noting AND combination, but it does not add details such as accepted formats for chamber or district beyond what the schema gives. Baseline 3 is appropriate because the schema carries 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?

The description starts with a specific verb ('Search or list'), names the resource (legislators) and the endpoint (GET /v1/legislators), and lists the key filter dimensions (jurisdiction, chamber, party, district, or name). It also distinguishes this tool's lookup purpose from get_legislator, so an agent can tell it apart from its sibling tools without opening any schemas.

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 makes the use case explicit: 'This is how you turn a name into the people_id that get_legislator needs.' This clearly points to a common workflow and identifies the downstream consumer. It does not explicitly explain when to choose list_legislators over list_session_legislators or list_candidates, but the primary use case is well covered.

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

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

With no annotations, the description carries full burden. It states the tool is a read operation (listing legislators) and mentions the return includes people_id. It doesn't disclose pagination or full response structure, but for a simple list tool this is adequate and adds context on the source of session_id.

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 two sentences, front-loads the core function, and then provides usage guidance with the alternative tool and parameter source. There is no redundant information and the structure is clear.

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 tool with a single parameter, no output schema, and no annotations, the description covers purpose, usage, and parameter source. It doesn't detail the response fields beyond people_id, but that is acceptable given the tool's simplicity; the guidance is sufficient for an agent to invoke it correctly.

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% as the only parameter, session_id, already has a description ('session_id from list_sessions (filter by state)'). The description reinforces this by saying 'Get session_id from list_sessions.' It adds no new semantic detail beyond the schema, meeting the baseline for full coverage.

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 it lists every legislator who served in a specific session, and distinguishes it from list_legislators which handles the current roster by state. It also notes the inclusion of people_id, making the resource and output explicit.

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 explicitly tells when to use this tool (for a past or special session) versus list_legislators (current roster by state), and instructs the agent to get session_id from list_sessions. This is clear and actionable guidance.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It does add useful context: the endpoint is GET, it lists regular and special sessions, and the corpus is 2026-forward only. However, it does not mention pagination behavior, ordering, response format, or any access constraints, which a fully transparent description would include.

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?

Three focused sentences with no fluff. The endpoint is front-loaded, the returned fields are listed, use cases are given, and the coverage limitation is stated. Every sentence contributes.

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 simple optional-parameter list tool, the description covers the important operational knowledge: what the tool returns, when to use it, what omitting state does, and the corpus boundary. It does not describe ordering or pagination, but the input schema handles max_items defaults, so nothing critical is missing for correct invocation.

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%, so the baseline is 3. The description adds some context about state ('Omit state to list every jurisdiction's sessions') but does not add meaningful semantics beyond the schema, which already explains state format and max_items behavior.

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 verb and resource ('List legislative sessions') and immediately specifies what the payload contains: regular/special sessions, years, dates, and session_id. It is clearly distinct from the sibling tools, which are mostly get_* operations for individual bills, legislators, or session statistics.

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 explicit use cases: resolve a bill's session, find the current session for a state, and obtain session_id for search_bills filtering. It also explains the scope-changing behavior ('Omit state to list every jurisdiction's sessions'). It does not mention when not to use it or name alternatives, but no close alternative exists among the siblings, so this is a minor gap.

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

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

With no annotations, the description carries full burden for behavioral disclosure. It reveals the HTTP endpoint, that it returns the full list, the row count (52), and the fields included. For a zero-parameter read-only directory this is sufficient; it does not need to discuss side effects or auth. It could add pagination or caching details, but none are likely needed for such a simple fixed list.

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?

Three sentences, no fluff. The endpoint and scope are front-loaded, followed by the return shape and use case, and finally the sibling alternative. Every sentence earns its place.

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 simple, parameterless list tool with no output schema, the description tells the agent exactly what it will get (52 rows, specific fields) and how to interpret it. It also points to the right tool when completeness is needed. Nothing essential is missing.

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?

There are zero parameters and the schema coverage is 100%, so there is no parameter documentation burden. The description goes beyond the schema by explaining the semantics of the return value (resolving names to codes and enumerating coverage), which is useful context. Baseline 4 is appropriate for a no-parameter tool.

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 states a specific verb ('list') and resource ('states & jurisdictions'), enumerates exactly what is included (50 states, D.C., U.S. Congress), and lists the returned fields (state_id, 2-letter code, full name). It also distinguishes itself from get_coverage by scope, making it easy for an agent to select correctly.

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 explicitly states when to use this tool: to resolve a name to a code or enumerate everything the corpus covers. It also names the alternative (get_coverage) and the condition that selects it (when you need data completeness per jurisdiction). This is clear routing guidance.

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

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

With no annotations, the description carries the full behavioral load. It usefully discloses the return contents (codes, sections, bill links, edition) and the dual-endpoint mode switch, but says nothing about authorization, rate limits, pagination, or how large a state's code list can be.

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?

Three sentences, front-loaded with what the tool returns and ending with the call-first instruction. Slightly dense because it packs two endpoint behaviors plus a cross-reference into one description, but every clause earns its place.

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?

No output schema exists, so the description must explain returns — and it does, listing codes, sections, bill links and edition. Combined with the routing to get_statute, an agent has enough to invoke it correctly, though auth and pagination context is absent.

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% for the single state parameter, so the format is already handled. The description goes beyond it by explaining the consequence of passing state — it returns that state's codes and the code_id values consumed by get_statute — which adds real semantic value.

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 states a specific verb and resource — which jurisdictions' codified law is loaded plus size and currency, and it names the backing endpoints. It is slightly blurred because the same tool does double duty (coverage at /v1/statutes/coverage and code listing at /v1/statutes/codes), so the agent must infer a mode switch rather than a single clean purpose.

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?

'Call this first to know whether a state's statutes are available' gives explicit ordering and a clear condition for calling it. It also points to get_statute as the downstream consumer, though it never names alternatives like search_statutes or get_bill_statutes for comparison.

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

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

With no annotations, the description carries the behavioral disclosure burden. It does add useful context: raw taxonomy, per-subject bill counts, scoping by state, narrowing by q. However, it does not mention auth, rate limits, pagination, or the exact output shape, leaving some behavioral details implicit for a read-only list tool.

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?

Three sentences, all load-bearing: first identifies the resource, second explains the taxonomy and relationship to list_topics, third gives explicit use cases. No wasted words and the most important context is front-loaded.

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 low-complexity, zero-required-param list endpoint, the description covers purpose, sibling distinction, use cases, and filtering behavior. It mentions per-subject bill counts and the subject_id use case, which partially compensates for the missing output schema, though pagination/ordering details are absent.

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 schema already documents all three parameters. The description adds the 'scope with state, narrow with q' relationship, but this is mostly a restatement of the schema's own descriptions rather than significant new meaning.

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 identifies the resource ('raw subject taxonomy with per-subject bill counts') and the specific operation (GET /v1/subjects). It also explicitly distinguishes subjects from the curated topic slugs in list_topics, so an agent can tell this tool apart from its closest sibling.

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?

It states concrete use cases: finding a subject_id to filter search_bills by, or gauging what a jurisdiction is legislating on. It also names the sibling tool list_topics and explains the key difference, giving the agent clear routing guidance.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses the two operational modes (taxonomy listing vs. slug detail), the per-topic bill counts, and the sample of raw subject names. The GET verb implies a read-only operation, and the relationship to search_bills clarifies what the tool does *not* return. Missing error-behavior details are a minor gap.

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?

Two sentences, front-loaded with the core purpose, then the usage guidance and alternatives. Every phrase adds value; no redundancy or fluff.

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 read-only listing tool with no output schema, the description explains what to expect from both invocations (taxonomy with counts, slug detail with sample subject names). It omits error-handling details and explicit authentication requirements, but given the simple optional-slug pattern and the schema's max_items hint, the agent has enough to call it correctly.

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 schema already describes both parameters at 100% coverage, giving a baseline of 3. The description adds strategic meaning for 'slug' by framing it as the key for the search_bills topic filter and explaining the detail response. 'max_items' receives no extra description, but the schema already explains it adequately.

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's role as 'the canonical topic taxonomy with per-topic bill counts' and the GET endpoint. It distinguishes itself from search_bills by explicitly noting that actual bills are retrieved via that tool, and from raw subject names via the mention of 'sample of the raw subject names folded into it.'

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?

Provides explicit when-to-use guidance: 'Call this first to find the right slug for the topic filter on search_bills, instead of guessing one.' It also tells when to omit vs. pass a slug and routes the agent to search_bills for the actual bills, making the choice clear.

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

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

With no annotations provided, the description carries the full burden and largely succeeds: it discloses that create mutates the account and requires confirmation, delete also requires confirm, and list is read-only. It also explains test queues a sample delivery. It does not mention error responses or rate limits, but the key behavioral traits (mutation vs read-only, confirmation requirements) are clearly covered.

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 a single dense paragraph, but every sentence contributes: it states the purpose, explains each action, lists events and filters. It is front-loaded with the resource and action enumeration. While it could be bulleted for readability, it is appropriately concise given the number of actions and parameters.

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 7-parameter tool with no output schema and no annotations, the description covers the essential usage: all actions, required parameters per action (via schema plus description), and optional filters. It does not describe the response format or error cases, but for a webhook management tool these are secondary. The description, combined with the schema's 86% parameter coverage, provides sufficient guidance for correct invocation.

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 86% and the description adds meaning beyond it: it clarifies that states are postal codes and subjects are optional filters, that webhook_id is used for test/delete, and that confirm is required for create/delete. It also lists the event enum values in the description, though they are in the schema. This adds context for action-specific parameter usage.

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 verb 'Manage' and the resource 'webhook subscriptions', then enumerates the four actions (list, create, test, delete) with concise explanations for each. This distinguishes it from all sibling tools, which are exclusively read/list/search operations, making the purpose unambiguous.

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 provides per-action context (e.g., create requires confirm:true and user go-ahead, list is read-only), but does not explicitly contrast with alternatives. However, given the sibling list contains only read-only tools, the usage context is implicitly clear. It lacks an explicit 'use this when you need to modify webhooks' statement, but the action descriptions adequately guide selection.

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

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

With no annotations provided, the description carries the full burden, and it does well: it discloses the HTTP method, AND-combination semantics, direct bill-number matching in q, pagination, the 2026-forward corpus limitation, and the full status_id mapping. It does not mention auth or rate limits, but for a read-only GET search tool the key behaviors are covered.

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 front-loaded with purpose and usage, and most sentences earn their place. The status_id mapping is repeated from the schema, which is slightly redundant, but the overall length is reasonable for a tool with 13 optional filters and important behavioral caveats.

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 13 parameters, no annotations, and no output schema, the description covers the essential context: endpoint, filter behavior, corpus limitation, output shape, and when to escalate to get_bill. It could be more complete by explicitly routing to keyword_search_bills or semantic_search_bills for other search modes, but the schema fills most remaining parameter-level gaps.

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 schema already documents all 13 parameters at 100% coverage, so the baseline is 3. The description adds value beyond the schema by explaining that filters combine with AND, that a bill number in q matches the bill directly, and by providing aggregate status buckets. This is a meaningful supplement to the individual parameter descriptions.

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 opens with a specific verb and resource: 'Search or list legislation with structured filters (GET /v1/bills).' It also clarifies scope by distinguishing from get_bill ('call get_bill for the full record') and by emphasizing structured filters, which separates it from keyword or semantic search siblings.

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?

It explicitly says when to use the tool: 'Use this when you know the jurisdiction, sponsor, topic, or status you want.' It also notes that all filters are optional and combine with AND, and directs users to get_bill for full records. It does not explicitly contrast with keyword_search_bills or semantic_search_bills, but the structured-filter framing implies the distinction.

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

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

With no annotations, the description carries the behavioral burden and does well: it discloses the return shape (matching sections with headings and excerpts), the resolved:true flag semantics, and the important caveat that only loaded states resolve to text while others return the citation as written. It omits operational details like pagination or auth, but the substantive behavioral traits are covered.

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 verb+resource and endpoint, then layered with use cases, return shape, and the coverage caveat. Four dense sentences, all earning their place, though it packs multiple ideas closely together.

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?

No output schema and no annotations, so the description must explain returns and caveats, which it does (headings, excerpts, resolved flag, coverage limitation). An agent has enough to call it correctly; only minor gaps like default limit behavior remain, and those are handled by the schema.

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 75%, so the schema documents q, state, and code itself. The description implies the state-scoping constraint ('only states whose code is loaded') but adds no new syntax or semantics for q, code, or limit beyond what the schema already states, so it sits at the baseline.

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 specific verb (full-text search) and resource (a state's codified law), and even gives the endpoint GET /v1/statutes/search. It distinguishes itself from siblings by naming get_statute for full section retrieval and list_statute_coverage for coverage, so an agent can route without opening any 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 when to use it ('what does the law say about X', finding the section a bill or ballot measure changes) and points to the alternative (get_statute) for fetching whole sections. The coverage caveat plus pointer to list_statute_coverage preempts a common misuse.

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

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

With no annotations, the description carries the full burden and delivers: it explains vector search semantics, plain-English querying, match_score results, return fields, corpus restriction, and status_id meanings. This goes well beyond the schema and leaves little ambiguity about behavior.

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 compact yet information-dense, with the core purpose and usage guidance front-loaded. Every sentence adds value, including routing, return fields, corpus scope, and status code mapping.

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 no output schema, the description compensates well by listing returned fields, status_id values, and aggregate buckets. It also covers when to use the tool and corpus limitations, making it effectively complete for an agent.

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%, so the baseline is 3. The description adds helpful examples for the query parameter and status semantics, but it does not add much beyond the schema for limit, state, or threshold.

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 specific verb and resource: 'Vector search over the full text of every bill' with the endpoint. It also distinguishes itself from search_bills and keyword_search_bills, making the tool's unique role clear.

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 says when to use this tool ('questions and topics') and when to prefer search_bills or keyword_search_bills. The corpus limitation ('2026-forward only') is also disclosed, preventing misuse.

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