openstates-mcp-server

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

Annotations already indicate readOnlyHint, openWorldHint, and idempotentHint, so the tool is known to be safe and idempotent. The description adds valuable detail on the behavior of include parameters, e.g., 'include=votes returns the full vote tally and per-legislator positions', which goes beyond annotations. No contradiction.

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

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

The description is concise, front-loaded with the main purpose, and every sentence provides necessary information. There is no redundancy or filler, and the structure flows logically from purpose to usage to parameter details.

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

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

Given the presence of an output schema and comprehensive annotations, the description covers all needed contextual aspects: input methods, parameter usage, include options, and preference for openstates_id. No gaps remain for an agent to select and invoke the 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%, but the description adds meaning beyond schema: it explains the purpose of openstates_id vs path parameters, and details what each include value returns (e.g., 'versions' and 'documents' provide links). This adds significant value for selecting and invoking the tool.

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

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

The description clearly states the verb 'Fetch full detail' for a 'specific state bill', and distinguishes the tool from sibling search tools by focusing on bill detail retrieval. It explicitly mentions two input methods and the include parameter for related 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?

The description provides clear guidance on when to use openstates_id over the three-part path ('Prefer openstates_id when available to avoid session identifier lookup') and advises using include to avoid multiple searches. It lacks explicit when-not scenarios, but the context is clear for the intended use.

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 indicate read-only, open-world, and idempotent behavior. Description adds context about experimental status and incomplete state coverage, which is useful for setting expectations.

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 well-structured sentences, each serving a distinct purpose: core action, optional parameters, experimental warning, prerequisite. No redundant 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?

Output schema exists, annotations cover safety/idempotency. Description adds prerequisites and limitations. Adequate for a simple read tool; no need for error details.

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% (baseline 3). Description adds meaning beyond schema by explaining committee_id source and detailing what each include option returns (roster, links, sources).

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

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

Clearly states 'Fetch committee detail by OCD organization ID' and specifies return fields (name, classification, membership roster). Distinguishes from sibling 'openstates_search_committees' which returns search results.

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 instruction to obtain committee_id from openstates_search_committees. Also notes experimental nature and data availability limitations across states. Lacks explicit when-not-to-use but sufficient for 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?

Adds critical behavioral context beyond annotations: experimental status, limited coverage, and details on what each include option returns. Annotations already mark readOnly, openWorld, and idempotent, so no contradiction.

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 no filler: first states purpose and return types, second gives data source and experimental warning. Every word adds 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 full schema coverage, annotations, and output schema, the description still adds essential context (experimental, limited coverage, data source). No gaps remain for an agent to misuse the tool.

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

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

Schema covers 100% of parameters with descriptions. The description enhances meaning by noting the source for event_id and clarifying which include values are most useful (agenda, participants).

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

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

Description clearly states the action ('fetch full event detail'), resource ('event'), and identifier mechanism ('OCD event ID'). It distinguishes from sibling tools by referencing openstates_search_events as the source for the event_id.

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

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

Provides explicit requirement to obtain event_id from openstates_search_events and mentions experimental nature with limited coverage, helping the agent set expectations. Lacks explicit when-not-to-use but is still 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 confirm readOnlyHint, openWorldHint, idempotentHint. The description adds value by explaining supported input formats (OCD ID, state name, abbreviation) and the include parameter behavior, which is not in annotations.

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

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

Three sentences, front-loaded with purpose, no redundancy. Every sentence adds essential information, making it efficient and easy to parse.

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

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

For a tool with 2 parameters and an output schema, the description is complete. It covers what metadata is returned, input flexibility, and usage context without needing to explain return values.

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% with descriptions for both parameters. The description goes beyond by explaining jurisdiction_id accepts multiple formats and detailing include options, adding practical context.

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

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

The description clearly states the tool fetches full metadata for a specific jurisdiction, including legislative sessions, identifiers, and coverage dates. It distinguishes from sibling tools like openstates_list_jurisdictions by focusing on a single jurisdiction and providing specific use cases.

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

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

The description explicitly tells when to use this tool: when needing exact session identifiers before filtering bill searches, noting format variability. It implies not to use for listing jurisdictions (sibling), but lacks explicit exclusions or alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds context by stating the tool does not geocode and explaining the effect of the include parameter, which adds value beyond annotations.

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 concise sentences, each serving a purpose: purpose, use cases, limitation, and tip. No redundancy, well front-loaded.

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

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

Given the tool has an output schema, the description adequately covers input requirements and return types. It lacks mention of pagination or errors, but for a read-only, idempotent tool with good annotations, it is sufficiently 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 baseline is 3. The description adds extra meaning by explaining the include parameter's effect ('get contact information') and highlighting required coordinates format, which enhances the schema's 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 clearly states the action ('Find all state legislators representing a geographic coordinate'), specifies the resource ('legislators by location'), and lists the types of officials returned. This distinguishes it from sibling tools like search_people or get_bill.

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

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

Provides explicit use cases (constituent matching, policy research, boundary analysis) and a key limitation (no geocoding, caller provides coordinates). It does not explicitly state when to avoid using this tool, but sibling names imply alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint. Description adds that results come in a single default call via server-side merge, and explains behavior of the include parameter (returns sessions, organizations, runs). No contradictions, but could note rate limits or data freshness boundaries.

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?

Single focused paragraph, front-loaded with core purpose, then usage guidance and parameter details. Every sentence adds value, no repetition or fluff.

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

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

Given output schema present, 100% schema coverage, and annotations, the description is fully complete: covers all behaviors, use cases, and parameter nuances for this list 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 description adds significant semantic value: explains per_page default merging logic, include options with use cases, classification filter purpose, and page numbering. Consistently better than schema descriptions 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 clearly states the tool lists all jurisdictions covered by Open States, enumerates them explicitly (50 states, DC, 5 territories), and distinguishes from siblings like openstates_get_jurisdiction by emphasizing bulk listing and session discovery.

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 provides when-to-use guidance: 'Use this when you need to discover valid session identifiers for a state before calling openstates_search_bills with a session filter.' Also explains the include option for legislative sessions, giving actionable 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, openWorldHint, and idempotentHint. The description adds context that it is a search tool, that results can be paginated, and that inline data can be requested. It does not contradict any annotations. It does not detail the output format, but an output schema is present (not shown). Overall, the description adds useful behavioral context beyond the annotations.

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

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

The description is a single paragraph that combines multiple pieces of information. While it is relatively concise (about 100 words), it lacks visual structure (e.g., bullet points). Every sentence adds value, but the density could be improved for quick scanning. It is adequate but not exemplary.

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 complexity (15 parameters, many filtering options), the description covers the main use cases: required parameters, common includes, sort order for active bills, and discovery of session identifiers. It does not cover every edge case but is sufficient for an agent to use the tool effectively. An output schema exists, so return value details are not 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 100%, so the baseline is 3. The description adds value by explaining the interplay between parameters (e.g., 'Either jurisdiction or q is required — combining both narrows results') and giving usage tips for include and sort. It does not repeat schema info but enhances understanding, thus scoring above 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?

The description clearly states it searches state legislative bills across all covered US jurisdictions. It lists supported features (full-text, jurisdiction/session filtering, subject tags, sponsor lookups, sort order) and distinguishes itself from siblings like openstates_get_bill and openstates_search_committees. The verb 'search' combined with the resource 'bills' and scope 'all covered US jurisdictions' provides a specific purpose.

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

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

The description provides clear usage guidance: either jurisdiction or q is required, combining both narrows results. It recommends using include=sponsorships,actions to avoid extra calls, and sort=latest_action_desc to find moving bills. It points to openstates_get_jurisdiction for session identifiers. However, it does not explicitly state when not to use this tool (e.g., for a single bill, use openstates_get_bill), though that is implied.

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, openWorldHint, and idempotentHint. The description adds valuable behavioral context: the tool is experimental, state data coverage varies, and the coverageNote field will indicate limitations. This goes beyond annotations without contradicting them.

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

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

The description is concise: three sentences plus a note. The main purpose is front-loaded. Each sentence is informative and none are redundant. 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 7 parameters all fully described in the schema and an output schema existent, the description completes the picture by explaining parameter combinations and the experimental coverage. It covers the key behavioral notes needed for correct usage.

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 use cases (e.g., 'Use chamber to scope to upper/senate or lower/house committees', 'Use classification=subcommittee to find subcommittees'). It clarifies that omitting jurisdiction returns no committees, which is crucial semantics beyond the schema.

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

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

The description clearly states 'List committees for a jurisdiction', which is a specific verb and resource. It distinguishes from sibling tools (e.g., search_bills, get_committee) by focusing on listing committees. The experimental note adds context without muddying the purpose.

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

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

The description provides explicit guidance on when to use parameters like chamber, classification, and include. It advises supplying a jurisdiction to get results, which is a key constraint. However, it does not explicitly mention when not to use this tool vs alternatives, but given sibling tools cover different resources, this is acceptable.

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, openWorldHint, idempotentHint. The description adds valuable context: experimental state, most states lack event data, and the meaning of empty results. It also explains the behavioral effects of `require_bills` and `include` parameters.

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

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

Every sentence adds value, with no fluff. The description is front-loaded with the core purpose and then provides targeted guidance. It is appropriately sized for the tool's complexity.

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, 100% schema coverage, output schema exists, and annotations are present, the description covers all key aspects: experimental limitations, date scoping, useful filters, required jurisdiction, and the meaning of empty results. It is fully complete for the tool's 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%, but the description adds significant meaning: it explains the purpose of `after`/`before` for date scoping, the utility of `require_bills` for tracking legislation, the implications of each `include` value, and the essential nature of `jurisdiction` despite not being in the required array.

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

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

The description clearly states it searches 'hearings, floor sessions, and committee meetings', using the verb 'Search' with a specific resource. It distinguishes from siblings like `openstates_get_event` (which gets a single event) and `openstates_search_bills` (bills).

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

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

The description provides explicit guidance: use `after` and `before` for date ranges, `require_bills=true` for tracking legislation, and `include=agenda,participants` for full context. It also warns about experimental nature and empty results meaning lack of data. It lacks explicit when-not-to-use versus alternatives but is still strong.

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 indicate safe read-only behavior. The description adds valuable details: substring matching, case-insensitivity, precise behavior of org_classification values, and include options, all without contradicting annotations.

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 slightly long but front-loaded with purpose. Every sentence adds necessary detail; no redundancy.

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

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

With 7 parameters and high complexity, the description covers all behavioral aspects. Output schema exists, so return values are not needed. Complete enough for correct agent invocation.

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

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

Schema coverage is 100% but description adds meaning beyond the schema: explains that omitting org_classification is not equivalent to 'legislature', warns about jurisdiction omission, and clarifies include sub-options.

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

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

The description clearly states it searches state legislators and officials by name, jurisdiction, chamber, district, or party. This distinguishes it from sibling tools like search_bills or search_committees.

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 guidance on using filters like org_classification and include, and warns about large results when omitting jurisdiction. However, it does not explicitly state when to avoid using this tool.

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