Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@civic-awareness-mcp Show me recent bills on healthcare in Congress"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Two MCP servers for US civic data — one for Congress + federal campaign finance, one for 50-state legislatures.
Server | Source | Jurisdictions | Package |
| Congress.gov + OpenFEC | US federal |
|
| OpenStates | 50 states + DC |
|
Each server reads/writes-through to a local SQLite store as a TTL cache. Every response includes a sources: { name, url }[] array for provenance. No tool synthesizes summaries — that is the LLM's job.
Related MCP server: LegiScan MCP Server
Tool | Kind | What it answers |
| feed | Bills introduced or acted on in the last N days (Congress.gov) |
| feed | Roll-call votes in the last N days, yea/nay/present tallies |
| feed | Federal campaign contributions in a date window (OpenFEC) |
| search | Title search across cached federal bills, votes, contributions |
| entity | Name search across Members of Congress + FEC candidates/committees |
| entity | Entity detail + role history + recent documents |
| entity | Disambiguate a name into one or more Person entity IDs |
| entity | Co-occurrence graph via bills, votes, contributions (depth 1–2) |
| detail | Full roll-call vote with per-legislator positions |
Tool | Kind | What it answers |
| feed | Bills by jurisdiction; filters for sponsor, subject, classification, session, dates |
| feed | Roll-call votes in the last N days, chamber + tally (OpenStates, per jurisdiction) |
| detail | Full bill detail: actions, versions, sponsors, subjects |
| search | Title search across cached state bills |
| entity | Name search across state legislators (OpenStates) |
| entity | Entity detail + role history + recent documents |
| entity | Disambiguate a name into one or more Person entity IDs |
| entity | Co-occurrence graph via shared sponsored bills (depth 1–2) |
Node.js ≥ 22
API keys: api.data.gov (covers Congress.gov + OpenFEC), OpenStates — all free tier
npm install
npm run build
# federal server
npm run bootstrap:federal
npm run start:federal
# state server
npm run bootstrap:state
npm run start:stateFor development (no build step):
npm run dev:federal
npm run dev:stateThe server fetches data automatically on cache miss. For bulk pre-population:
# federal
npm run refresh:federal -- --source=congress --max-pages=1
npm run refresh:federal -- --source=openfec --max-pages=1
# state (one jurisdiction)
npm run refresh:state -- --source=openstates --jurisdictions=tx --max-pages=1To prune stale fetch-log rows (recommended monthly):
npm run evict-fetch-lognpm test # mocked unit + integration suite (MSW)
npm run test:watch # rerun on change
npm run test:drift # live-API drift tests (requires .env.local)
npm run typecheck # tsc --noEmit
npm run lint # eslint
npm run format # prettier --writeTo run both servers locally, add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"civic-federal-mcp": {
"command": "node",
"args": ["/absolute/path/to/civic-awareness-mcp/dist/federal/index.js"],
"env": {
"API_DATA_GOV_KEY": "your-key",
"CIVIC_FEDERAL_DB_PATH": "/absolute/path/to/federal.db"
}
},
"civic-state-mcp": {
"command": "node",
"args": ["/absolute/path/to/civic-awareness-mcp/dist/state/index.js"],
"env": {
"OPENSTATES_API_KEY": "your-key",
"CIVIC_STATE_DB_PATH": "/absolute/path/to/state.db"
}
}
}
}Variable | Server | Description |
| federal | api.data.gov key (Congress.gov + OpenFEC) |
| state | OpenStates v3 API key |
| federal | SQLite path (default |
| state | SQLite path (default |
| both | Optional daily API spend cap (unused by default) |
| both |
|
Four workflows in .github/workflows/:
ci.yml — format, lint, typecheck, tests, build, MCP stdio smoke. Matrix on Node 22/24. Runs on push to main and on every PR.
codeql.yml — CodeQL static analysis. Runs on push/PR/weekly.
scorecard.yml — OpenSSF Scorecard. Runs on push/weekly.
nightly-drift.yml — live-API shape checks against OpenStates, Congress.gov, OpenFEC. Runs daily at 09:00 UTC and on-demand via workflow_dispatch.
The drift workflow requires repo secrets OPENSTATES_API_KEY and API_DATA_GOV_KEY (separate from user keys — those are configured locally via .env.local).
See SECURITY.md. Highlights:
Never writes to upstream APIs
All sources are sanctioned free-tier APIs with documented rate limits
Rate-limited fetch with per-host token bucket; Retry-After honoured
Zod-validated inputs; parameterized SQLite queries
No contributor PII in responses
MIT — see LICENSE.
Given an entity ID, return co-occurrence edges to other entities via shared state bills. Supports depth=1 (direct) or depth=2 (through one hop). Edges are capped at 100 and sorted by co_occurrence_count descending.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| depth | No | ||
| min_co_occurrences | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full behavioral burden. It honestly discloses that the tool returns edges capped at 100, sorted by co_occurrence_count, and supports depth 1 or 2. However, it does not state that the operation is read-only, mention any authentication needs, or describe behavior when no edges exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at three sentences, front-loaded with the core purpose. Every sentence adds essential information: what it does, depth options, and output constraints. 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?
Given 3 parameters, no output schema, and no annotations, the description covers key aspects but leaves gaps. It explains the output behavior (edges capped and sorted) but does not describe the response structure or fields. The 'min_co_occurrences' parameter is entirely omitted. Completeness is adequate but not thorough.
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 0% parameter descriptions, so the description must compensate. It explains the depth parameter and the edge cap/sorting, adding meaning beyond the schema's constraints. However, it fails to describe the 'id' parameter beyond 'entity ID' and does not mention the 'min_co_occurrences' parameter at all.
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's purpose: returning co-occurrence edges to other entities via shared state bills, given an entity ID. It specifies depth options (direct or one hop) and output constraints (capped at 100, sorted by count). This distinguishes it from siblings like get_entity (which retrieves a single entity) and search_entities (which searches).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when an entity ID is available and edges are needed, but it lacks explicit guidance on when to use this tool versus alternatives like get_entity or search_entities. It does not mention prerequisites, limitations, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch full detail for a single state bill including actions, versions, sponsors, and subjects. Requires jurisdiction, session, and identifier.
| Name | Required | Description | Default |
|---|---|---|---|
| session | Yes | ||
| identifier | Yes | ||
| jurisdiction | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the operation fetches details (read) and lists included fields. However, it does not disclose limitations, error handling, or any side effects. For a read-only tool, this is adequate but not thorough.
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 sentence that efficiently conveys the core purpose and requirements. It is front-loaded with the action. It could be structured with bullet points for clarity, but it is already 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?
For a tool with 3 required parameters and no output schema, the description provides the essential context (what it does and what it returns). However, it lacks details on parameter formats, output structure, and error behavior, leaving some uncertainty.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It names the three required parameters but does not explain their meaning (e.g., jurisdiction format, session format, identifier format). The additional value over the schema is minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch full detail'), the resource ('a single state bill'), and the included fields ('actions, versions, sponsors, subjects'). It distinguishes from siblings like 'recent_bills' (list vs detail) and 'search_entities' (search vs fetch specific).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly requires 'jurisdiction, session, and identifier', indicating the parameters needed. It implies usage when needing detailed information on a specific bill, but does not explicitly state when not to use it or mention alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single entity by ID with recent related documents. For state Persons, returns the cross-jurisdiction roles[] history.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must convey behavior. It mentions returning recent related documents and a special case for state Persons, but omits disclosures about authentication, error handling, or read-only nature. Basic but not comprehensive.
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 concise sentences with no filler. The main action is front-loaded, and the special case is appended efficiently. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple parameter set (single required string ID) and no output schema, the description covers the core functionality and a notable variant. Missing details on return format or error conditions, but adequate for a straightforward fetch.
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 no descriptions (0% coverage), but the description explains that the 'id' parameter is the entity identifier. This adds meaningful context beyond the schema's raw type definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Fetch', the resource 'a single entity', the method 'by ID', and includes specialized behavior for state Persons. It distinguishes well from siblings like get_bill or search_entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when an entity ID is known but does not explicitly state when to use this tool versus alternatives (e.g., get_bill, resolve_person). No when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List U.S. state legislative bills from OpenStates. Defaults to the last days (default 7) of recently-updated bills. Optional filters: chamber, session, sponsor_entity_id (civic entity UUID, resolved to OpenStates OCD id), classification, subject, introduced_since/until, updated_since/until, sort. Any explicit date range overrides days. Pass a jurisdiction like 'us-tx' or 'us-ca'; '*' queries all cached jurisdictions locally. Useful for 'what did this legislator introduce' and 'recent bills on ' queries.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Look-back window in days. Ignored when any explicit introduced_since/until or updated_since/until is set. | |
| sort | No | updated_desc | |
| limit | No | Optional row cap. Without explicit date filters, caps recency-sorted rows from a 365-day lookback. | |
| chamber | No | ||
| session | No | ||
| subject | No | ||
| jurisdiction | Yes | Jurisdiction like 'us-tx' or 'us-ca'. '*' queries all cached jurisdictions locally (no upstream fetch). | |
| updated_since | No | ||
| updated_until | No | ||
| classification | No | ||
| introduced_since | No | ||
| introduced_until | No | ||
| sponsor_entity_id | No | Civic entity UUID; resolved to OpenStates OCD person id before upstream fetch. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses defaults, override behavior, and the wildcard jurisdiction for local caching. However, it does not state that the operation is read-only, mention rate limits or authentication needs, or describe any side effects. This is adequate but leaves gaps.
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 efficient and front-loaded, starting with the core purpose. It packs multiple pieces of information into a single paragraph without fluff. Could be slightly more structured (e.g., use bullet points for filters), but it is concise and readable.
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 no output schema and 13 parameters (31% coverage), the description provides good context for core functionality and use cases. However, it omits details about return format, pagination, error cases, and does not fully compensate for the low parameter coverage. It is functional but not fully complete for complex queries.
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 31%, so the description must compensate. It lists many optional filters (chamber, session, subject, etc.) and explains `sponsor_entity_id` resolution and jurisdiction wildcard. However, it does not add detailed semantics for all 13 parameters (e.g., classification, `limit` behavior could be clearer). The description adds some value beyond the schema but is not comprehensive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'U.S. state legislative bills from OpenStates', with details on defaults and optional filters. It distinguishes from siblings like get_bill (single bill) and recent_votes (votes) by focusing on recent bills, but does not explicitly contrast with all siblings.
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 the default `days` parameter, how explicit date ranges override it, and mentions specific use cases like 'what did this legislator introduce'. It lacks explicit guidance on when not to use this tool versus alternatives, but the context is sufficient for an agent to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recent roll-call votes from state legislatures via OpenStates. Pass a jurisdiction like 'us-tx' or 'us-ca'. Votes are sourced from recently-updated bills with embedded vote data. Use '*' to query all cached jurisdictions locally.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | ||
| limit | No | ||
| chamber | No | ||
| session | No | ||
| jurisdiction | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that votes are from recently-updated bills with embedded vote data and mentions local caching. However, no annotations are provided, and the description does not cover rate limits, authentication, or potential side effects.
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 short sentences that are front-loaded with the main purpose, no redundant or extraneous content.
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 5 parameters and no output schema or annotations, the description lacks details on optional parameters, return format, and pagination. It only covers jurisdiction usage, leaving significant gaps for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description explains the jurisdiction parameter with examples but provides no information about the other four parameters (days, limit, chamber, session), leaving the agent to infer their meaning from the 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 lists recent roll-call votes, specifies the data source (OpenStates), and gives jurisdiction examples. It is distinct from sibling tools like 'recent_bills'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides examples of jurisdiction input and mentions the wildcard '*' for all cached jurisdictions, but does not explicitly state when not to use this tool or suggest alternatives for other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Disambiguate a person by name across state legislators. Returns all matching Person entities with confidence tiers. Supply jurisdiction_hint to trigger upstream OpenStates hydration.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| context | No | ||
| role_hint | No | ||
| jurisdiction_hint | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It mentions confidence tiers and hydration but omits details on side effects, error states, permissions, or what happens with no matches. The behavior is only partially transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy. The first sentence states the core purpose, the second adds a key behavioral hint. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters and no output schema, the description is incomplete. It lacks parameter docs for context and role_hint, does not describe the return format beyond confidence tiers, and omits error handling. More detail is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description should explain all parameters. It only describes name (implicitly) and jurisdiction_hint, leaving context and role_hint unexplained. This is insufficient for the 4-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'disambiguate' and the resource 'person by name across state legislators', distinguishing it from sibling tools like get_entity or search_entities. It also specifies return of matching Person entities with confidence tiers.
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 a usage hint about jurisdiction_hint triggering upstream hydration but does not explicitly say when to use this tool over alternatives or when not to use it. No comparison to sibling tools is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search state civic documents (bills) by title. Optionally filter by jurisdiction, kind, source, or date range.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | ||
| to | No | ||
| from | No | ||
| kinds | No | ||
| limit | No | ||
| sources | No | ||
| jurisdiction | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description must disclose behavior. It only states basic operation and optional filters, omitting details like pagination (limit param), result format, error handling, or rate limits. Fails to provide expected behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 13 words, no redundancy. Front-loaded action and then optional filters. Very concise, though could benefit from listing filters if more detail needed. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters, 100% undocumented in schema, and no output schema, the description is too minimal. It doesn't explain what the search returns, how results are ordered, or timeouts. A search tool requires more context for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description maps 'date range' to from/to and lists filters (jurisdiction, kind, source), adding some meaning. But with 0% schema coverage, it should explain each parameter's valid values or constraints (e.g., no enums for jurisdiction/kinds/sources). Incomplete but partially helpful.
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 it searches state civic documents (bills) by title, differentiating from siblings like get_bill (retrieves single bill) and recent_bills (lists recent). The verb 'search' and resource 'civic documents/bills' are specific.
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?
Mentions optional filters (jurisdiction, kind, source, date range), giving context on when to apply them. Lacks explicit when-not or alternatives like 'use get_bill for a specific bill ID', but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for people or organizations by name across state legislatures (OpenStates). Pass a jurisdiction to trigger upstream hydration.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | ||
| kind | No | ||
| limit | No | ||
| had_role | No | ||
| jurisdiction | No | ||
| had_jurisdiction | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only mentions that passing jurisdiction triggers upstream hydration, but lacks details on read-only nature, result format, pagination, or error handling. This is insufficient for a search tool with 6 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at two sentences, with no filler. The first sentence clearly states the purpose, and the second adds a critical behavioral note. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 6 parameters and no output schema or annotations, the description is incomplete. It covers only purpose and one parameter behavior, missing key aspects like pagination, default behavior without jurisdiction, and return type. Sibling tools do not compensate for this lack.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only hints at the meaning of 'q' (search by name) and 'jurisdiction' (triggers hydration), ignoring 'kind', 'limit', 'had_role', and 'had_jurisdiction'. This leaves 4 out of 6 parameters unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for 'people or organizations by name across state legislatures', specifying the verb, resource, and context. It also distinguishes from sibling tools like get_bill or recent_bills which focus on bills, and the mention of OpenStates provides domain clarity.
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 that the tool is for searching entities by name, and hints at using 'jurisdiction' to trigger hydration, but does not explicitly state when not to use it or list alternatives. Sibling tools are available externally but not mentioned in the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.0entity_connectionsget_billget_entityrecent_billsrecent_votesresolve_personsearch_civic_documentssearch_entitiesScored across 8 tools
Most tools have distinct purposes (bill detail, entity lookup, recent bills, votes, search, connections). However, search_civic_documents and recent_bills both retrieve bills, though via different access patterns (search vs. listing), causing minor overlap.
All tool names follow a consistent verb_noun pattern using snake_case (e.g., get_bill, search_entities, recent_votes). No naming style conflicts.
8 tools cover the domain of state legislative data without being too few or excessive. Each tool serves a clear function in the workflow.
Core operations for browsing state bills, entities, votes, and connections are present. Missing features like jurisdiction listing or bill text retrieval are minor gaps that don't break typical workflows.
U.S. federal policy data — bills, Congress members, voting records, and civic info.
Access U.S. congressional data - bills, votes, members, committees - via MCP.
Search bills and speaker-attributed hearing transcripts across all 50 US state legislatures.
U.S. civic data for AI agents: reps, votes, bills, finance, lobbying, cited gov sources. 47 tools.
