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.7/5 across 10 of 10 tools scored.
Each tool targets a distinct entity or operation (bill, committee, event, jurisdiction, legislators by location, jurisdictions list, and search endpoints for bills, committees, events, people). No two tools have overlapping purposes; even get_legislators_by_location is unique from search_people by using geographic coordinates.
All tools follow the 'openstates_verb_noun' pattern with snake_case (get_bill, search_bills, list_jurisdictions, etc.). The verb choices (get, search, list) are consistently applied to their respective operations, providing a predictable and logical structure.
With 10 tools, the server is well-scoped for interacting with state legislative data. It covers both retrieval of specific entities (bills, committees, events, jurisdictions, people) and search functionality. The count is appropriate without being overwhelming or too sparse.
The tool set covers the core CRUD-like operations for bills (get, search), committees (get, search), events (get, search), people (get by location, search), and jurisdictions (get, list). Missing are update/delete operations, but those are not typical for a read-only API. The include parameters allow fetching related details, reducing gaps. Minor gap: no direct vote retrieval tool, but votes can be embedded via include=votes.
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 (e.g., "2025-01-01"). | |
| 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 (e.g., "2025-01-01"). | |
| 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. |
| appliedFilters | Yes | Filters applied to this query as the server received them, for agent self-verification of zero or unexpected results. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark as readOnly/idempotent. Description adds search-specific behaviors: pagination parameters, sorting impacts, and that combining jurisdiction and q narrows results. Explains how include options affect data retrieval without separate calls.
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?
Five efficient sentences front-load purpose, then key features, then usage requirements and tips. No redundant information; each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complexity (14 params, output schema exists), description covers major usage patterns, required parameters, and cross-references sibling tool. Could mention pagination limits explicitly, but overall sufficient 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?
Input schema covers all 14 parameters with descriptions (100% coverage). Description adds value by clarifying required combination (jurisdiction or q), recommending include options, and explaining sort order effects. Provides extra usage context 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 it searches state legislative bills across all US jurisdictions, listing specific features like full-text, jurisdiction/session filtering, and sponsor lookups. It distinguishes from sibling tools like openstates_get_bill by being a 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: requires either jurisdiction or q, combining narrows results, includes tip on using include=sponsorships,actions to avoid separate get_bill call, and refers to openstates_get_jurisdiction for session identifiers.
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. |
| appliedFilters | Yes | Filters applied to this query as the server received them, for agent self-verification of zero or unexpected results. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description supplements the existing annotations (readOnlyHint, idempotentHint, openWorldHint) by disclosing that the feature is experimental, not all states have data, and the coverage_note field will indicate limitations. This adds important behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences long, front-loaded with the main purpose, then an important caveat, followed by parameter hints, and finally an output note. No wasteful 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's complexity (7 parameters, output schema exists), the description covers the overall purpose, experimental status, and key parameter usage. Pagination and return format are handled by the schema. The description feels complete for an agent to use 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?
The input schema has 100% description coverage, but the description adds practical guidance: 'Use chamber to scope to upper (senate) or lower (house) committees,' 'Use classification=subcommittee,' and 'Use include=memberships.' This enhances the schema descriptions with concrete usage examples.
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 starts with 'List committees for a jurisdiction,' providing a clear verb and resource. It distinguishes itself from sibling tools like openstates_get_committee and openstates_search_bills by specifying committees.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to list committees) and provides usage tips for optional parameters like chamber, classification, and include. It also notes the experimental nature and data limitations, but does not explicitly state when not to use it or contrast with alternatives.
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. |
| appliedFilters | Yes | Filters applied to this query as the server received them, for agent self-verification of zero or unexpected results. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds valuable context about experimental status, data scarcity, and interpretation of empty results, going 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 and well-structured: opens with clear action, then key usage tips in logical order. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, output schema, and annotations, the description covers all essential behavioral and contextual aspects, including experimental nature and data limitations, making it complete for 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%, so baseline is 3. Description adds meaningful context for after/before (date range scoping), require_bills (most useful filter), and include (full meeting context), justifying 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 explicitly states it searches hearings, floor sessions, and committee meetings, clearly distinguishing it from sibling tools like openstates_get_event (single event retrieval) and other search 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?
Provides explicit guidance on using after/before for date ranges, require_bills for tracking legislation, and include for full context. Warns about experimental nature and empty results, helping the agent decide when to use it.
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. |
| appliedFilters | Yes | Filters applied to this query as the server received them, for agent self-verification of zero or unexpected results. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable behavioral details: case-insensitive substring matching, the effect of omitting jurisdiction (large result set), and what include options add (phone, fax, address, etc.). 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 three sentences: purpose, key features, and a warning. Every sentence conveys essential information without redundancy. It is front-loaded and efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters, no required parameters, and an output schema, the description covers all critical aspects: filtering, include options, and an important warning. The presence of an output schema reduces the need to explain return values. The description is sufficiently complete for an agent to select and 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?
Schema coverage is 100% (all parameters have descriptions). The description enhances understanding by explaining enum values (e.g., 'upper' for Senate) and clarifying include sub-options ('offices adds phone, fax, and address'). It adds meaning beyond the raw 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 opens with a specific verb ('Search') and clearly identifies the resource ('state legislators and officials'). It lists multiple filtering dimensions (name, jurisdiction, chamber, district, party), making the tool's scope unambiguous and distinct from sibling tools like search_bills or search_committees.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to use key features: name substring matching, org_classification values, include options, and the warning about large result sets when jurisdiction is omitted. It does not explicitly state when not to use this tool or name alternatives, but the sibling list provides implicit context.
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!