Ein Model Context Protocol (MCP)-Server, der Terminal-Agenten strukturierten Zugriff auf die LegiScan-API für Gesetzgebungsdaten aus allen 50 US-Bundesstaaten und dem Kongress bietet.
Entwickelt für Recherche-Workflows, bei denen Sie einen Agenten (Codex, Claude Code, Claude Desktop usw.) anweisen, schnell Gesetzesverläufe, Informationen zu Sponsoren und Abstimmungsergebnisse zu sammeln.
10 optimierte MCP-Tools für Workflows in der gesetzgeberischen Recherche
Zusammengesetzte Tools, die mehrstufige Recherche-Workflows in einzelne MCP-Tool-Aufrufe zusammenfassen
Batch-Verarbeitung pro Anfrage und Caching für wiederholte Abfragen von Gesetzesentwürfen und namentlichen Abstimmungen
Vollständige TypeScript-Typdefinitionen für alle API-Antworten
Normalisierung von Gesetzesnummern (unterstützt Formate wie AB 858, AB858, AB-858)
Eingabevalidierung für Bundesstaat-Codes, Abgeordnetennamen-Abfragen und große Batches von Gesetzesentwürfen
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 buildErstellen Sie ein kostenloses Konto bei LegiScan
Registrieren Sie sich für den API-Zugriff unter https://legiscan.com/legiscan
Kopieren Sie Ihren API-Schlüssel
Fügen Sie diesen Server dem MCP-Host hinzu, den Ihr Terminal-Agent verwendet.
Konfigurationspfade für Claude Desktop:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Für andere MCP-Clients (Codex CLI, Claude Code usw.) fügen Sie denselben mcpServers.legiscan-Eintrag in die MCP-Konfigurationsdatei des Clients ein.
{
"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 | Beschreibung |
| Findet die |
| Ruft in einem Aufruf ab, wie ein Abgeordneter bei mehreren Gesetzesentwürfen abgestimmt hat. |
| Ruft nur Gesetzesentwürfe ab, bei denen der Abgeordnete Hauptautor ist (kein Co-Sponsor). |
Tool | Beschreibung |
| Ruft detaillierte Informationen zu Gesetzesentwürfen ab (Sponsoren, Verlauf, Abstimmungen, Texte) |
| Findet einen Gesetzesentwurf anhand der Nummer (unterstützt AB 858, AB858, AB-858, A.B. 858). Am besten für die exakte Suche. |
| Ruft Abstimmungsdetails mit den Stimmen einzelner Abgeordneter ab |
Tool | Beschreibung |
| Ruft Informationen zu Abgeordneten mit Drittanbieter-IDs ab (VoteSmart, OpenSecrets usw.) |
| Ruft alle in einer Legislaturperiode aktiven Abgeordneten ab |
Tool | Beschreibung |
| Volltextsuche in der Gesetzgebung. Akzeptiert Varianten von Gesetzesnummern wie AB858, verwenden Sie jedoch |
Tool | Beschreibung |
| Listet verfügbare Legislaturperioden nach Bundesstaat auf |
Geben Sie Ihrem Agenten ein Ziel, einen Bundesstaat, einen Zeitrahmen und ein Ausgabeformat vor.
Beispiel-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).Für qualitativ hochwertige Ergebnisse weisen Sie den Agenten an, diese Reihenfolge einzuhalten:
legiscan_get_session_list, um die korrekte Legislaturperiode zu identifizieren.
legiscan_search oder legiscan_find_bill_by_number, um Ziel-Gesetzesentwürfe zu finden.
legiscan_get_bill für Referenzen zu Sponsoren/Verlauf/Abstimmungen.
legiscan_get_roll_call für Details zu einzelnen Abstimmungen.
legiscan_get_person nur, wenn eine Anreicherung der Abgeordnetendaten erforderlich ist.
Wenn Sie mit legiscan_find_legislator beginnen, geben Sie die zurückgegebene session.session_id oder denselben state an nachfolgende Workflows weiter, damit die Ergebnisse in der beabsichtigten Legislative und im Zeitrahmen bleiben.
Diese reduzieren das Volumen der Tool-Aufrufe und vereinfachen die Anweisungen an Ihren Agenten:
legiscan_find_legislator: people_id aus einer Namensabfrage abrufen.
legiscan_get_primary_authored: Hauptautoren von Co-Sponsoren bei Gesetzesentwürfen trennen.
legiscan_get_legislator_votes: Abstimmungspositionen zu vielen Gesetzesentwürfen in einer Anfrage abrufen.
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.Die zusammengesetzten Tools reduzieren die Roundtrips zwischen Agent und Tool für gängige Workflows drastisch:
Workflow | Manuelle MCP-Schritte | Mit zusammengesetzten Tools |
Stimmen für 1 Abgeordneten zu 10 Entwürfen | Abgeordneten finden → Entwürfe suchen/auflösen → jeden Entwurf prüfen → jede Abstimmung prüfen | 1 Tool-Aufruf, sobald Sie |
Hauptautoren von 150 gesponserten Entwürfen filtern | Sponsorenliste → jeden Entwurf abrufen → Sponsoren prüfen | 1 Tool-Aufruf, optional nach |
Abgeordneten nach Namen finden | Sitzungsermittlung → Suche nach Personen in der Sitzung → manueller Abgleich | 1 Tool-Aufruf |
Bundesstaat-Codes werden als zwei-Buchstaben-Strings validiert und automatisch in Großbuchstaben umgewandelt (ca → CA). Ungültige Codes wie ZZ bestehen die lokale Validierung, führen aber zu einem API-Fehler von LegiScan.
Fixieren Sie immer Bundesstaat und Legislaturperiode in Ihrem Prompt, um mehrdeutige Ergebnisse zu reduzieren.
Bitten Sie den Agenten, bill_id, roll_call_id und people_id in der Zwischenausgabe anzuzeigen, damit Sie die Rückverfolgbarkeit prüfen können.
Geben Sie für die Suche nach Abgeordneten mindestens einen Vor- und Nachnamen an (die Namenseingabe muss mindestens 2 Zeichen lang sein).
legiscan_get_primary_authored kann alle verfügbaren Sitzungen zurückgeben, aber die Angabe von state oder session_id hält die Ergebnisse auf die beabsichtigte Legislative und den Zeitrahmen ausgerichtet.
legiscan_get_legislator_votes akzeptiert bis zu 100 bill_ids pro Anfrage; teilen Sie größere Aufträge in Blöcke auf.
legiscan_search wiederholt kompakte Abfragen von Gesetzesnummern wie AB858 unter Verwendung eines kanonischen Formats mit Leerzeichen. Für die exakte Auflösung von Gesetzesentwürfen bevorzugen Sie legiscan_find_bill_by_number.
Fragen Sie nach Endergebnissen in einer für Tabellen/CSV geeigneten Form, wenn Sie eine nachgelagerte Analyse planen.
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: Schnelle deterministische Tests mit gemockten Netzwerkaufrufen.
npm run test:e2e: Recherche-Workflow-Tests basierend auf echten gesetzgeberischen Analyseaufgaben. Wird übersprungen, wenn LEGISCAN_API_KEY nicht verfügbar ist.
npm run test:live: Echte LegiScan-API-Integrationstests. Erfordert LEGISCAN_API_KEY.
Kostenlose öffentliche API-Schlüssel haben ein Limit von 30.000 Abfragen pro Monat.
Zusammengesetzte Tools führen Batch-Anfragen durch (maximal 10 gleichzeitig) und cachen wiederholte Abfragen innerhalb einer einzigen Anfrage, um unnötige Duplikate zu vermeiden.
Zusammengesetzte Tools reduzieren die Reibung im MCP-Workflow, aber die Nutzung der LegiScan-API skaliert weiterhin mit der Anzahl der verschiedenen Gesetzesentwürfe und Abstimmungen, die Sie untersuchen.
Bauen Sie das Container-Image lokal:
docker build -t legiscan-mcp .Führen Sie es mit Ihrem zur Laufzeit bereitgestellten API-Schlüssel aus:
docker run --rm -i \
-e LEGISCAN_API_KEY=your-api-key-here \
legiscan-mcpGlama-Prüfungen erwarten ein GitHub-Release. Erstellen und veröffentlichen Sie nach dem Zusammenführen Ihrer nächsten Repo-Änderungen ein Tag wie v1.0.0 von GitHub oder mit:
git tag v1.0.0
git push origin v1.0.0Bauen Sie das Container-Image lokal:
docker build -t legiscan-mcp .Führen Sie es mit Ihrem zur Laufzeit bereitgestellten API-Schlüssel aus:
docker run --rm -i \
-e LEGISCAN_API_KEY=your-api-key-here \
legiscan-mcpGlama-Prüfungen erwarten ein GitHub-Release. Erstellen und veröffentlichen Sie ein Tag wie v1.0.0, nachdem Sie Änderungen gepusht haben.
MIT - siehe LICENSE für 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.
