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 for this coordinate. |
| notice | No | Present when no legislators were found — explains why (e.g., location outside US boundaries or unsupported territory). |
| legislators | Yes | Legislators representing the given coordinate. |
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 that results include state senators, representatives, and possibly executive officials, and that it returns a list. No contradictions. The description adds useful context 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?
The description is concise and well-structured: first sentence states purpose, second gives details, third notes limitation, fourth provides usage tip. Every sentence adds value 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?
Given the tool has 3 parameters, an output schema, and annotations already covering safety/invariants, the description is complete. It explains what the tool returns, how to use parameters, and key limitations, enabling correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for each parameter. The description adds value by providing example coordinates (Seattle, WA) and explaining the 'offices' value in the include array. This enhances understanding beyond schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds state legislators for a given geographic coordinate, using specific verbs ('find', 'representing') and resource ('legislators'). It distinguishes from siblings by focusing on location-based query, which is unique among the listed 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 provides clear context for when to use (constituent matching, policy research, electoral analysis) and what not to expect (no geocoding). It also mentions the include=offices option. However, it does not explicitly contrast with alternative tools, though sibling tools are distinct enough.
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 |
|---|---|---|
| page | Yes | Current page returned. |
| maxPage | Yes | Total pages available. |
| results | Yes | Jurisdictions matching the filter. |
| pagination | Yes | Pagination metadata. |
| totalCount | Yes | Total jurisdictions matching the filter across all pages. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, openWorld, idempotent. Description adds behavioral details: returns latest update times, optionally all legislative sessions, and warns about varying session identifier formats. 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?
Description is informative but slightly wordy, with multiple sentences. However, it is well-structured with a clear order: purpose, usage, parameter guidance. Could be slightly more concise, but still effective.
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, the description adequately covers purpose, usage, parameters, and critical advice about session identifiers. No gaps for a listing tool with rich annotations and schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions. Description adds context: per_page default 52 covers all, includes option legislative_sessions returns all identifiers and is required for session discovery, and warns about format variation. Adds significant explanatory value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all jurisdictions covered by Open States (50 states, DC, Puerto Rico) and returns coverage metadata, optionally legislative sessions. It distinguishes from siblings by emphasizing its role in discovering session identifiers for 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?
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 advises to always check identifiers here due to varying formats.
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 |
|---|---|---|
| page | Yes | Current page returned. |
| notice | No | Recovery hint when results are empty — echoes the filters applied and suggests how to broaden. Absent when results are returned. |
| maxPage | Yes | Total pages available. |
| results | Yes | Bills matching the search criteria. |
| pagination | Yes | Pagination metadata. |
| totalCount | Yes | Total bills matching the query across all pages. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. The description adds behavioral context like full-text search scope, filter combinations, and inline includes, without contradicting annotations. No hidden traits disclosed, but sufficient given strong 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?
Description is a single well-structured paragraph, front-loaded with purpose, followed by key features and constraints. Every sentence adds value; no redundancy or fluff. Ideal length for a complex search tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 14 parameters with 100% schema coverage, strong annotations, and an output schema, the description provides all necessary context: required parameters, common filter combinations, performance tips, and cross-references. It covers the tool's role within the API comprehensively.
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%, yet the description adds significant value beyond parameter descriptions: explains how combining q and jurisdiction narrows results, recommends specific include values (sponsorships, actions) to avoid extra calls, and clarifies sort order semantics. This provides practical guidance.
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 searches state legislative bills across all covered US jurisdictions, listing specific filtering options (full-text, jurisdiction, session, subject, sponsor, sort). It distinguishes from sibling tools by targeting bills specifically, not committees, events, or people.
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 explains required parameters ('Either jurisdiction or q is required') and suggests use cases like 'sort=latest_action_desc surfaces bills currently moving.' It cross-references openstates_get_jurisdiction for session identifiers, but does not explicitly state when to prefer alternatives like openstates_get_bill.
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 |
|---|---|---|
| page | Yes | Current page returned. |
| maxPage | Yes | Total pages available. |
| results | Yes | Committees matching the search criteria. |
| pagination | Yes | Pagination metadata. |
| totalCount | Yes | Total committees matching the query across all pages. |
| coverageNote | 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?
Annotations already indicate readOnly, openWorld, idempotent. Description adds experimental status, coverage limitations, and the coverage_note field, offering useful context 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?
Concise single paragraph of 4 sentences, front-loaded with purpose, and every sentence adds value 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?
Given 7 parameters, 0 required, and output schema existence, the description covers experimental context, key filter usage, and output field. Could mention pagination but schema already handles page/per_page.
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 usage tips (e.g., 'Use chamber to scope...') that enhance understanding beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists committees for a jurisdiction using a specific verb ('List committees') and resource ('jurisdiction'). It distinguishes from siblings like openstates_get_committee by being a search tool, and the experimental note sets it apart.
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 usage guidance for chamber, classification, and include parameters, and notes experimental limitations. However, it does not explicitly mention when not to use or suggest alternative tools for specific cases.
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 |
|---|---|---|
| page | Yes | Current page returned. |
| notice | No | Recovery hint when results are empty. Absent when results are returned. |
| maxPage | Yes | Total pages available. |
| results | Yes | Events matching the search criteria. |
| pagination | Yes | Pagination metadata. |
| totalCount | Yes | Total events matching the query across all pages. |
| coverageNote | 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?
The description notes the tool is 'Experimental' and warns that 'most states do not publish event data,' with empty results often indicating lack of data rather than no events. This adds important behavioral context beyond the readOnlyHint and idempotentHint 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 of four sentences, efficiently covering purpose and usage tips with no fluff. It could be slightly more structured with bullet points, but it is appropriately concise.
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 7 optional parameters and the presence of an output schema, the description covers the main use cases and data limitations. It provides rationale for parameter usage and sets expectations about data availability, though it does not detail pagination or result formats (handled by schema).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though schema coverage is 100%, the description adds value by explaining the utility of key parameters: using 'after' and 'before' for date scoping, 'require_bills=true' for filtering, and 'include=agenda,participants' for context. These explanations go beyond 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 explicitly states it searches 'hearings, floor sessions, and committee meetings,' which are clear types of events. This distinguishes it from sibling search tools that search bills, committees, or people.
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 recommends using date range parameters ('after' and 'before') and highlights the 'require_bills=true' filter for tracking legislation. It also advises using 'include=agenda,participants' for full context. However, it does not explicitly compare to alternatives like search_bills.
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 |
|---|---|---|
| page | Yes | Current page returned. |
| notice | No | Recovery hint when results are empty. Absent when results are returned. |
| maxPage | Yes | Total pages available. |
| results | Yes | Legislators matching the search criteria. |
| pagination | Yes | Pagination metadata. |
| totalCount | Yes | Total legislators matching the query across all pages. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, openWorld, and idempotent. The description adds behavioral context: case-insensitive substring matching, the effect of include parameters, and the scope of jurisdiction omission. 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 a single paragraph that front-loads the purpose and then elaborates on parameters. All sentences add value; no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters (mostly optional) and an output schema present, the description covers key behaviors and parameter usage. The warning about large results when omitting jurisdiction is helpful. It is complete enough 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?
Schema description coverage is 100%, so baseline is 3. The description adds meaning: explains org_classification values and include options more concretely than the schema alone, improving agent understanding.
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 legislators and officials' with specific parameters (name, jurisdiction, chamber, district, party), making the verb and resource explicit. It distinguishes from sibling tools like openstates_search_bills which search 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?
It explains key usage details: substring matching (case-insensitive), org_classification mappings, include options, and warns that omitting jurisdiction may return large results. While it doesn't explicitly exclude alternatives, the sibling tools serve different purposes, so guidance is adequate.
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!