bill-commons

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

Goes well beyond the annotations (readOnly/idempotent/non-destructive) by disclosing that snapshots are NOT archived, that snapshot_id is a change detector rather than a retrieval handle, and that it only changes when a cited fact changes. It also describes the returned how_to_cite structure and labeling of official vs. derived content — exactly the non-obvious behavior an agent needs.

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

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

Three tight paragraphs, front-loaded with what the packet contains, then the return shape, then the optional scoping parameter. Slightly long, but each sentence carries distinct information and nothing is 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?

With no output schema, the description itself documents the return surface (cite_as sentence, permalink, download_url, snapshot_id) and its semantics. Combined with the labeling behavior and the snapshot caveat, 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 0%, so the description must compensate. It explains `question` well (recorded scope, echoed into the artifact) but leaves `bill_id` and `include_full_text` undefined — an agent cannot tell from the description whether include_full_text defaults on or what format bill_id takes.

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 ('Compile') and resource ('citation-ready evidence packet for a bill') and enumerates exactly what the packet contains (official record, history timeline, member-level votes, hearings). This is clearly distinguishable from siblings like get_bill_record (raw record) and trace_legislative_history (history only), since it composes all of them into one cited artifact.

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?

Usage is implied rather than stated: an agent can infer this is the tool for producing a citable, self-contained packet, and the snapshot/citation discussion hints at the 'check a citation later' workflow. However, it never explicitly contrasts with get_bill_record or trace_legislative_history, nor states when NOT to build a packet.

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, idempotent, non-destructive, closed-world. The description adds genuinely non-obvious behavior: the default-to-earliest/latest rule, the error condition, and the important provenance caveat that output is 'derived' rather than an official document. This is meaningful context beyond the annotation set.

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 operation and then the default/error/provenance details. Every sentence carries information; only the ordering could be marginally tightened.

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 adequately characterizes the return (unified + structured diff, labeled 'derived'). Default and failure behavior are covered for a 3-param read tool; only bill_id semantics remain 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 description coverage is 0%, so the description must compensate. It does well for version_id_a/version_id_b by explaining the default when omitted, but bill_id semantics are never stated and the relationship/ordering of A vs B is left implicit. Partial compensation 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?

States a specific verb (diff/compare) and resource (a bill's extracted text versions), with the scope 'unified + structured' and the determinism guarantee. An agent can distinguish this from siblings like trace_legislative_history or get_bill_record 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?

Clearly explains the default behavior when version ids are omitted (earliest vs latest texted version) and names the precondition that will cause failure (<2 versions with extracted text). It does not explicitly point to alternative tools for version listing, so it stops short of full when/alternatives 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 cover readOnly, idempotent, non-destructive, and closed-world. Beyond that, the description adds genuinely useful behavioral context: results are computed by deterministic trigram similarity across jurisdictions and are explicitly labeled 'derived,' not official cross-references. This manages expectations about both determinism and result trustworthiness.

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

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

Two tight sentences with the core operation front-loaded and the trust caveat relegated to second position. No filler, though the multiline formatting adds no structural value.

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 characterizes what comes back (derived similar-title matches, cross-jurisdiction). But it omits output shape, ordering, and what limit does, leaving meaningful gaps for a search-style 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 0%, and neither 'bill_id' nor 'limit' is explained anywhere. With two parameters undocumented in the schema, the description carries the full burden and supplies nothing about what bill_id expects or what limit controls.

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 ('Find'), resource ('bills'), and distinctive method ('similar titles via deterministic trigram similarity'), which clearly separates it from exact-match lookups like get_bill_record. It does not, however, explicitly name or contrast itself with any sibling tool such as search_legislation.

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

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

The description implies a fuzzy-title use case but never states when to prefer this over search_legislation or get_bill_record, nor any prerequisites. The 'derived, not official' caveat describes the nature of results rather than guiding tool selection.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds that results are limited to sessions "flagged active," which is useful scoping, but it does not characterize the active flag, return shape, or ordering. Moderate added value against a low annotation bar.

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 that states the resource, its scope, and the optional filter with zero 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 list tool with rich annotations and no output schema, the description covers what is returned at a high level, the filter, and the filter format. It stops short of defining what "active" means or naming returned fields, which is a minor gap given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the single parameter is an untyped string, so the description carries the burden. It compensates by specifying accepted formats (two-letter state code or name) and that the filter is optional, which the schema does not convey.

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 (List) and resource (legislative sessions) with a clear scope qualifier (currently flagged active). No sibling tool deals with sessions, so it is distinguishable in practice, though it never names an alternative. Clear but without explicit sibling differentiation.

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

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

"optionally filtered by jurisdiction" implies the filter's use case but gives no when-to-use/when-not guidance, prerequisites, or alternatives. Adequate implied usage, nothing more.

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, idempotent, non-destructive behavior, so the bar is lower. The description adds real value by disclosing the content shape of the returned record and the dual lookup semantics, though it says nothing about size limits or truncation when full text is included.

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 return contents and lookup modes front-loaded; the example is embedded where it is needed and 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?

With no output schema, the description's enumeration of returned fields does the work of explaining the response, and the lookup guidance removes ambiguity about argument combinations. Complete for an agent 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 0%, so the description must compensate, and it does for four of five params: bill_id is a UUID, jurisdiction+identifier form the human bill number path, and session disambiguates. The include_full_text flag is never mentioned, leaving one parameter unexplained.

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 (fetch) and resource (one bill's full record), and enumerates exactly what the record contains: metadata, sponsors, subjects, actions, versions, vote-event summaries. This distinguishes it from siblings like get_vote_details or trace_legislative_history without needing to inspect schemas.

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

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

Clearly explains the two lookup paths and when to use each: bill_id for UUIDs, jurisdiction+identifier for human bill numbers, with session to disambiguate. Includes a concrete example (jurisdiction="NC", identifier="HB 123"). Does not name explicit alternatives or exclusions, so 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 readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds real behavioral caveats: coverage status measures stored bill/text availability only, timestamps can advance on count recomputation without new data, and statewide semantic freshness is unverified even for GREEN. These warnings meaningfully shape interpretation of 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 core return behavior is front-loaded, which is good, but the text is dense and stacked with undefined jargon ('state-machine status', 'bounded retained official-source observation health'), and the three trailing caveat sentences are compressed to the edge of parseability.

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 convey return content, and it does: status per state, full matrix on omission, public-registry/unlisted row counts, observation health, and evidence links. The main gap is failing to explain the possible status values (e.g. what GREEN/BLACK mean) beyond warning about freshness.

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 0% and the single 'state' param is undocumented in the schema, so the description carries the load. It specifies the acceptable forms (abbreviation or name) and the important semantic that omission yields the full stored coverage matrix, which is the key behavior of this argument.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Return the jurisdiction_coverage state-machine status') and states the two modes of operation (single state vs full matrix when state is omitted). No sibling covers jurisdiction coverage, so it is naturally differentiated, though the 'state-machine status' framing is jargon-heavy rather than plainly self-explanatory.

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 implies when to use which mode — pass a state for one jurisdiction, omit it for the full matrix — but never states purpose-driven conditions or exclusions (e.g. when to prefer this over get_bill_record for coverage questions). Usage is inferable rather than explicit.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered and the bar for added context is lower. The description usefully discloses the payload shape (member-level yes/no/other/absent records) and that bill_id returns all recorded votes, but says nothing about ordering, pagination, or behavior when neither id is supplied.

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, and the resource scope is front-loaded before the parameter routing. 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 partially compensates by characterizing the returned records at member level. Annotations cover the safety profile, so the only real omission is the no-argument/both-argument default behavior for a tool where zero parameters are 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 description coverage is 0% and both parameters are optional with no descriptions, so the description carries the full burden. It does define both: vote_event_id selects a single vote event, bill_id returns all recorded votes for a bill. It does not state what happens if both are omitted or supplied together, which is the remaining gap.

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 vote event(s)') and immediately narrows the payload to 'member-level (yes/no/other/absent) vote records'. No sibling tool covers vote events, so the agent can distinguish this from get_bill_record or trace_legislative_history 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?

'Provide vote_event_id for one vote, or bill_id for all recorded votes on that bill' gives clear invocation modes, but this is really parameter routing rather than when-to-use guidance. It names no alternative tool, no exclusion condition, and no case where a different sibling (e.g. get_bill_record) would be preferred.

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 readOnly/idempotent/non-destructive, so the bar is lower, but the description still adds real value: it discloses the return shape at a semantic level (title/subject membership rules tuned for precision over recall, live bill_count, how_to_fetch_bills) and the key limitation that no bill rows come back. It does not discuss pagination or rate limits, keeping it just short of 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 the verb and resource, and each sentence carries distinct information (scope, examples, semantics of a topic, what it does not return, what to pair it with). The long parenthetical example list is slightly costly but serves discovery, so it is efficient overall rather than padded.

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 carries the burden of describing returns, and it does so (title/subject membership rules, bill_count, how_to_fetch_bills) while also signposting the follow-up path to bills. For a zero-argument, read-only listing tool this is 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?

The tool takes zero parameters, so the baseline is 4. Nothing in the description needs to compensate for parameter documentation, and the empty schema is consistent with a no-argument 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+resource ('List Bill Commons' curated cross-state topic trackers') and enumerates concrete examples of the topics. It also explicitly distinguishes itself from bill-returning tools, so an agent can tell it apart from search_legislation or get_bill_record 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 frames the tool as the entry point for 'what subjects does Bill Commons track across all 50 states + DC' and 'how do I get every bill in one', and names the alternatives ('pair it with search_legislation or the REST API's /topics/{slug}'). Both the when and the when-not (it does not return bill rows) are stated.

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 the safe read-only/idempotent profile, and the description adds genuine behavior: websearch_to_tsquery syntax, a fuzzy pg_trgm title-similarity fallback when exact matching yields nothing, and a bill-number fast path attempted first. It stops short of describing result shape or what limit does when omitted.

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 paragraphs: capabilities and the routing rule. The distinguishing claim ('FULL BILL TEXT -- not just known-bill-number lookup') is front-loaded, and every sentence carries selection-relevant information despite the dense technical detail.

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 five-parameter search tool with no output schema and no annotation detail on returns, the description covers matching semantics, fallback behavior, and the primary alternative well. The only real gap is the undocumented limit/result-count behavior and no hint at what a result row contains.

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 0%, so the description must compensate, and it does for q (phrase/OR/-exclusion syntax, three bill-number formats) plus jurisdiction (two-letter state code or name), chamber, and status. The limit parameter is never explained, leaving one of five parameters undocumented.

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 bill-text search) and immediately scopes it against the sibling it is not: known-bill-number lookup (get_bill_record). It also enumerates the searched fields (titles, descriptions, ingested document text), so an agent can distinguish it from every sibling 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 routes the agent: use this for ad-hoc keyword search, but call list_topics first for a curated cross-state subject slice, with the reason given (subject tags this search can't see). It also states that a bill-number query is accepted and tried on a fast path, so the agent needn't avoid this tool for lookups.

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, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful context about what is returned (a merged timeline), but says nothing about pagination, auth needs, or output size for a potentially large chronological record.

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 that packs the resource, scope, and returned contents with zero filler. Every phrase earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only, single-parameter retrieval tool with annotations covering safety and no output schema, the description is largely sufficient because it enumerates the returned timeline components. Minor gaps remain around bill_id format and whether long histories are paginated.

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 0% for the single required bill_id parameter, so the schema provides no semantics. The description also never mentions bill_id or its expected format (e.g., jurisdiction-prefixed identifier), leaving format inference to the agent from a self-descriptive name 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 states a specific resource (a bill's legislative history) and enumerates the merged contents: actions, version publications, votes, and related-bill links. It is clearly distinguishable from siblings like compare_bill_versions and get_bill_record, though it does not explicitly name those alternatives.

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?

Usage is implied by the content scope - an agent can infer this is for retrieving a bill's full timeline - but there is no explicit when-to-use guidance, no mention of when to prefer compare_bill_versions or get_bill_record, and no stated prerequisites.

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