Legislation

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral content — that the single-measure mode returns full text, summary and official source URL. However, it says nothing about pagination despite limit/offset parameters, nor that state is required even when fetching a single measure by number.

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 resource and its two modes, followed by intent examples. Dense and waste-free, though the parenthetical endpoint reference is marginally redundant for an agent that only needs invocation guidance.

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 six parameters, no output schema and no enums, the description covers the two access patterns and the shape of the single-measure response. It leaves gaps an agent would care about: pagination behavior, what the filter parameters do, and the fact that state is always required.

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 67%, so the baseline is 3. The description reinforces the key 'number' semantics with a format example ('Amendment 1') and clarifies that 'state' scopes the list, but it adds nothing about q, type, limit or offset, leaving the filter and pagination parameters to the schema alone.

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 the resource (ballot measures), the underlying endpoint, and both operating modes: a state-level list or a single measure fetched by number. That is a specific verb+resource statement. It stops short of distinguishing itself from the sibling get_measure_statutes, so an agent must still infer the boundary between them.

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 two concrete user-intent triggers — 'what's on the ballot in X' and 'what does Amendment N do' — which map cleanly onto the list and single-measure modes. There are no explicit exclusions or named alternatives (e.g. when to prefer get_measure_statutes instead), so it falls 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?

Annotations already establish read-only, non-destructive, open-world behavior, and the description adds important operational context: include calls are separate API calls, detail avoids that cost, and analyses/citations are only populated for deeper-coverage states. It also supplies status_id and aggregate-bucket semantics that help interpret 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 definition is front-loaded with the core fetch behavior and then organizes includes, coverage caveats, and status semantics. It is somewhat long and duplicates the include enum, but the added status mapping is useful enough to justify most of the length.

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 rich schema and annotations, the description covers the main calling decisions: where to get bill_id, whether to use include or detail, coverage limitations, and status/aggregate meanings. Since there is no output schema, the return shape could be described more fully, but the key semantic context is present.

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, but the description adds meaning beyond the schema by explaining what several include values contain and how detail:true overrides include. max_items is left to the schema, which is acceptable given 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 states a specific verb and resource: fetch a single bill by numeric bill_id via GET /v1/bills/{bill_id}. It also names the search tools that supply bill_id, so an agent can distinguish this from broad bill search.

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 to get bill_id from search_bills or semantic_search_bills and explains the include-vs-detail tradeoff: each include is a separate API call, while detail:true fetches everything in one round trip. It does not explicitly compare against siblings like get_bill_text or get_bill_statutes, so it stops short of full when-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?

While annotations confirm safety (readOnlyHint: true), the description adds vital behavioral context by specifying that the diff is precomputed. It sets expectations regarding availability, noting that the bill must have more than one text version to return a diff.

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 tool packs significant technical and workflow information—input source, parameter roles, and output format—into a concise, front-loaded paragraph without unnecessary 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?

The description is complete, providing all necessary context: how to acquire the input IDs, the roles of the parameters (`from` vs. `to`), and the specific types of analysis the tool performs.

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?

Since schema coverage is 100%, the description focuses on adding semantic context. It clarifies the necessary prerequisite workflow for obtaining the `from` and `to` parameter values, which is essential for agent execution.

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 is highly specific, stating that it compares two versions of a bill and listing the exact metrics provided in the output (unified diff, similarity, line/character counts, and highlights). It clearly distinguishes this function from simple text retrieval 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?

It provides explicit workflow instructions, noting that the version IDs must first be retrieved from the `get_bill` tool with the `include:['texts']` flag. It also defines the temporal relationship between the `from` and `to` parameters.

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?

Beyond the readOnly/openWorld annotations, it discloses a real behavioral trait: only states with loaded codes resolve to text, ungranted sections come back as bare citations, and resolved sections carry resolved:true with text. No pagination or volume/rate context, which keeps it below 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-loaded with what is returned, then usage, then provenance, then the coverage caveat. Four dense sentences with no filler, though the parenthetical endpoint and nested caveats make it slightly heavy for a single-parameter tool.

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?

Covers provenance, partial-coverage behavior, and the shape of returned section links, which is important since there is no output schema. Error/empty-result behavior and pagination are unaddressed, so not fully 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 coverage is 100% and the single bill_id parameter is already documented, so the schema does the heavy lifting. The description adds only the provenance hint (from search_bills), which is useful but marginal.

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 resource (sections of existing law a bill amends/creates/repeals/cites) plus the endpoint, and the classification dimension. It is clearly distinguishable from get_statute, search_statutes, and get_measure_statutes by being bill-keyed and change-classified.

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?

Explicit trigger phrase ('Use for what current law does this bill change') and an acquisition hint ('Get bill_id from search_bills') plus a dependency pointer to list_statute_coverage. It does not, however, explicitly route away from adjacent siblings like get_measure_statutes or search_statutes for the same question.

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?

Annotations already cover the safety profile (readOnly, non-destructive, open-world), so the description's added value is the disclosure that entities are decoded and that texts over 40,000 characters are clipped with a '[truncated]' marker. That truncation caveat is a real behavioral trait an agent must know before quoting, and it is not expressed in any structured field.

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 tight sentences: what it returns, how to obtain the ID, and the one truncation caveat. The critical constraint is placed last but only after the core definition is front-loaded; nothing 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?

There is no output schema, and the description compensates by characterizing the return as decoded plain text suitable for quoting and by flagging the truncation marker. Minor gaps remain — it doesn't say what happens for an invalid or missing text_id, or whether the response is a bare string — but nothing essential to invoking it correctly 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?

With a single parameter at 100% schema description coverage, the schema already documents text_id and the description repeats the same provenance hint. The parenthetical about each version having a date and type adds marginal context for choosing a version but not for the parameter's format itself, so this lands 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 and resource — the cleaned plain text of one bill-text version — plus the underlying endpoint GET /v1/texts/{text_id}. It implicitly distinguishes itself from siblings like get_bill_text_history (versions) and get_bill_diff (comparison) by scoping to a single version's rendered text.

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 concrete guidance on where the required text_id comes from (get_bill with include:['texts'], noting each version carries a date and type). It does not explicitly name sibling alternatives such as get_bill_text_history when the agent wants the list of versions rather than text, so it stops short of full 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real context about the shape of the result (a chronological series of diffs with magnitude), but says nothing about result volume or pagination for what is described as 'all' diffs on a bill.

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 primary purpose and endpoint come first, then the disambiguation and prerequisite, in exactly the order an agent needs them.

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, and the description compensates by summarizing what each diff entry contains. For a small two-parameter read tool this is nearly complete; the only gap is any hint about result size ordering for a bill with many versions.

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 both parameters including the include_whitespace default. The description still adds value by naming the concrete tools that produce a valid bill_id, which is more actionable than the schema's generic 'bill_id from a search result'.

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 resource (the timeline of all computed diffs between successive text versions of one bill) plus the underlying endpoint, and clarifies what each entry conveys: what changed, when, and how much. It is clearly distinguishable from get_bill_diff and from get_bill_text, so an agent can pick it 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 routes the agent: use get_bill_diff for one specific pair of versions, use this for the full succession of diffs. It also removes the main prerequisite blocker by naming search_bills and semantic_search_bills as the source of bill_id.

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?

Annotations already declare this a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description only needs to add context — and it does, by explaining that FEC and Bioguide ids are conditionally present and that people_id signals an available voting record. It stops short of describing not-found or invalid-id behavior, which is the remaining 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?

Front-loaded with the verb, resource, and endpoint, then layers conditional data semantics and follow-on routing. Dense and mostly waste-free, though the REST path restates what the name already conveys.

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 output schema, the description usefully enumerates returned fields and conditional ids, and covers id sourcing plus next-step tools. Only error/empty-result behavior is unaddressed, a minor gap for a single-param read 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% and the single id parameter is fully documented, so the schema carries the load. The description adds the provenance hint (id comes from list_candidates) but omits get_midterms, which the schema does list, so it adds no meaning 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?

States a specific verb and resource ('Fetch one election candidate by id'), names the backing endpoint, and enumerates exactly what is returned (party, office, district, cycle, FEC filer id, Bioguide id). It is clearly distinguishable from sibling list_candidates and get_candidate_photo.

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 explicit entry and exit routing: get the id from list_candidates, and if people_id is set, pass it to get_legislator or get_legislator_scorecard. Both the precondition and the follow-on alternatives are named.

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?

Beyond the read-only and non-destructive annotations, the description discloses important behavioral context: the data sources are official portraits only, each image carries a license and attribution string that MUST be shown when required, and the tool returns null in the common case because only about 11% of the 2026 field has an accepted portrait. These are meaningful operational and compliance details not present in structured fields.

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, then adds only high-value caveats: license attribution, the common null return, and the preferred alternative path through list_candidates/get_midterms. Every sentence contributes to correct selection or 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?

Although there is no output schema, the description fully explains the return value as a URL or null, notes the endpoint's image-byte behavior, warns that null is common, and covers license/attribution obligations. For a one-parameter read-only lookup, this is complete enough for an agent to call and handle 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 description coverage is 100% and there is only one parameter, candidate_id, so the schema already carries the main parameter documentation burden. The description adds contextual guidance about when a bare id is available, but it does not add format or syntax details beyond the schema's anyOf integer/string definition.

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 resource and return value: the URL of a candidate's official portrait, with the underlying GET endpoint noted as returning image bytes. It distinguishes this from candidate-row tools by explaining that list_candidates and get_midterms already include photo_url, so an agent can tell when this standalone photo lookup is appropriate.

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 routing rule: call this only when you have just a candidate id, because candidate rows from list_candidates and get_midterms already include photo_url. It also sets expectations for the common null case and recommends an initials-avatar default, which is directly actionable 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?

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered; the description adds the non-obvious default behavior (no since = last hour) and the near-real-time staleness caveat, which are genuinely extra context. It stops short of describing response shape, ordering, or truncation behavior when limit is hit, which matter for a polling feed.

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 plus a parenthetical example, front-loaded with what it is, then how to use it, then the alternative it displaces. The only mild restatement is the last-hour default, which also appears in the schema, but it is load-bearing for the polling guidance.

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 4-parameter, all-optional read feed with no output schema, the description gives enough to call it correctly: cursor strategy, default window, filter vocabulary, and the monitoring-vs-search decision. Remaining gap is what the returned change objects contain and how to advance the cursor under limit truncation.

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; the description earns above that by explaining the cursor contract in operational terms ('everything newer than your cursor', vs the schema's 'newest timestamp you have already seen') and by enumerating valid reason values that the schema only gives as an example list without an enum constraint.

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 resource and shape: a near-real-time change feed backed by GET /v1/changes, and immediately distinguishes it from re-scanning search_bills. The enumerated reason types (NewBill, StatusChange, Text, Vote, Amendment) tell an agent exactly what kind of content the feed carries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names the use case (monitoring, incremental sync, 'what moved in Florida since yesterday') and the alternative it replaces (re-scanning search_bills). Polling semantics are stated as a directive — pass since as your cursor — leaving no inference needed about incremental usage.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds real value by disclosing that members and hearings are merged into the response and clarifying what each contains (roster with roles, scheduled meetings). It says nothing about response size limits or pagination behavior beyond what the schema's max_items already encodes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with the required parameter, the endpoint, the optional merge behavior, and a sibling pointer — 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 3-parameter read tool with 100% schema coverage and full annotations, this covers invocation fully. With no output schema, it could say a bit more about the returned committee shape, but nothing an agent needs to call it correctly 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, and the description goes beyond it by glossing 'members' as a role-bearing roster and 'hearings' as scheduled meetings, and by explaining the provenance of committee_id. It adds no further detail on max_items semantics (cap vs. default) 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?

States a specific verb and resource ('Fetch a committee by committee_id') plus the underlying endpoint GET /v1/committees/{committee_id}, and names the sibling (list_committees) that produces the identifier — clearly separable from get_legislator, list_committees and get_hearing.

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 routes the agent to list_committees to obtain a committee_id and explains when the optional include sub-resources apply. It lacks an explicit 'don't use this if you just need a list' exclusion, but the context is unambiguous.

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?

Beyond the read-only annotations, the description discloses that results come from a materialised snapshot, that computed_at indicates its age, and that low pct_with_votes often reflects legislative behavior rather than missing data. These are important behavioral and interpretive details that help the agent use the tool correctly.

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 definition and then adds usage guidance, interpretation caveats, and freshness information. Every sentence contributes useful context, and there is no redundant 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 one-parameter, read-only coverage tool with no output schema, the description gives enough detail about what the snapshot contains, how to interpret its ratios, and how fresh it is. Nothing essential for correct invocation appears to be 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?

The only parameter, max_items, is fully documented in the schema, including its default and maximum. The description does not add any parameter-specific meaning beyond that, so the high schema coverage sets the baseline at 3.

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 this tool returns a per-state depth snapshot of data completeness, including bill counts, vote/text/sponsor coverage, and session status. It is specific about the resource and metrics, but it does not explicitly name or distinguish itself from sibling tools such as list_states or list_statute_coverage.

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 a clear use case: check it before drawing conclusions from a thin result set, specifically to distinguish 'no such bills' from 'this state is thinly covered.' It also explains how to interpret the ratios. It does not explicitly name alternatives or state when not to use it.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds important behavioral context: a sitting can run to 850,000 characters and the tool returns a window using offset, max_chars, and next_offset, or search passages. It does not mention rate limits or the schema's 20-passage search cap.

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 purpose, then explains transcript size and window/search behavior, then ends with the prerequisite for obtaining transcript_id. 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 read-only transcript retriever with full schema descriptions and annotations, the description covers purpose, scale, pagination, search behavior, and ID sourcing. Because there is no output schema, it could say more about the structure of returned passages, but it is largely 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 coverage is 100%, so all four parameters are already documented. The description adds practical meaning by framing offset/max_chars as a window and by giving a concrete use for search, such as a bill number or member's name, though it does not add syntax detail for transcript_id.

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 gives a specific verb and resource: the verbatim record of one chamber sitting, covering debate, explanations of vote, and roll calls. It clearly distinguishes this from the listing sibling by saying to get transcript_id from list_floor_transcripts.

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 tells the agent to obtain transcript_id from list_floor_transcripts and explains when to use the search mode versus reading a window. It stops short of explicit when-not-to-use guidance or naming other alternatives beyond the listing 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?

Annotations already confirm read-only safety, but the description adds important behavior: transcripts can exceed a million characters, so the tool returns a bounded window with offset/max_chars/next_offset, or search returns every matching passage. It also clarifies that transcript_url is the official document.

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 then explains the large-transcript handling. It is dense with useful information, though slightly long and could be broken into clearer sentences for faster scanning.

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 output schema, the description must explain return behavior, and it does: the hearing, transcript window, next_offset, search passages with offsets, and transcript_url. It also covers edge cases like missing transcripts and oversized documents.

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 useful semantics beyond the schema: offset and next_offset form a continuation loop, max_chars bounds the window, and search switches to phrase-based passage retrieval rather than a linear window.

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—'One committee hearing or meeting'—and includes the endpoint. It distinguishes itself from siblings by naming list_hearings and get_committee for finding hearing_id, and explains that the tool returns the hearing plus transcript content.

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 tells the agent how to obtain hearing_id via list_hearings or get_committee include:['hearings'] and when to use the windowed read versus the search mode. It also notes that transcripts exist only where has_transcript indicates and gives examples of venues that carry them.

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?

Annotations already cover the read-only, non-destructive, open-world profile, and the description adds substantial context beyond them: merge ordering ('newest first'), the numeric position codes (1=Yea, 2=Nay, 3=Not Voting, 4=Absent), and sponsor_type_id values. Those code decodings materially change how an agent interprets the response.

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 primary action and identifier are front-loaded in the first clause, with the optional merges and their semantics following. Every parenthetical earns its place by decoding data the agent will otherwise misread.

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, yet the description explains what the merged sub-resources contain and how to read their numeric codes, plus the corpus boundary. Combined with a fully documented schema and safety annotations, nothing essential to 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 coverage is 100%, so baseline is 3; the description goes further by explaining what the 'include' values actually pull in and that limit applies per included sub-resource. The parenthetical code tables describe returned data rather than parameters, so it doesn't fully saturate parameter 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?

States a specific verb and resource ('Fetch a legislator's profile by people_id'), includes the underlying endpoint, and explicitly enumerates the two optional sub-resource merges. An agent can distinguish this from list_legislators or get_legislator_scorecard without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent on how to obtain the required key ('Find a people_id with list_legislators or from a bill's sponsors') and states the corpus constraint (2026-forward only). It lacks an explicit statement of when NOT to use it (e.g., bulk retrieval vs. list_legislators), which keeps it just below the top.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered; the description adds genuinely new context: it is a 'one-call' aggregate that returns several derived metrics in a single response, plus the underlying endpoint. With no output schema, this enumeration of returned metrics is the agent's only signal about result shape.

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 dense sentences: capability plus return contents first, intent routing and ID resolution second. Nothing is redundant with the title, and no sentence could be removed without losing 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 single-parameter read tool with no output schema, the description covers purpose, contents, and ID resolution adequately. It stops short of saying what period the scorecard covers (current session vs. career) or how the alignment metric is computed, which are the remaining questions an agent might have.

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 schema already says 'people_id from list_legislators', so the baseline is 3. The description adds a small but real operational detail beyond that — the '(q=name)' hint for resolving the ID — which speeds up the dependent lookup.

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 ('voting and sponsorship profile for a legislator') and enumerates exactly what the profile contains: participation, party-line alignment, bills sponsored and passed, notable votes. The content enumeration also implicitly separates it from the bare 'get_legislator' sibling, so an agent can pick between them without opening a 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 frames the intent triggers ('how does X vote', 'is X effective') and gives the prerequisite resolution path: 'Get people_id from list_legislators (q=name)'. It lacks a stated when-not or a named alternative for raw bio data, which keeps it 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?

Adds substantial behavior beyond the readOnly/openWorld annotations: data is read from the measure's official text, unpublished text yields empty results, the list is a 'floor', and resolved:true distinguishes a section we hold from a bare citation. Doesn't cover pagination or ordering, but the annotation bar is already low 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?

Front-loaded with the resource definition, then caveats; every sentence carries information. The final sentence is dense and packs resolution semantics into one line, which hurts scanability slightly.

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, so the description carries the return-shape burden and does so by explaining the resolved:true/text pairing. Combined with the state-coverage caveat and empty-result condition, an agent has everything needed to call and interpret it.

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 both parameters are already documented, and the description leans on that ('see list_statute_coverage', 'state whose code is loaded') without adding syntax or format detail. 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?

States a specific verb and resource: 'The sections of existing law a 2026 ballot measure amends, creates, repeals or cites', with the underlying endpoint given. This is clearly distinct from sibling get_statute (a single section) and get_bill_statutes (bills, not measures).

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 ('which laws does Prop X / Question Y change') and routes the agent to list_statute_coverage for the coverage question. It also states the cases where the tool returns nothing, which functions as a when-not-to-expect-results rule.

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?

Beyond the read-only annotations, the description discloses data provenance (official state election-office and FEC content collected by Delilah), attribution posture, and critical interpretation rules for live_results, including per-contest entries and closed-primary party vote_pct semantics. These are exactly the behavioral details an agent needs to avoid misusing results data.

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, scope, and the GET endpoint, and every sentence carries useful information. It is somewhat dense, especially the long live_results sentence, but it is not padded or redundant.

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, open-world tool with no output schema, the description covers scope, provenance, key result semantics, and reporting constraints well. It does not fully describe the overall response structure beyond live_results, leaving some return-shape 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?

With 100% schema description coverage, the input schema already documents all seven optional parameters. The description adds no request-parameter guidance beyond what the schema provides, so the baseline 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?

The description states a specific resource and scope: the 2026-11-03 election slate, with races, candidates, ballot measures per state, and official results. This is clear enough to identify the tool, but it does not explicitly route against sibling tools such as get_candidate, list_candidates, or get_ballot_measure.

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 usage contexts ('who is running for X' and results questions) and important cautions about not comparing candidates across contests, not calling/projecting races, and reporting counts exactly. However, it does not say when to prefer a sibling tool over this one.

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?

Beyond the readOnly annotations, the description discloses the underlying endpoint (GET /v1/votes/{roll_call_id}), the returned fields, the semantics of vote_id values (1=Yea, 2=Nay, 3=Not Voting, 4=Absent), and the effect of include:['details']. This adds substantial behavioral context not provided by the annotations alone.

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?

It is a single dense paragraph with no filler, and the core fetch operation is front-loaded. The embedding of endpoint, enum legend, and ID sourcing makes it slightly packed, 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?

There is no output schema, yet the description explains both the summary return fields and the detailed member-vote return shape. It also covers the required ID source and the optional include behavior, so an agent has enough to call the tool correctly without further 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 adds meaning: it explains that include:['details'] pulls individual member positions and decodes the vote_id enum values, which are not in the schema. The max_items default and cap are already in the schema, so the description does not need to repeat 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 gives a specific verb and resource ('Fetch a roll call by roll_call_id') and states exactly what is returned: motion, chamber, date and tallies. It distinguishes itself from siblings by naming get_bill as the source of IDs and describing the include:['details'] variant as the tool for individual member votes.

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 details mode ('this is the tool for "how did each legislator vote on this"') and how to obtain the required ID ('Get a roll_call_id from get_bill with include:['votes']'). The alternative source path is named, leaving little inference for an 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?

Annotations already declare readOnly, openWorld, and non-destructive behavior. The description adds endpoint paths and the full status_id ladder plus aggregate buckets (passed/failed/alive), which is real domain behavior beyond annotations. It does not discuss auth, rate limits, or response shape, but with annotations present this is solid.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense paragraph front-loads purpose, then endpoint, prerequisite, and domain mappings; every clause is useful for interpreting counts. There is 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 two-parameter count tool with no output schema, it explains grouping modes, status codes, and bucket semantics, which is enough to call and interpret. It stops short of describing exact response shape or subject identifiers, but those are minor 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?

Schema description coverage is 100%, so baseline is 3; the description adds meaning by explaining by='status' vs by='subject' and giving the full status_id mapping and aggregate buckets. It also tells where session_id comes from, exceeding 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?

The description states a specific verb ('Bill count') and resource ('per status ... or per subject') scoped to one session, and the title reinforces it. It does not differentiate from siblings such as get_session_dashboard or get_weekly_stage_breakdown, so 4 rather than 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives the prerequisite 'Get session_id from list_sessions' and implies use for session-level bill counts, but never says when to choose this over get_session_dashboard, get_weekly_stage_breakdown, or list_bills_by_stage. No explicit exclusions or alternatives are provided.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description goes beyond them by naming the six aggregate metrics returned, effectively documenting the response shape in the absence of an output 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?

Three compact sentences, front-loaded with the resource and metrics, then usage cue, then prerequisite. No filler or restatement of 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 one-parameter read-only aggregate tool with no output schema, the description supplies both the invocation prerequisite and the returned metrics, leaving no material gap an agent would need filled before calling it.

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 parameter's schema description already says 'session_id from list_sessions (filter by state)', so the description's identical guidance adds no new syntax or format detail. Baseline 3 is appropriate when the schema fully carries parameter 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?

States a specific verb+resource ('Headline counts for one legislative session') and enumerates the exact metrics returned (bills filed, passed, signed, vetoed, roll calls, active legislators), plus the endpoint. This makes it clearly distinguishable from narrower siblings like get_session_breakdown or get_session_vote_participation.

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 entry-point cue ('Start here for "how is the 2026 Florida session going"') and prerequisite routing ('Get session_id from list_sessions'). It lacks an explicit when-not-to-use or named alternative for drill-downs (e.g., get_session_breakdown), which keeps it 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?

Beyond the read-only annotations, it discloses the row fields returned, defines pass_rate via status codes 4, 5, and 8, and notes that committee sponsor rows are excluded by default. These are meaningful behavioral details, though it does not discuss auth, rate limits, or error 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 front-loaded with the core ranking behavior and return fields, followed by usage triggers, exclusion behavior, and the prerequisite for session_id. Every sentence contributes relevant context without 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?

There is no output schema, but the description explains the returned row fields and pass_rate calculation. Combined with the fully documented input schema and read-only annotations, an agent has enough information to invoke this tool 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, but the description adds useful meaning for key parameters: chamber filtering, sort:'passed', sort:'primary_passed' counting only carried bills, and sourcing session_id from list_sessions. It does not add much for party or limit, which the schema already documents.

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 operation and resource: legislators ranked by bills sponsored and passed in one session. It also names the endpoint and distinguishes the tool as the one call for activity/effectiveness ranking, so an agent can separate it from sibling session 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?

It gives concrete usage triggers such as 'who is most active or effective this session' and 'which senator passed the most bills', and explains how to set chamber and sort. It also tells the agent to get session_id from list_sessions, but does not explicitly state when not to use this tool or name a competing alternative.

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?

Annotations already declare this is a safe read-only operation, so the description needn't repeat safety. It adds useful semantic context that the output is a comparison of votes cast vs missed per legislator, but does not mention auth needs, pagination behavior beyond the limit param, or response shape.

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, front-loaded sentences that each carry information: definition, usage condition, and prerequisite. 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 read-only analytics endpoint with full schema coverage and annotations, the description is nearly complete. It clarifies the metric being returned, though it could note pagination behavior or typical response ordering.

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 both parameters are already documented. The description adds value by specifying where session_id comes from (list_sessions), but does not explain the limit parameter or add anything beyond the schema 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 metric and scope: per-legislator voted-vs-missed roll-call counts for one session. An agent can distinguish this from generic session tools like get_session_breakdown or get_roll_call by the attendance measure, though no sibling is named explicitly.

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 a clear use case ('attendance questions') and a concrete prerequisite (session_id from list_sessions). It could go further by saying when to prefer this over get_session_breakdown or get_roll_call, but the context is 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?

The description adds substantial behavior beyond the annotations: it explains that only loaded state codes resolve to text, that held links return resolved:true with text, and that otherwise only the citation is returned. It also discloses that include_bills retrieves bills that amend, create, repeal, or cite the section.

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 core purpose is front-loaded, followed by concise invocation guidance, examples, and resolution behavior. The paragraph is dense but every sentence contributes useful information for correct 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?

With no output schema, the description carries the burden of explaining return behavior, and it does so by specifying full text, code placement, resolved:true behavior, citation-only fallback, and optional related bills. Coverage limitations are also called out via list_statute_coverage.

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, but the description adds useful semantics for citation formatting, section_id provenance, and include_bills behavior. It does not explain the code parameter, but the schema already documents that parameter 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 states a specific resource and operation: retrieve one statute section with full text and its code placement. It also distinguishes retrieval by section_id versus citation lookup, making it easy to differentiate from search_statutes and related sibling 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?

It explicitly says how to supply either a section_id from a search or bill/measure link, or state plus citation in code format. It also names list_statute_coverage as the prerequisite check for loaded states and explains when to set include_bills.

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?

Annotations already cover the read-only, non-destructive, open-world safety profile, so the description's added value is the return shape: bill summaries plus mention counts, scoped to a look-back window. It doesn't disclose rate limits or pagination, but that is minor given annotation coverage.

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 clauses with the core purpose front-loaded, followed by usage triggers and a routing hint. No filler or redundant restatement of the name.

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 output schema, the description compensates by describing what comes back (summaries with mention counts) and where to go for detail. Bounds on days/limit live in the schema, so nothing essential to correct invocation 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 parameters are fully documented in the schema; the baseline is 3. The description only loosely references the window and the optional state filter and says nothing about limit, adding little 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?

States a specific verb+resource (bills with most news coverage) plus the underlying endpoint and an optional state filter. It is clearly distinguishable from search_bills and keyword_search_bills, which retrieve by query rather than by news prominence.

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 explicit use-case triggers ('what's in the news', 'hot bills right now') and routes the agent to get_bill for detail. It does not explicitly say when to prefer keyword_search_bills or search_bills instead, but the intended usage is 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds valuable context by specifying the return fields and the endpoint. It omits whether the call is scoped to the current key's auth context (implied by 'current key'), which is a minor residual 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 payload description and the usage trigger. The endpoint reference is compact and useful; nothing is redundant with 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?

With no input schema parameters and no output schema, the description carries the burden of telling the agent what comes back — and it does so by enumerating the returned fields. Nothing needed to call and 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?

There are zero parameters, so parameter semantics have no surface area to cover. Score follows the 0-params baseline, and the description correctly does not fabricate any parameter detail.

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 precise verb+resource ('get usage' of the current key) and enumerates what is returned: tier, monthly cap, requests used/remaining, and reset time. It even includes the underlying endpoint (GET /v1/_meta/usage), leaving no ambiguity about what data is fetched.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names the trigger conditions: call when a request is rate-limited (HTTP 429) or when the user asks about their plan. This is exactly the when-to-use guidance an agent needs, and no sibling tool competes for that scenario.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description isn't required to prove safety. It still adds real behavior: the aggregation key is 'latest action' (not first action or any action) and results are fleet-wide rather than per-jurisdiction, which materially changes how the numbers can be interpreted. It stops short of noting data lag or coverage limits, which matters given openWorldHint=true.

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 with zero filler: the aggregation semantics come first, then the disambiguation. The trailing endpoint path is the only arguable excess, and it is short.

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?

It describes the return shape ('one row per stage with the number') despite there being no output schema, and it names the one alternative that could be confused with it. Minor gaps: no statement about whether stages with zero bills appear, and no coverage/freshness note for an openWorld 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 description coverage is 100% and the single `days` parameter is fully documented there with bounds and a default of 7. The description only implicitly echoes it via 'in the window' and 'this week', adding no format or edge-case guidance beyond the schema, 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 specific verb+resource: one row per stage with a count of bills whose latest action landed there in the window, across all jurisdictions. That is a precise aggregation contract an agent can match against a request, and it is distinguishable from sibling tools without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes: use this for a national 'how much moved this week' number, use get_session_dashboard for a single state. The when-to-use and the alternative-to-use are both named in one clause.

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?

Annotations already cover safety (readOnlyHint, destructiveHint=false), so the description's value-add is the disclosure of the 2026-forward-only corpus and the 'up to 10 terms' ceiling — both non-obvious constraints that affect whether a call will succeed. It also notes the return shape (summaries plus pagination), though it does not say what happens with zero matches or how ranking works.

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 short sentences, front-loaded with the defining constraint and followed by routing guidance, then limits, then return shape. Nearly every clause earns its place; only the endpoint path is arguably redundant for an agent that never constructs URLs.

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 output schema, the description usefully states that results are bill summaries with pagination. Combined with the corpus-scope warning and the alternative-tool routing, an agent has enough to decide and call correctly; only edge-case behavior (empty result sets, term matching rules such as stemming/phrase handling) is unstated.

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 limit, offset, state, and keywords are all documented in the schema already. The description reinforces the keywords cap ('Up to 10 terms') and gives an example of valid term formatting, but adds nothing about state filtering or pagination semantics. Baseline 3 is appropriate when the schema carries the load.

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 mechanism (AND-semantics keyword search where every term must appear) plus the endpoint, which is far more precise than the sibling 'search_bills' and immediately distinguishable from 'semantic_search_bills'. The title and first clause agree and leave no ambiguity about the resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names the selection condition (user gives specific words that all must be present) with a concrete example, and routes to both alternatives: semantic_search_bills for natural-language questions and search_bills for structured filters. This is exactly the when/when-not/alternative structure the dimension rewards.

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?

Annotations already declare readOnly/openWorld/no-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: results are classified from action text rather than status_id, and scope is all jurisdictions with no state filtering — both materially affect how an agent interprets 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?

One dense but front-loaded paragraph: the defining behavior comes first, then scope caveat, then classification note, then example queries. The endpoint path is minor noise, but almost 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?

With no output schema, the description still tells the agent enough to use and post-filter results (rows carry state_id/state_name). Defaults for days/limit live in the schema, so nothing critical is missing; return field shapes are only partially implied.

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 enums document the stage values, so the schema carries most weight. The description adds meaning beyond it by expanding 'executive' into its three sub-cases (with the governor, signed, vetoed) and noting stage values are lowercase, which reduces enum-lookup errors.

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 (bills whose LATEST action falls in a stage) and enumerates the stage taxonomy, plus the backing endpoint. An agent can immediately distinguish this from search_bills or get_weekly_stage_breakdown without opening a 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 concrete use cases ('what passed this week', 'what reached the governor') and a key constraint: fleet-wide, no state filter, filter rows by state_id/state_name yourself. It does not name a specific sibling alternative (e.g., get_weekly_stage_breakdown) for aggregate/count needs, so it stops short of full 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?

Annotations already declare read-only/open-world safety, so the description adds useful data-quality context: filters combine with AND, roughly a third of rows carry an FEC id, only sitting members carry a Bioguide id, and people_id is populated only when a voting record exists. It does not cover pagination totals or result ordering, but the behavioral context it does add is substantive.

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 and front-loaded with purpose, then routing hints. Every clause carries information, though the middle sentences about FEC and Bioguide ids are somewhat compressed.

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 return values. It describes key row fields (fec_id, bioguide, people_id) and coverage, but omits the candidate name/id field and pagination behavior, leaving minor gaps for an agent forming expectations about results.

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 explaining that filters combine with AND and by clarifying when fec_id and bioguide will be non-null, which helps the agent interpret filter 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?

States a specific verb and resource ('Search the election-candidate directory... people running for office') plus the underlying endpoint. This clearly separates it from siblings like list_legislators and get_candidate.

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 routes the agent: use get_candidate for the full record via candidate id, and get_legislator / get_legislator_scorecard for voting history via people_id. It states scope (STATE and federal candidates) but does not explicitly contrast with 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?

Annotations already cover read-only, non-destructive, open-world behavior, so the description's job is additive — and it adds the endpoint path and the fact that results are id values intended for a follow-up call. It does not mention result counts, pagination, or ordering, which keeps it below the top score.

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 short sentences, both earning their place: the first gives capability and filters, the second gives the return contract and downstream use. It is front-loaded with the operation and nothing is repeated.

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 output schema, the description correctly compensates by stating what is returned (committee_id values). Minor gaps remain — no mention of default result size or whether results are paginated — but the schema's limit parameter covers most of 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 coverage is 100%, so all four parameters are already documented in the schema. The description restates the three filter dimensions (name search, chamber, jurisdiction) at a high level but adds no format or edge-case detail beyond what the schema says, 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 specific verb and resource ('List legislative committees') plus the underlying endpoint, and explicitly says what it returns ('committee_id values'). It also differentiates from the sibling get_committee by framing this tool as the lookup that feeds 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?

Gives clear usage context through the filter dimensions and the workflow hint that its output is the input to get_committee. It stops short of an explicit exclusion rule (e.g. 'use get_committee when you already have an id'), but the implied routing is easy to infer.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds valuable context beyond annotations: the boundary polygon is large and benefits from simplify (with an example), and matching should be numeric. It doesn't cover rate limits or pagination, but this is a strong addition.

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 dense sentences, front-loaded with the primary purpose, then boundary specifics, then a critical matching note. Zero wasted words and every sentence carries actionable 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?

Given 7 parameters, no output schema, and moderate schema coverage, the description covers the complex boundary and matching behavior well. However, it doesn't explain return fields, default pagination, or how limit/offset affect results, which are relevant for a list tool without 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?

Schema description coverage is 71%, so the baseline is 3. The description adds meaning for boundary, simplify (with example), and district_id (numeric matching), but completely omits limit and offset, which are undocumented in both schema and description. This leaves a notable gap for a list 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?

States a specific verb and resource: district metadata by state and type, listing the exact types (congressional, sldu, sldl). Also clearly describes the secondary boundary retrieval mode. An agent can distinguish this from all sibling tools, none of which deal with districts.

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 operational guidance: pass district_id with boundary:true to get a polygon, and set simplify to shrink it. Also warns to match districts numerically, not by label. It doesn't explicitly name when-not-to-use or alternatives, but none are needed given the unique resource.

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?

Annotations already cover the safety profile (readOnly, non-destructive, openWorld), so the description's job is added context — and it delivers: newest-first ordering, exact coverage boundary (NY Senate, 2025 onward), and the fields each row carries including the official PDF. It does not mention result-size behavior or paging semantics beyond what the schema states, keeping it short of 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?

Three tight sentences: what it is, what a row contains, how coverage is bounded, then two routing pointers. Front-loaded with the resource identity and 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?

With no output schema, the description usefully enumerates the row fields, so an agent knows what comes back. The one gap is the mismatch between the stated NY-Senate-only coverage and the presence of state/chamber parameters that imply broader jurisdiction — worth a sentence of explanation, but not enough to block 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 all six parameters (limit, offset, since, until, state, chamber) are already documented in the schema and the baseline is 3. The description adds only the 'newest first' ordering, which implicitly informs how since/until/offset behave, but it never explains why state/chamber filters exist when coverage is stated as NY-only.

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?

Specific verb+resource ('Verbatim stenographic records of chamber floor sessions'), plus the backing endpoint and the row shape returned (date, session type, length, official PDF). It explicitly distinguishes itself from get_floor_transcript (single record) and list_hearings (different resource), so an agent can pick it without opening a 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?

Names both alternatives and the condition that selects each: 'Read one with get_floor_transcript' and 'For committee hearings use list_hearings.' The coverage statement ('the New York Senate, every sitting from 2025 on') also tells the agent when this tool will return nothing useful.

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?

Annotations already declare read-only, non-destructive, open-world behavior. The description adds value beyond them: sort order (newest first), the fact that has_transcript:true rows expose a verbatim transcript sized transcript_chars, and a pointer to get_hearing for reading it. It stops short of stating pagination behavior or result volume limits, but the key behavioral traits are 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?

Four sentences, each load-bearing: purpose+scope, use case, transcript behavior, and sibling routing. Purpose is front-loaded and there is no redundant restatement of 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?

No output schema exists, yet the description still conveys row shape (has_transcript, transcript_chars), ordering, and how to drill into a record. Combined with five optional, fully documented parameters and a safe-read annotation profile, an agent has everything needed to call this 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 limit/offset/since/state are already documented. The description adds real meaning to has_transcript beyond the schema's filter wording by explaining the consequence of the flag (a verbatim transcript of transcript_chars length read via get_hearing), and frames 'jurisdiction and start date' as the primary filter axes.

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?

Specific verb+resource (committee hearings and meetings), with explicit endpoint, ordering ('newest first'), and filter dimensions. It is clearly distinguishable from get_hearing (single record), get_committee, get_bill, and list_floor_transcripts, which are all named.

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 a concrete use case ('what is being heard this week', tracking next committee meeting) and then routes to alternatives with explicit conditions: get_committee with include:['hearings'] for a single committee, get_bill with include:['calendar'] for a single bill, list_floor_transcripts for floor sessions.

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?

Annotations already declare readOnly/openWorld safety, so the bar is lower. The description adds a genuine behavioral fact not in structured data — 'Filters combine with AND' — which changes how an agent composes queries. It omits pagination/return-shape notes, so not 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?

Three tight sentences with the search capability front-loaded and the key routing hint last; no filler, 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?

Seven optional params with full schema coverage plus annotations covering safety — the description is sufficient to call it correctly. Return fields are unspecified (no output schema), but for a list endpoint the shape is predictable enough that 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 all seven parameters are already documented. The description only restates the filter dimensions (and uses 'jurisdiction' where the schema says 'state'), adding little beyond the schema; 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?

States a concrete verb+resource ('Search or list legislators'), names the endpoint, and enumerates the filter dimensions, making it trivially distinguishable from get_legislator and list_session_legislators.

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 identifies the workflow role: 'This is how you turn a name into the people_id that get_legislator needs,' naming the sibling and the condition that selects it. That is a precise when-to-use rule, not mere 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only a small amount beyond that — the returned people_id and the endpoint path — and says nothing about result volume, ordering, or whether historical vs. special sessions differ in coverage.

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 with the resource definition front-loaded, then the disambiguation, then the prerequisite. No sentence is redundant, and the sibling comparison arrives before the caller needs it.

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-only list tool with full schema coverage and clear annotations, the description supplies purpose, alternative, and input source — enough to invoke correctly. Minor gap: no expectation set for result size or pagination on a session roster, and there is no output schema to cover 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 coverage is 100% for the single session_id parameter, and its description already says 'session_id from list_sessions (filter by state).' The tool description largely repeats that sourcing hint rather than adding new format or constraint information; baseline 3 applies when the schema does the 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?

States a specific verb+resource ('Every legislator who served in one session') and even names the underlying endpoint, plus the key returned identifier (people_id). It explicitly distinguishes itself from the sibling list_legislators, so an agent can choose 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 a direct alternative with its condition: 'Use list_legislators for the current roster by state; use this for a specific past or special session.' It also names where the required input comes from ('Get session_id from list_sessions'), leaving nothing to inference.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds genuinely new behavioral context: the corpus boundary (2026-forward) and the omit-state semantics that change result scope. It stops short of stating pagination/ordering behavior beyond the schema's max_items cap, so not 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?

Three sentences, each earning its place: resource + returned fields first, then actionable use cases, then the scope caveat. Front-loaded and free of filler; the only nit is the 'sine-die' typo for sine die.

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 two-parameter read-only list tool with no output schema, everything needed is present: what comes back, when to call it, how to route the result into search_bills, and the temporal limit. Nothing an agent must know to call it correctly 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 meaning the schema does not: omitting `state` switches the call from a state-scoped list to a full multi-jurisdiction list. That is a semantic consequence of a parameter, not a restatement of its type.

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 resource (legislative sessions, GET /v1/sessions) and enumerates exactly what a row contains: year, start/sine-die dates, session_id, and the regular-vs-special distinction. An agent can distinguish this from get_session_breakdown or get_session_dashboard, which are analytics siblings, 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 three concrete use cases (resolve a bill's session, find the current session for a state, obtain a session_id for search_bills) plus an explicit negative case: omit `state` to list every jurisdiction. The corpus caveat ('2026-forward only') prevents a known failure mode before the call is made.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds context the annotations cannot: the endpoint, the exact row count (52), and that the full list is returned with no filtering or pagination. It stops short of describing response ordering or formatting, but that is minor.

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: the first front-loads what the resource is and what fields come back, the second routes to the alternative. No filler or repetition of the name/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?

There is no output schema, but the description compensates by naming the returned fields (state_id, 2-letter code, full name) and the row count. For a simple no-param read tool, an agent has everything needed to call it 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?

The tool takes zero parameters and the description correctly implies a no-argument full-list call, so there is nothing to misinterpret. Baseline 4 applies for a parameterless 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?

States a specific resource (jurisdiction directory, GET /v1/states) and exact scope: the 50 states, D.C. and the U.S. Congress, with the fields returned. It is clearly distinguishable from sibling enforcement/coverage tools by naming get_coverage as the tool for completeness data.

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 two explicit use cases (resolve a name to a code, enumerate everything the corpus covers) and names the alternative, get_coverage, plus the condition that selects it. Nothing is left to inference.

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?

The read-only annotations already establish safety and non-destructiveness, and the description adds useful behavioral detail about the GET endpoints and the coverage fields returned. It does not discuss auth or rate limits, but those gaps are minor for a read-only metadata 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 three tight sentences with no filler, and it front-loads the purpose before describing the state-specific behavior and recommended first-call usage.

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 output schema, the description still explains what is returned: jurisdiction coverage, code and section counts, bill links, edition currency, and state-specific code IDs. That is sufficient for a one-optional-parameter read-only 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 state parameter is already documented in the schema. The description adds value by explaining that passing state lists that state's codes and produces code_id values consumed by get_statute.

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 resource and scope: which jurisdictions' codified law is loaded, with per-state counts and currency. It distinguishes the tool from get_statute by explaining that state queries return code_id values used by those lookups.

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 to call this first to check whether a state's statutes are available, and explains that passing state switches to listing that state's codes. This gives clear when-to-use guidance and names the related get_statute dependency.

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?

The description adds behavioral context regarding the nature of the data, explaining that subjects are 'raw' and 'the fine-grained categories the legislatures themselves assign to bills,' which is valuable context beyond the standard API call structure. Annotations already cover safety (readOnlyHint: true), meaning the description is providing high-quality utility context.

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 definition is highly efficient; every clause is necessary, and the logical flow—defining the resource, explaining its context relative to siblings, and then giving usage tips—is optimally structured.

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 complete schema coverage and the safety annotations provided, the description is maximally complete. It leaves no ambiguity about the purpose, limitations, or proper integration of the returned subject IDs.

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?

Since schema description coverage is 100%, the description does not need to elaborate on the parameters. It adds mild semantic value by contextualizing 'state' (jurisdiction) and 'q' (narrow search) but follows the baseline score for fully documented 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 explicitly states it provides the 'raw subject taxonomy with per-subject bill counts.' It clearly identifies subjects as fine-grained legislative categories, and effectively distinguishes this tool from 'list_topics' which uses 'curated topic slugs'.

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 both when and how to use the tool, advising agents to use it to 'find a subject_id to filter search_bills by' and to 'gauge what a jurisdiction is legislating on.' It also instructs on parameter use: scope with 'state' and narrow with 'q'.

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?

Annotations already establish read-only, non-destructive, open-world behavior, so the description's job is to add context — which it does by disclosing that the no-slug call returns counts and that the slug call returns topic detail plus a sample of raw subject names folded in. It does not mention pagination behavior beyond max_items or ordering of results, which keeps 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?

Three tight sentences with the core description front-loaded, followed by the usage guidance and then the hand-off to search_bills. No filler or restated name/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?

There is no output schema, so the description must convey return values — and it does for both modes (taxonomy with bill counts; slug detail with raw subject sample). For a two-parameter read-only tool with full schema coverage, nothing an agent needs to invoke it correctly 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; the description goes beyond it by explaining the behavioral consequence of passing a slug (detail plus sample raw subjects) versus omitting it (whole taxonomy), which the schema only states neutrally. It says nothing extra about max_items, capping the score at 4.

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 resource (canonical topic taxonomy with per-topic bill counts) plus the backing endpoint, and explicitly explains the two modes (list vs. single-slug detail). It also distinguishes itself from search_bills, so an agent can place it in the toolset without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit when: 'Call this first to find the right slug ... instead of guessing one.' It also names the alternative and the condition for choosing it: to get actual bills, use search_bills with topic=<slug>. Both the use case and the hand-off are spelled out.

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?

Annotations already declare readOnly/openWorld/non-destructive, and the description goes well beyond by disclosing the corpus boundary ("2026-forward only"), that results are summaries plus pagination rather than full records, and that a bill number placed in q matches directly. These are behavioral facts the annotations and schema do not carry.

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 purpose, then trigger, then filter behavior, then the get_bill handoff — a sensible order with no filler sentences. The status_id value list and aggregate buckets are useful domain knowledge but occupy half the description and duplicate the schema, costing some tightness.

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 13-parameter tool with no output schema, the description covers what is returned (summaries plus pagination), where to go for the full record, and a real coverage limit in the 2026-forward corpus. Nothing an agent needs to call this correctly 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; the description earns an extra point by adding real semantics the schema lacks — the AND-combination rule and the non-obvious q behavior where "HB 1" or "SB0002" resolves to a specific bill. The long status_id enumeration is, however, a verbatim restatement of the schema field rather than added 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?

Names a specific verb and resource ("Search or list legislation") and scopes it with "structured filters," which implicitly separates it from the free-text keyword_search_bills and semantic_search_bills siblings. It explicitly routes to get_bill for full records, but never names the closest search siblings, so the 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?

"Use this when you know the jurisdiction, sponsor, topic, or status you want" gives a clear positive trigger, and "Every filter is optional and they combine with AND" tells the agent how filters behave. It states no explicit exclusion (e.g., use keyword_search_bills when you have only a fuzzy phrase), so the when-not case is left to inference.

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?

Annotations already declare this is a read-only, open-world, non-destructive operation, and the description goes well beyond that by disclosing a non-obvious failure mode: only states with loaded codes resolve to section text. It also explains the resolved:true marker and the degraded 'citation as written' fallback, which an agent would otherwise misread as a bug.

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 use case are front-loaded in the first sentence, and every clause adds information. The final sentence is dense and slightly run-on with its two-part resolved/not-resolved condition, but no sentence is 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 4-parameter read tool with no output schema, the description covers return shape (matching sections with headings and excerpts), the follow-up path, and the coverage limitation. It stops short of explaining result ordering, pagination behavior, or what to do when zero sections resolve.

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% with solid descriptions on q, code, and state, so the schema carries most of the load and the description adds little beyond restating 'state'. The undescriptioned limit parameter is never addressed, though its 1-100 bounds are self-explanatory from 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+resource ('Full-text search of a state's codified law') plus the endpoint, and immediately separates itself from the bill-search siblings by framing the query as 'what does the law say about X'. The follow-up mention of get_statute makes the search-then-fetch division of labor 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?

Gives two concrete use cases (asking what the law says, and locating the section a bill or ballot measure changes), names the alternative tool for the follow-up step (get_statute), and adds a critical prerequisite gate pointing at list_statute_coverage. When-not-to-use is implied by the coverage caveat rather than left to inference.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds a genuinely non-obvious corpus constraint ('Corpus is 2026-forward only') and the returned field set. It stops short of explaining what match_score means (presumably 0-1 similarity) or any pagination/ranking behavior, so a 4 rather than 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?

Purpose and sibling routing are front-loaded, and the trailing status_id/bucket block earns its length because the schema has zero enums and there is no output schema. It is dense but not padded; the only redundancy is a 'match_score' mentioned up front and then absent from the enumerated return fields.

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 output schema, the description compensates by enumerating returned fields and decoding status_id values including the resolution edge case (bill_type_id 2) and the passed/failed/alive aggregate buckets. Combined with the corpus scope limit, an agent has everything needed to call and interpret this 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 description coverage is 100%, so the baseline is 3. The description earns one step above baseline by illustrating the form the 'query' parameter should take (topical natural-language phrases rather than keywords or bill numbers), which the schema's 'The question or description, in plain English' only asserts.

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?

Opens with a specific verb+resource ('Vector search over the full text of every bill') and includes the endpoint. The plain-English query examples ('protecting kids from social media') make the retrieval mode unmistakable and distinguish it from structured or keyword 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?

Explicitly routes between three competing search tools: 'Prefer this over search_bills for questions and topics; prefer search_bills for a known bill number, sponsor, or status filter, and keyword_search_bills for exact terms that must all appear.' Both the when and the when-not are spelled out with the selecting condition.

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