openstates-mcp-server
Server Details
Search bills, legislators, committees, and events across all 50 US states, DC, and Puerto Rico.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
- Repository
- cyanheads/openstates-mcp-server
- GitHub Stars
- 1
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.6/5 across 10 of 10 tools scored.
Each tool targets a distinct entity or action (bill, committee, event, jurisdiction, legislators by location, jurisdictions list, and searches for bills, committees, events, people) with no overlapping purposes.
All tool names follow a consistent 'openstates_verb_noun' pattern (e.g., openstates_get_bill, openstates_search_people), using only 'get', 'list', and 'search' as verbs.
With 10 tools, the server is well-scoped for a legislative data API, covering retrieval and search of key entities without being overly sparse or bloated.
The server covers main entities (bills, committees, events, jurisdictions, people) with both get and search operations. Minor gaps include lack of a direct get_legislator by ID, but overall coverage is solid for a read-only API.
Available Tools
10 toolsopenstates_get_billGet BillARead-onlyIdempotentInspect
Fetch full detail for a specific state bill. Accepts either the three-part path (jurisdiction + session + bill_id) or a direct OCD bill ID (openstates_id from search results). Use include to request votes, actions, sponsorships, documents, and versions in one call rather than searching again. include=votes returns the full vote tally and per-legislator positions. include=actions returns the complete action history. Prefer openstates_id when available to avoid session identifier lookup.
| Name | Required | Description | Default |
|---|---|---|---|
| bill_id | No | Bill identifier as used by the legislature (e.g., "HB 1000", "SB 42"). Required with jurisdiction + session. | |
| include | No | Related data to inline. "sponsorships", "actions", "votes" are most commonly needed. "versions" and "documents" provide links to bill text and fiscal notes. | |
| session | No | Session identifier. Required with jurisdiction + bill_id. | |
| jurisdiction | No | State name, abbreviation, or OCD-ID. Required when using path-based lookup with session + bill_id. | |
| openstates_id | No | OCD bill ID from openstates_search_bills results (e.g., "ocd-bill/..."). Preferred over the three-part path when available. |
Output Schema
| Name | Required | Description |
|---|---|---|
| id | Yes | OCD bill ID. |
| title | Yes | Bill title. |
| votes | No | Vote events when include=votes is requested. |
| actions | No | Full action history when include=actions is requested. |
| session | Yes | Legislative session identifier. |
| subject | Yes | Subject tags. |
| versions | No | Bill text versions when include=versions is requested. |
| abstracts | No | Bill abstracts when include=abstracts is requested. |
| documents | No | Bill documents (fiscal notes, etc.) when include=documents is requested. |
| identifier | Yes | Bill identifier as used by the legislature. |
| jurisdiction | Yes | Originating jurisdiction. |
| sponsorships | No | Sponsorships when include=sponsorships is requested. |
| related_bills | No | Related bills when include=related_bills is requested. |
| classification | Yes | Bill classifications. |
| openstates_url | No | Open States URL for this bill. |
| first_action_date | Yes | Date of first recorded action. |
| from_organization | Yes | Originating chamber. |
| latest_action_date | Yes | Date of most recent action. |
| latest_passage_date | Yes | Date bill passed (when applicable). |
| latest_action_description | Yes | Most recent action description. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnly, openWorld, idempotent), the description explains the behavior of 'include' options, e.g., 'include=votes returns the full vote tally and per-legislator positions', adding valuable behavioral 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 description is five sentences long, front-loads the main purpose, and every sentence contributes new, useful information without 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?
The description covers both lookup methods, explains the 'include' parameter's effects, and is consistent with the presence of an output schema (not shown). No additional information is needed for an agent to use 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?
With 100% schema coverage, the description adds significant value: it gives examples for 'bill_id', clarifies acceptable inputs for 'jurisdiction', explains the format for 'openstates_id', and highlights the most commonly needed 'include' values.
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 detail for a specific state bill and distinguishes between two lookup methods: path-based and OCD ID. This contrasts it with sibling search/get tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises preferring 'openstates_id' when available to avoid session lookup, and suggests using 'include' to fetch related data in one call. It does not explicitly state when not to use this tool, but provides clear guidance on best practices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openstates_get_committeeGet CommitteeARead-onlyIdempotentInspect
Fetch committee detail by OCD organization ID. Returns name, classification, and membership roster when include=memberships is requested. Experimental — not all states have committee data in Open States. Obtain the committee_id from openstates_search_committees.
| Name | Required | Description | Default |
|---|---|---|---|
| include | No | Related data to inline. "memberships" includes the full roster with member roles. | |
| committee_id | Yes | OCD organization ID (from openstates_search_committees results). |
Output Schema
| Name | Required | Description |
|---|---|---|
| id | Yes | OCD organization ID. |
| name | Yes | Committee name. |
| parent_id | Yes | OCD ID of parent committee, or null for top-level committees. |
| memberships | No | Membership roster when include=memberships is requested. |
| classification | Yes | Committee classification: "committee" or "subcommittee". |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, open-world, and idempotent. Description adds 'Experimental — not all states have committee data', which is valuable beyond annotations. No contradictions.
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 essential information, front-loaded. No unnecessary words.
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 output schema present, description need not detail returns. Covers purpose, parameter usage, and experimental caveat thoroughly. Complete for the tool's complexity.
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?
Input schema has 100% description coverage. Description adds meaning by explaining that 'memberships' includes full roster with member roles and clarifies where committee_id comes from.
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 the verb 'fetch', resource 'committee detail', and key parameter 'OCD organization ID'. Distinguishes from sibling tool 'openstates_search_committees' by specifying how to obtain the committee_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?
Explicitly states to get committee_id from openstates_search_committees, and mentions the include parameter for membership roster. Does not explicitly state when not to use, but context is clear for a single-committee fetch.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openstates_get_eventGet EventARead-onlyIdempotentInspect
Fetch full event detail by OCD event ID. Returns agenda, participants, media links, and associated documents when requested via include. Experimental — event coverage is limited in Open States. Obtain the event_id from openstates_search_events.
| Name | Required | Description | Default |
|---|---|---|---|
| include | No | Related data to inline. "agenda" and "participants" are most useful. | |
| event_id | Yes | OCD event ID (from openstates_search_events results). |
Output Schema
| Name | Required | Description |
|---|---|---|
| id | Yes | OCD event ID. |
| name | Yes | Event name. |
| links | No | Event links when include=links is requested. |
| media | No | Media links when include=media is requested. |
| agenda | No | Agenda items when include=agenda is requested. |
| status | Yes | Event status. |
| end_date | No | Event end datetime. Absent when not recorded. |
| location | No | Event location when available. |
| documents | No | Document links when include=documents is requested. |
| start_date | Yes | Event start datetime. |
| description | Yes | Event description. |
| jurisdiction | Yes | Hosting jurisdiction. |
| participants | No | Participants when include=participants is requested. |
| classification | Yes | Event classification. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint, openWorldHint, idempotentHint) are matched; description adds experimental limitation and include behavior. 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?
Three concise sentences, no fluff, front-loaded with purpose. Every sentence adds essential 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 output schema exists and parameters are well-documented, description covers all needed context: purpose, usage hint, experimental note.
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%; description adds value by highlighting most useful include values and instructing on event_id source.
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 verb 'Fetch full event detail', specific resource 'event by OCD event ID', and lists what is returned. Distinguishes from sibling search tool.
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 guidance to obtain event_id from openstates_search_events and notes experimental status. Lacks alternative exclusions but sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openstates_get_jurisdictionGet JurisdictionARead-onlyIdempotentInspect
Fetch full metadata for a specific jurisdiction including all legislative sessions, their identifiers, and coverage dates. Use when you need to know the exact session identifier for a state before filtering bill searches — session formats vary widely (e.g., "2025", "2025rs", "2025s1"). Jurisdiction IDs follow OCD format: ocd-jurisdiction/country:us/state:{abbr}/government (e.g., ocd-jurisdiction/country:us/state:wa/government). State names (e.g., "Washington") and two-letter abbreviations (e.g., "wa") are also accepted.
| Name | Required | Description | Default |
|---|---|---|---|
| include | No | Related data to inline. "legislative_sessions" returns all historical and current sessions with identifiers and date ranges. "latest_runs" shows last scraper run metadata. | |
| jurisdiction_id | Yes | OCD jurisdiction ID, state name (e.g., "Washington"), or two-letter abbreviation (e.g., "wa"). |
Output Schema
| Name | Required | Description |
|---|---|---|
| id | Yes | OCD jurisdiction ID. |
| url | Yes | Official legislature URL. |
| name | Yes | Jurisdiction name. |
| classification | Yes | Jurisdiction type. |
| latest_bill_update | Yes | ISO 8601 timestamp of most recent bill data update. |
| latest_people_update | Yes | ISO 8601 timestamp of most recent people data update. |
| legislative_sessions | No | All legislative sessions when include=legislative_sessions is requested. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, open-world. The description adds value by specifying the returned metadata (sessions, identifiers, dates). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no waste. It front-loads the purpose and efficiently adds usage guidance and 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 output schema exists and annotations are comprehensive, the description covers all key aspects. It could mention error handling or rate limits but is sufficient for this simple 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%, but the description significantly enhances understanding: clarifies jurisdiction_id formats (OCD, state name, abbreviation) and explains the include options in more detail than the schema 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 it fetches full metadata for a specific jurisdiction, including legislative sessions. It distinguishes from sibling tools like openstates_list_jurisdictions (which lists all) and other get tools for different entities.
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 guidance: use when needing exact session identifiers before bill searches. It implies alternatives (e.g., list_jurisdictions for listing) but does not explicitly mention when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openstates_get_legislators_by_locationGet Legislators by LocationARead-onlyIdempotentInspect
Find all state legislators representing a geographic coordinate. Pass latitude and longitude to get state senators and representatives (and potentially governor/executive officials) for that location. Useful for constituent-to-representative matching, address-based policy research, and electoral boundary analysis. This server does not geocode addresses — the caller must provide decimal-degree coordinates. Use include=offices to get contact information alongside the legislator list.
| Name | Required | Description | Default |
|---|---|---|---|
| include | No | Related data to inline. "offices" includes phone, fax, and address. | |
| latitude | Yes | Latitude in decimal degrees (e.g., 47.6062 for Seattle, WA). | |
| longitude | Yes | Longitude in decimal degrees (e.g., -122.3321 for Seattle, WA). |
Output Schema
| Name | Required | Description |
|---|---|---|
| count | Yes | Number of legislators returned. |
| legislators | Yes | Legislators representing the given coordinate. |
| coverage_note | No | Present when no legislators were found — explains why (e.g., location outside US boundaries or unsupported territory). |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations by specifying that results include state senators, representatives, and potentially governor/executive officials. It also notes that 'include=offices' returns contact info. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and the description aligns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, with the main purpose in the first sentence. Every sentence adds value: purpose, usage scenarios, geocoding limitation, and parameter hint. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters and an output schema, the description covers purpose, input requirements, usage scenarios, and a key constraint. It also mentions the types of officials returned, which is helpful for an agent. Complete enough for effective selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description adds value by clarifying that latitude/longitude must be decimal degrees with examples, and explains the effect of the 'include' parameter for offices. This extra guidance justifies a 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?
The description clearly states the verb 'Find' and resource 'state legislators representing a geographic coordinate'. It distinguishes from siblings which are about bills, committees, events, and searches, making it obvious when to use this tool.
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 use cases like constituent matching and policy research, and notes the critical limitation that the server does not geocode. It does not explicitly exclude alternatives, but the sibling tools are clearly different, so the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openstates_list_jurisdictionsList JurisdictionsARead-onlyIdempotentInspect
List all jurisdictions covered by Open States — all 50 states, DC, and Puerto Rico. Returns coverage metadata: latest bill update time, latest people update time, and optionally all legislative sessions with their identifiers. Use this when you need to discover valid session identifiers for a state before calling openstates_search_bills with a session filter. The legislative_sessions include option returns all historical and current sessions — always check valid session identifiers here before using them in bill searches, since formats vary widely by state (e.g., "2025", "2025-2026", "2025rs", "2025s1").
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-indexed). | |
| include | No | Related data to inline. "legislative_sessions" returns all session identifiers and date ranges — required when you need to discover valid session values for bill searches. | |
| per_page | No | Results per page. Default 52 to cover all states, DC, and Puerto Rico in one request. | |
| classification | No | Filter by jurisdiction type. Use "state" (default) for all 50 states, DC, and Puerto Rico. | state |
Output Schema
| Name | Required | Description |
|---|---|---|
| results | Yes | Jurisdictions matching the filter. |
| pagination | Yes | Pagination metadata. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, indicating safe, non-destructive behavior. The description adds value by detailing what metadata is returned (latest update times, optionally all legislative sessions), which is beyond what annotations provide.
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 relatively concise, with two main sentences and a parenthetical note about session formats. It is front-loaded with the core purpose. A slightly more structured breakdown could improve scanability, but it earns its place without wasted words.
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 a modest complexity (4 parameters, no nested objects) and an output schema exists, the description is complete. It covers when to use the tool, what each parameter does, and hints at the output. No gaps remain for effective agent use.
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: for 'include' it explains that 'legislative_sessions' returns all session identifiers and date ranges required for bill searches. For 'per_page', it clarifies the default covers all jurisdictions in one request. For 'classification', it explains the default filters to states and territories.
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 and return coverage metadata. It distinguishes from sibling tools like openstates_search_bills by explicitly noting its use for discovering valid session identifiers before bill searches.
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 this when you need to discover valid session identifiers for a state before calling openstates_search_bills with a session filter.' It explains why this is necessary (formats vary by state) and what the legislative_sessions option does.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openstates_search_billsSearch BillsARead-onlyIdempotentInspect
Search state legislative bills across all covered US jurisdictions. Supports full-text search, jurisdiction/session filtering, subject tags, sponsor lookups, and sort order. Either jurisdiction or q (full-text) is required — combining both narrows results. include=sponsorships,actions returns sponsor and action history inline. sort=latest_action_desc surfaces bills currently moving. openstates_get_jurisdiction with include=legislative_sessions returns valid session identifiers for session filtering.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Full-text search across bill titles, abstracts, and text. Required unless jurisdiction is provided. Combining with jurisdiction is recommended for precision. | |
| page | No | Page number (1-indexed). | |
| sort | No | Sort order. Use "latest_action_desc" for bills currently moving through the legislature. | updated_desc |
| chamber | No | Filter by originating chamber. "upper" = Senate, "lower" = House/Assembly. | |
| include | No | Related data to inline. "sponsorships" and "actions" cover most research needs without a separate openstates_get_bill call. "votes" adds full vote tallies and per-legislator positions. | |
| session | No | Session identifier (e.g., "2025", "2025-2026", "2025rs"). Use openstates_get_jurisdiction with include=legislative_sessions to discover valid values. Omit to search across all sessions. | |
| sponsor | No | Filter by sponsor name or OCD person ID. | |
| subject | No | Filter to bills tagged with one or more subject categories. | |
| per_page | No | Results per page. Maximum 20. Default 10. | |
| action_since | No | ISO 8601 date — only return bills with an action after this date. | |
| jurisdiction | No | State name, two-letter abbreviation, or OCD-ID (e.g., "Washington", "wa", or "ocd-jurisdiction/country:us/state:wa/government"). Required unless q is provided. | |
| updated_since | No | ISO 8601 date — only return bills updated after this date. | |
| classification | No | Bill classification: "bill", "resolution", "constitutional amendment", etc. | |
| sponsor_classification | No | Filter sponsor type: "primary", "cosponsor". |
Output Schema
| Name | Required | Description |
|---|---|---|
| message | No | Recovery hint when results are empty — echoes the filters applied and suggests how to broaden. Absent when results are returned. |
| results | Yes | Bills matching the search criteria. |
| pagination | Yes | Pagination metadata. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, openWorldHint, idempotentHint. The description adds behavioral nuances such as the effect of include parameters on performance and result richness, and the need for combining jurisdiction and q for precision. No contradiction with 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 concise, front-loaded with the core purpose, and every sentence adds value. It avoids redundancy and packs significant useful information into a single paragraph.
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 14 parameters, full schema coverage, annotations, and an output schema, the description covers all essential aspects: when to use, how to filter, performance tips, and cross-references to related tools. It is complete for effective use.
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?
Despite 100% schema coverage (baseline 3), the description adds valuable context: required combinations for q/jurisdiction, practical use of include, and a method to discover valid session values. This goes beyond the schema definitions.
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 'Search state legislative bills' and lists specific capabilities (full-text search, filtering, etc.). It distinguishes from sibling tools like openstates_get_bill by focusing on search and listing functions.
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 required parameters ('Either jurisdiction or q is required'), practical combinations ('combining both narrows results'), and tips like using sort=latest_action_desc for active bills. It references another tool for session discovery, but does not fully exclude when to avoid this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openstates_search_committeesSearch CommitteesARead-onlyIdempotentInspect
List committees for a jurisdiction. Experimental — Open States is actively working to restore committee support and not all states have data. Use chamber to scope to upper (senate) or lower (house) committees. Use classification=subcommittee to find subcommittees of a parent. Use include=memberships to get the full roster with member roles. The coverage_note field in the output will always note the experimental coverage limitations.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-indexed). | |
| parent | No | OCD organization ID of a parent committee to retrieve its subcommittees. | |
| chamber | No | Filter by chamber. "upper" = Senate, "lower" = House/Assembly. | |
| include | No | Related data to inline. "memberships" includes the full roster with member roles. | |
| per_page | No | Results per page. Maximum 20. | |
| jurisdiction | No | State name, abbreviation, or OCD-ID. Omitting searches across all states. | |
| classification | No | Filter to parent committees or subcommittees only. Omit for all. |
Output Schema
| Name | Required | Description |
|---|---|---|
| results | Yes | Committees matching the search criteria. |
| pagination | Yes | Pagination metadata. |
| coverage_note | Yes | Committee data is experimental — not all states have coverage in Open States. Empty results may indicate the state lacks data, not that no committees exist. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, idempotentHint, openWorldHint), the description adds that the tool is experimental, may not have all states' data, and that the coverage_note field will indicate limitations. This provides useful behavioral context 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 concise with five sentences, each adding unique information. It front-loads the core purpose, then provides usage tips and experimental notes without redundancy. No unnecessary words.
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 list tool with 7 parameters and an output schema, the description covers the main functionality and experimental status. It briefly mentions pagination indirectly via the 'page' parameter in schema, but does not explain the per_page limit or that omitting jurisdiction searches all states. These are minor gaps given the schema's clarity.
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?
While the schema has 100% coverage, the description adds value by explaining the purpose of specific parameters like chamber, classification, and include in plain language, and how they affect results. It could be more detailed for jurisdiction (optional vs. required), but overall supplements the schema well.
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 committees for a jurisdiction, using specific verbs and resource. It distinguishes itself from sibling tools like openstates_get_committee which retrieves a single committee, and other search tools that handle different entities.
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 using chamber, classification, and include parameters to filter results. It also notes the experimental nature and coverage limitations. However, it does not explicitly contrast with openstates_get_committee or other sibling tools for when to use this search vs. a direct lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openstates_search_eventsSearch EventsARead-onlyIdempotentInspect
Search hearings, floor sessions, and committee meetings. Experimental — most states do not publish event data to Open States. Use after and before to scope to a date range. Set require_bills=true to filter to events with bills on the agenda, which is the most useful filter for tracking legislation through committee. Use include=agenda,participants for full meeting context. Empty results often indicate the state lacks event data rather than no events occurring.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-indexed). | |
| after | No | ISO 8601 datetime — events starting after this time. Use to find upcoming hearings. | |
| before | No | ISO 8601 datetime — events starting before this time. | |
| include | No | Related data to inline. "agenda" includes the meeting agenda with bill references. "participants" includes the committee or chamber hosting the event. | |
| per_page | No | Results per page. Maximum 20. | |
| jurisdiction | No | State name, abbreviation, or OCD-ID. Omitting searches across all states. | |
| require_bills | No | When true, only return events with at least one bill on the agenda. Most useful for tracking legislation through committee. |
Output Schema
| Name | Required | Description |
|---|---|---|
| message | No | Recovery hint when results are empty. Absent when results are returned. |
| results | Yes | Events matching the search criteria. |
| pagination | Yes | Pagination metadata. |
| coverage_note | Yes | Event data is experimental — most states do not publish event data to Open States. Empty results may indicate the state lacks data, not that no events occurred. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds value by stating the tool is experimental and that most states do not publish event data, helping interpret empty results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at 5 sentences with front-loaded key info. Each sentence adds value, though it could be slightly more compact for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 7 optional params and an output schema, the description covers usage patterns, data limitations, and result interpretation. No gaps for an agent to misuse.
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 good descriptions for each parameter. The description reinforces key params (after, before, require_bills, include) but adds no new details beyond what the schema already provides.
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 'Search hearings, floor sessions, and committee meetings' with a specific verb and resource. It distinguishes from sibling search tools like openstates_search_bills by targeting events.
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 guidance: use after/before for date range, set require_bills=true for tracking legislation, include=agenda,participants for full context. Also explains empty results often indicate missing state data rather than no events.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openstates_search_peopleSearch PeopleARead-onlyIdempotentInspect
Search state legislators and officials by name, jurisdiction, chamber, district, or party. Supports name substring matching (case-insensitive). org_classification targets a specific chamber: "upper" for Senate, "lower" for House/Assembly, "legislature" for all legislators, "executive" for governors and executive officials. include=offices adds phone, fax, and address. include=links adds website and social links. Omitting jurisdiction searches across all states and may return a large result set.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Name or partial name to match (case-insensitive substring). | |
| page | No | Page number (1-indexed). | |
| include | No | Related data to inline. "offices" includes phone, fax, and address. "links" includes website and social links. | |
| district | No | District label (e.g., "1", "37", "At-Large"). Formats vary by state. | |
| per_page | No | Results per page. Maximum 20. | |
| jurisdiction | No | State name, abbreviation, or OCD-ID. Omitting searches across all states. | |
| org_classification | No | Filter by role type. "upper" = Senate, "lower" = House/Assembly, "legislature" = all legislators, "executive" = governors and executive officials. |
Output Schema
| Name | Required | Description |
|---|---|---|
| message | No | Recovery hint when results are empty. Absent when results are returned. |
| results | Yes | Legislators matching the search criteria. |
| pagination | Yes | Pagination metadata. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds behavior beyond annotations: substring matching, case-insensitivity, page limits (max 20), include subfields, large result warning. Annotations already declare readOnly/open/Idempotent; description complements without 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?
Concise single paragraph (4 sentences) front-loading purpose. Could benefit from bullet structure for parameter explanations, but remains efficient and scannable.
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 exists, description adequately covers all key aspects: search criteria, filtering, includes, pagination, jurisdiction scope. Sufficient for an agent to invoke 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?
With 100% schema coverage, description adds critical meaning: explains org_classification values in plain language ('upper'=Senate), include subfields ('offices' adds phone/fax/address), and jurisdiction formats. Significantly enhances 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 verbs 'Search' and specifies the resource 'state legislators and officials'. It distinguishes from sibling search tools (bills, committees, events) that target different entities.
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 context for when to use (name matching, org_classification values, include options, jurisdiction scope) but does not explicitly state when to avoid or use alternatives, though sibling tools imply differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!