The LegiScan MCP Server provides structured access to the LegiScan API for legislative data from all 50 US states and Congress through 10 optimized MCP tools.
Core Capabilities:
Legislative Search: Full-text search across bills with relevance scoring, pagination, and state/year/session filtering
Bill Information: Retrieve comprehensive bill data including sponsors, history, votes, texts, amendments, and supplements
Bill Lookup: Find bills by number with automatic format normalization (AB 858, AB858, AB-858)
Vote Tracking: Access roll call vote details with individual legislator positions (Yea/Nay/NV/Absent)
Legislator Search: Find legislators by name (partial matching supported) to get their unique people_id
Legislator Details: Get information including party, role, district, and third-party IDs (VoteSmart, OpenSecrets, Ballotpedia, FollowTheMoney)
Voting Records: Retrieve how a legislator voted across multiple bills in a single optimized call
Primary Authorship: Filter bills where a legislator is the primary author, excluding co-sponsored bills
Session Participants: List all active legislators in a legislative session
Session Management: Browse available legislative sessions by state
Key Advantages:
API Efficiency: Composite tools batch multiple API calls for 90%+ reduction in API usage (e.g., 1 call instead of ~80 for votes)
Input Validation: Automatic state code validation and bill number normalization
Research Workflows: Optimized for opposition research, bill tracking, and scorecard generation
Integration: Compatible with MCP-capable agents like Claude Desktop, Codex CLI, and Claude Code
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., "@LegiScan MCP Server find recent climate change bills in California"
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.
A Model Context Protocol (MCP) server that gives terminal agents structured access to the LegiScan API for legislative data from all 50 US states and Congress.
Built for research workflows where you direct an agent (Codex, Claude Code, Claude Desktop, etc.) to gather bill history, sponsor context, and voting records quickly.
10 Streamlined MCP Tools optimized for legislative research workflows
Composite tools that collapse multi-step research workflows into single MCP tool calls
Per-request batching and lookup caching for repeated bill and roll-call lookups
Full TypeScript type definitions for all API responses
Bill number normalization (handles AB 858, AB858, AB-858 formats)
Input validation guardrails for state codes, legislator name queries, and large bill batches
Related MCP server: Gavelin
npm install -g legiscan-mcp-servergit clone https://github.com/sh-patterson/legiscan-mcp.git
cd legiscan-mcp
npm install
npm run buildCreate a free account at LegiScan
Register for API access at https://legiscan.com/legiscan
Copy your API key
Add this server to whatever MCP host your terminal agent uses.
Claude Desktop config paths:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
For other MCP clients (Codex CLI, Claude Code, etc.), add the same mcpServers.legiscan entry in that client's MCP config file.
{
"mcpServers": {
"legiscan": {
"command": "npx",
"args": ["-y", "legiscan-mcp-server"],
"env": {
"LEGISCAN_API_KEY": "your_api_key_here"
}
}
}
}{
"mcpServers": {
"legiscan": {
"command": "node",
"args": ["/path/to/legiscan-mcp-server/dist/index.js"],
"env": {
"LEGISCAN_API_KEY": "your_api_key_here"
}
}
}
}Tool | Description |
| Find a legislator's people_id by name. Supports partial matching. |
| Get how a legislator voted on multiple bills in one call. |
| Get only bills where legislator is primary author (not co-sponsor). |
Tool | Description |
| Get detailed bill info (sponsors, history, votes, texts) |
| Find bill by number (handles AB 858, AB858, AB-858, A.B. 858). Best for exact bill lookup. |
| Get vote details with individual legislator votes |
Tool | Description |
| Get legislator info with third-party IDs (VoteSmart, OpenSecrets, etc.) |
| Get all legislators active in a session |
Tool | Description |
| Full-text search across legislation. Accepts bill-number variants like AB858, but use |
Tool | Description |
| List available legislative sessions by state |
Give your agent a goal, state, timeframe, and output format.
Example prompt:
Use the LegiScan MCP tools to find major California housing bills in the current session.
Return: bill number, title, latest action date, top sponsors, and whether there was a close roll-call vote (margin <= 5).For high-quality results, tell the agent to do this order:
legiscan_get_session_list to identify the correct session.
legiscan_search or legiscan_find_bill_by_number to locate target bills.
legiscan_get_bill for sponsor/history/vote references.
legiscan_get_roll_call for individual vote details.
legiscan_get_person only when legislator enrichment is needed.
If you start with legiscan_find_legislator, keep passing the returned session.session_id or the same state into follow-up authoring workflows so results stay in the intended legislature and timeframe.
These cut tool-call volume and simplify instructions to your agent:
legiscan_find_legislator: get people_id from a name query.
legiscan_get_primary_authored: separate primary-authored from co-sponsored bills.
legiscan_get_legislator_votes: pull vote positions across many bills in one request.
Use LegiScan MCP for Texas.
1) Find legislator "Jane Smith".
2) List all primary-authored bills in the current session.
3) For these bills, summarize topic area and latest status.
4) Then check votes on SB 12, HB 301, and SB 455, and show how the legislator voted.Use LegiScan MCP to track "climate resilience" bills in New York.
Focus on current session only.
Return top 15 bills by relevance with bill number, title, last action, sponsor party, and any recorded roll calls.For California session 2172, resolve bill numbers AB 858, SB 525, SB 616, SB 399.
For each bill, fetch details and any roll calls.
Then report vote positions for people_id values 21719, 23214, and 25359.
Output as a table suitable for CSV export.The composite tools dramatically reduce agent-to-tool round trips for common workflows:
Workflow | Manual MCP Steps | With Composites |
Get votes for 1 legislator on 10 bills | Find legislator → search/resolve bills → inspect each bill → inspect each roll call | 1 tool call once you have |
Filter primary authored from 150 sponsored bills | Sponsored list → fetch each bill → inspect sponsors | 1 tool call, optionally scoped by |
Find legislator by name | Session discovery → session people lookup → manual matching | 1 tool call |
State codes are validated as two-letter strings and uppercased automatically (ca → CA). Invalid codes like ZZ pass local validation but return an API error from LegiScan.
Always pin state and session in your prompt to reduce ambiguous results.
Ask the agent to show bill_id, roll_call_id, and people_id in intermediate output so you can audit traceability.
For legislator search, provide at least a first and last name (name input must be at least 2 characters).
legiscan_get_primary_authored can return all available sessions, but passing state or session_id keeps results aligned to the intended legislature and timeframe.
legiscan_get_legislator_votes accepts up to 100 bill_ids per request; split larger jobs into chunks.
legiscan_search retries compact bill-number queries like AB858 using a canonical spaced format. For exact bill resolution, prefer legiscan_find_bill_by_number.
Ask for final outputs in a table/CSV-ready shape if you plan downstream analysis.
npm run build # Compile TypeScript
npm run typecheck # Type-check src + tests
npm test # Run deterministic unit tests (no API key)
npm run test:e2e # Run real-world workflow tests (skips cleanly without API key)
npm run test:live # Run live API integration tests (requires API key)
npm run test:coverage # Run unit tests with coverage
npm run lint # Check for lint errors
npm run format # Format code with Prettiernpm test / npm run test:unit: Fast deterministic tests with mocked network calls.
npm run test:e2e: Research workflow tests based on real legislative analysis tasks. Skips if LEGISCAN_API_KEY is unavailable.
npm run test:live: Real LegiScan API integration tests. Requires LEGISCAN_API_KEY.
Free public API keys have a 30,000 queries per month limit
Composite tools batch requests (10 concurrent max) and cache repeated lookups inside a single request to avoid unnecessary duplication
Composite tools reduce MCP workflow friction, but LegiScan API usage still scales with the number of distinct bills and roll calls you inspect
Build the container image locally:
docker build -t legiscan-mcp .Run it with your API key provided at runtime:
docker run --rm -i \
-e LEGISCAN_API_KEY=your-api-key-here \
legiscan-mcpGlama checks expect a GitHub release. After merging your next repo changes, create and publish a tag such as v1.0.0 from GitHub or with:
git tag v1.0.0
git push origin v1.0.0MIT - see LICENSE for details.
Find a bill by its number within a state's current session or specific session. Handles format variations (AB 858, AB858, AB-858). Returns bill summary if found, null if not.
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | Two-letter state abbreviation (e.g., CA, TX). Uses current session. | |
| session_id | No | Session ID for searching a specific session. Takes precedence over state. | |
| bill_number | Yes | Bill number in any common format (e.g., 'AB 858', 'AB858', 'AB-858', 'SB 1234') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry behavioral info. It states return behavior (bill summary or null) and format handling, but does not explicitly declare read-only nature or discuss side effects, permissions, or rate limits.
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 redundant information. Efficiently communicates purpose, usage options, and handling behavior.
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?
Covers input variations and precedence, and mentions return type. Missing output schema, but description adequately addresses what to expect. Could mention that bill summary includes key fields, but not necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and description adds value beyond schema: examples for state (CA, TX), precedence rule for session_id, and common bill number formats (AB 858, AB858, etc.).
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 action (find), resource (bill), and context (by number within session). Distinguishes from siblings like legiscan_get_bill (which likely uses ID) and legiscan_search (general search).
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?
Explains state vs session_id options and format variations, but does not explicitly mention when to use this versus alternative tools (e.g., legiscan_get_bill) or provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find a legislator's people_id by searching their name. Useful as a first step before other queries. Supports partial name matching.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Full or partial name to search (e.g., 'Smith', 'Jane Smith') | |
| state | Yes | Two-letter state abbreviation (e.g., 'CA') | |
| session_id | No | Optional specific session_id (default: current session) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. States 'Supports partial name matching', a key behavioral trait. Lacks details on error handling, rate limits, or multiple results, but sufficient for a simple lookup.
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 brief sentences, front-loaded with the core action. 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?
No output schema, but description explicitly mentions the return value (people_id). With full parameter schema and no nested objects, the description provides enough context to understand the tool's role.
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 'partial name matching' which overlaps with schema's 'Full or partial name'. No additional detail on session_id or 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?
Clearly states the verb 'find', the resource 'legislator's people_id', and the method 'searching their name'. Distinguishes from siblings by framing it as a 'first step before other queries', implying it is a lookup 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?
Explicitly says 'Useful as a first step before other queries', providing clear context. Does not explicitly state when not to use, but the purpose is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed bill information including sponsors, full history, votes, texts, amendments, and supplements. This is the primary tool for bill research.
| Name | Required | Description | Default |
|---|---|---|---|
| bill_id | Yes | Bill ID from search results or find_bill_by_number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It describes the information returned (sponsors, history, votes, etc.), which implies a read-only operation, but it does not explicitly state idempotency, potential side effects, authentication requirements, or rate limits. The description is adequate but not fully 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?
The description is extremely concise, consisting of just two sentences. The first sentence lists the key components of the bill information, and the second sentence asserts its role as the primary research tool. Every word is purposeful, and there is no fluff or 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 simplicity of the tool (one required parameter, no output schema, no annotations), the description sufficiently covers what the tool does and what it returns. It could mention limitations like jurisdiction scope or required API key, but for a basic retrieval tool, the description provides adequate context for an AI agent to understand its purpose.
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 one parameter (bill_id) with 100% description coverage. The schema's description already explains its source ('from search results or find_bill_by_number'). The tool's description adds no additional parameter information beyond the schema, so it provides no extra value for parameter semantics.
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 specifies the verb 'Get' and the resource 'detailed bill information', listing key components like sponsors, history, votes, etc. It also explicitly identifies itself as 'the primary tool for bill research', distinguishing it from sibling tools like legiscan_search or legiscan_find_bill_by_number.
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 indicates this is the primary tool for bill research, implying its use for comprehensive data. However, it does not explicitly state when to avoid it or specify alternatives for simpler needs (e.g., legiscan_find_bill_by_number for just an ID). The guidance is clear but lacks exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get how a legislator voted on specific bills. Use find_legislator first to get people_id from a name. Returns vote positions (Yea/Nay/NV/Absent) for each bill with roll call details.
| Name | Required | Description | Default |
|---|---|---|---|
| chamber | No | Optional chamber filter (H=House, S=Senate, A=Assembly) | |
| bill_ids | Yes | Array of bill_ids to check votes on (max 100) | |
| people_id | Yes | Legislator ID (use find_legislator to resolve from name) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It states the return format (vote positions with roll call details) but does not explicitly confirm read-only behavior, permissions, or side effects. The description is adequate but minimally informative beyond the schema.
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 two sentences, front-loaded with the main action. Every sentence serves a purpose: stating the function and providing usage guidance. No extraneous text.
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, the description explains return values (vote positions). It covers the prerequisite tool and parameter roles. Missing: error conditions, edge cases (e.g., invalid bill_ids), but overall sufficient for a 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%, so baseline is 3. The description adds context for people_id (use find_legislator) but otherwise repeats schema information (chamber enum, bill_ids array). No new semantic meaning beyond structured data.
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 'Get how a legislator voted on specific bills' with a specific verb and resource. It distinguishes from siblings like get_roll_call (single roll call) and get_bill (bill details) by focusing on legislator votes. The prerequisite to use find_legislator is explicit.
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 gives explicit guidance to use find_legislator first to obtain people_id. However, it does not mention when not to use this tool or alternative tools for different scenarios (e.g., single roll call). The usage context is clear but lacks exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get legislator information including party, role, district, and third-party IDs (VoteSmart, OpenSecrets, Ballotpedia, FollowTheMoney).
| Name | Required | Description | Default |
|---|---|---|---|
| people_id | Yes | Legislator ID (use find_legislator to resolve from name) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It does not explicitly state that the operation is read-only, nor does it mention response characteristics, error conditions, or rate limits. A simple 'get' is safe, but transparency is minimal.
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?
A single sentence of 20 words efficiently conveys the tool's purpose and key return fields. No redundant information, and the most important content is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description provides a reasonable list of return fields. It does not cover error responses or rate limits, but the core functionality is adequately described.
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% and the parameter description includes a helpful hint to use find_legislator. The main description adds meaning by enumerating the data fields returned (party, role, district, IDs), which goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves legislator information and lists specific fields (party, role, district, third-party IDs). It distinguishes from siblings like legiscan_find_legislator by implying a workflow (people_id from find_legislator), though not explicitly in the main description.
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 parameter description hints that find_legislator should be used first to obtain the people_id, but there is no explicit guidance on when to use this tool versus siblings or when not to use it. Usage context is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get only bills where a legislator is the PRIMARY author, not co-sponsor. Use find_legislator first to get people_id from a name. Filters out co-sponsored bills automatically.
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | Optional state abbreviation - if provided without session_id, uses current session | |
| people_id | Yes | Legislator ID (use find_legislator to resolve from name) | |
| session_id | No | Optional session_id to filter results |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses automatic filtering of co-sponsored bills, but does not mention permissions, rate limits, or error behavior. Adequate but not rich.
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. Front-loaded with purpose, followed by usage guidance. 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?
No output schema, but tool is simple. Description covers filtering behavior and prerequisite step. Missing return value details, but acceptable for a retrieval 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% with parameter descriptions. Description adds value for people_id by explaining how to resolve it via find_legislator, beyond schema. No additional info for state or session_id, but reasonable.
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 'Get' and resource 'bills where a legislator is the PRIMARY author, not co-sponsor'. Distinguishes from co-sponsor and mentions prerequisite use of find_legislator. No ambiguity.
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 instructs to use find_legislator first to obtain people_id, providing a clear prerequisite. States that co-sponsored bills are filtered out automatically, implying when to use. Lacks explicit when-not-to-use, but context is clear given sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get roll call vote details including individual legislator votes. Get roll_call_id by calling get_bill first.
| Name | Required | Description | Default |
|---|---|---|---|
| roll_call_id | Yes | Roll call ID from get_bill response |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The verb 'Get' implies a read-only operation, and it describes the return content (roll call details, individual votes). No annotations are provided, so the description adequately covers behavior for a simple retrieval tool.
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: first for purpose, second for usage guidance. 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?
For a simple tool with one parameter and no output schema, the description provides necessary context: how to get the ID and what the response contains. It could mention error handling or rate limits, but overall sufficient.
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%, and the description repeats the same context as the schema parameter description. It adds no new semantics beyond what is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it retrieves roll call vote details including individual legislator votes. Distinguishes from sibling tools like get_bill which provides the roll_call_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 instructs to obtain roll_call_id from get_bill first, providing a clear prerequisite. Does not mention when not to use it or alternatives, but the workflow guidance is helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get list of available legislative sessions. Returns sessions with session_id, years, and state info. Use session_id for subsequent bill lookups.
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | Two-letter state abbreviation (e.g., 'CA', 'TX'). Omit to get sessions for all states. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that the tool returns a list of sessions with specific fields, implying a read-only operation. Minor omission: no explicit statement about safety or idempotency.
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, front-loaded with the main purpose, no extraneous information. 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?
For a simple list tool with one optional parameter and no output schema, the description is complete: it states what is returned and how to use the results. No additional details are necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already describes the parameter (state abbreviation, optional). The description adds no additional semantic value beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a list of legislative sessions and specifies the returned fields (session_id, years, state info). It differentiates from sibling tools which focus on bills, legislators, or roll calls.
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: use this tool to obtain session IDs for subsequent bill lookups. It implies when to use, but does not explicitly exclude cases where session IDs are already known.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all legislators active in a legislative session. Returns list of people with their roles, parties, and districts.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | Session ID (use get_session_list to find sessions for a state) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It states the return content (list with roles, parties, districts) but does not disclose if it is read-only, any rate limits, or pagination behavior. For a simple getter, this is adequate but could be improved by explicitly stating 'Read-only operation, no 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?
The description is extremely concise, consisting of two short sentences. No unnecessary words. It efficiently communicates the tool's purpose and output, earning its place without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a single parameter and no output schema, the description provides sufficient information to understand what the tool does and what it returns. It could optionally mention that the list includes identifiers (e.g., person_id) for further operations, but it is complete enough for typical 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%, with one parameter (session_id) already described in the schema. The description adds value by explaining how to obtain the session_id ('use get_session_list to find sessions for a state'), which goes beyond the schema's basic type and requirement.
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 uses a specific verb 'Get' and clearly identifies the resource as 'all legislators active in a legislative session'. It also states what is returned (list with roles, parties, districts), which distinguishes it from siblings like legiscan_get_person (single person) or legiscan_find_legislator (search by criteria).
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 you need legislators in a session but does not explicitly state when to use this tool versus alternatives (e.g., use legiscan_find_legislator if you know the legislator name). The context is clear but lacks exclusions or direct comparisons to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full-text search across bill texts. Returns 50 results per page with relevance scores, bill summaries, and URLs. Use for interactive searches.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number for pagination. Default: 1 | |
| year | No | Year filter: 1=all, 2=current (default), 3=recent, 4=prior, or exact year (>1900) | |
| query | Yes | Search query. Supports full-text search syntax. URL encode special characters. | |
| state | No | Two-letter state abbreviation or 'ALL' for nationwide search. Default: ALL | |
| session_id | No | Search within a specific session_id instead of state/year |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses key behaviors: full-text search, 50 results per page, relevance scores, summaries, and URLs. However, it does not mention rate limits, authentication, or any destructive potential, though as a search tool, destructive behavior is unlikely. The transparency is good but not exhaustive.
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 two sentences, front-loaded with purpose and key output details, then a usage hint. Every sentence provides value, with no unnecessary words. Ideal conciseness.
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 5 parameters and no output schema, the description covers the main return fields (relevance scores, bill summaries, URLs) but omits details like pagination behavior beyond '50 results per page' and specific field names. The schema explains parameters, and the description adds sufficient context for a search tool, though slightly incomplete.
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% (all parameters have descriptions), so baseline is 3. The tool description does not add new meaning to parameters beyond the schema; it only reiterates the search nature. Thus, no improvement over 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 'Full-text search across bill texts,' specifying the verb (search) and resource (bill texts). It also adds details like returning 50 results per page with relevance scores, bill summaries, and URLs, distinguishing it from siblings like legiscan_find_bill_by_number or legiscan_get_bill.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Use for interactive searches,' which implies usage context but does not explicitly state when not to use or provide alternative tools. The differentiation from siblings is implied by the search functionality, but no direct exclusion or guidance is given.
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.
legiscan_find_bill_by_number1 field changedInput schema / properties / state / patternAdded value: +"^[A-Za-z]{2}$"legiscan_find_legislator2 fields changedInput schema / properties / name / minLengthAdded value: +2Input schema / properties / state / patternAdded value: +"^[A-Za-z]{2}$"legiscan_get_legislator_votes4 fields changedInput schema / properties / bill_ids / descriptionPrevious value: -"Array of bill_ids to check votes on"New value: +"Array of bill_ids to check votes on (max 100)"Input schema / properties / bill_ids / maxItemsAdded value: +100Input schema / properties / bill_ids / minItemsAdded value: +1Input schema / properties / people_id / descriptionPrevious value: -"Legislator people_id to look up votes for"New value: +"Legislator ID (use find_legislator to resolve from name)"legiscan_get_person1 field changedInput schema / properties / people_id / descriptionPrevious value: -"People ID from sponsors, votes, or session people lists"New value: +"Legislator ID (use find_legislator to resolve from name)"legiscan_get_primary_authored2 fields changedInput schema / properties / people_id / descriptionPrevious value: -"Legislator people_id to get primary authored bills for"New value: +"Legislator ID (use find_legislator to resolve from name)"Input schema / properties / state / patternAdded value: +"^[A-Za-z]{2}$"legiscan_get_roll_call1 field changedInput schema / properties / roll_call_id / descriptionPrevious value: -"Roll call ID from bill.votes[] array"New value: +"Roll call ID from get_bill response"legiscan_get_session_list1 field changedInput schema / properties / state / patternAdded value: +"^[A-Za-z]{2}$"legiscan_get_session_people1 field changedInput schema / properties / session_id / descriptionPrevious value: -"Session ID from getSessionList"New value: +"Session ID (use get_session_list to find sessions for a state)"legiscan_search1 field changedInput schema / properties / state / patternAdded value: +"^(?:[A-Za-z]{2}|[Aa][Ll][Ll])$"v1.0.0legiscan_find_bill_by_numberlegiscan_find_legislatorlegiscan_get_billlegiscan_get_legislator_voteslegiscan_get_personlegiscan_get_primary_authoredlegiscan_get_roll_calllegiscan_get_session_listlegiscan_get_session_peoplelegiscan_searchScored across 10 tools
Each tool targets a distinct resource or action (bills, legislators, sessions, votes, search) with clear boundaries. Even related tools like get_legislator_votes and get_roll_call serve different purposes (individual legislator vs. specific roll call).
All tool names follow a consistent 'legiscan_verb_noun' pattern using lowercase with underscores. Verbs are limited to 'find', 'get', and 'search', making the set predictable.
10 tools is well-scoped for a legislative tracking server. Each tool addresses a core need without unnecessary duplication or omission.
The tool surface covers the primary lifecycle for legislative data: discovering sessions, searching bills, retrieving details, and accessing legislator info and votes. No obvious gaps for a read-only MCP server.
Search bills and speaker-attributed hearing transcripts across all 50 US state legislatures.
Search bills, legislators, committees, and events across all 50 US states, DC, and 5 US territories.
LegiScan MCP — wraps the LegiScan API (api.legiscan.com)
Search 209k+ US state bills, all 50 states + DC: full text, sponsors, votes, status. Free.
