ターミナルエージェントがLegiScan APIに構造化されたアクセスを行い、全米50州および連邦議会の立法データを取得できるようにするModel Context Protocol (MCP) サーバーです。
エージェント（Codex、Claude Code、Claude Desktopなど）に法案の履歴、提案者の背景、投票記録を迅速に収集させるようなリサーチワークフローのために構築されています。
立法リサーチワークフローに最適化された10種類の効率的なMCPツール
複数ステップのリサーチワークフローを単一のMCPツール呼び出しに集約する複合ツール
法案やロールコール（点呼投票）の繰り返し検索に対するリクエストごとのバッチ処理とキャッシュ
すべてのAPIレスポンスに対する完全なTypeScript型定義
法案番号の正規化（AB 858、AB858、AB-858形式に対応）
州コード、議員名クエリ、大規模な法案バッチに対する入力検証ガードレール
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 buildLegiScanで無料アカウントを作成します
https://legiscan.com/legiscan でAPIアクセスを登録します
APIキーをコピーします
ターミナルエージェントが使用するMCPホストにこのサーバーを追加してください。
Claude Desktopの設定パス:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
その他のMCPクライアント（Codex CLI、Claude Codeなど）の場合は、そのクライアントのMCP設定ファイルに同じ mcpServers.legiscan エントリを追加してください。
{
"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"
}
}
}
}ツール | 説明 |
| 名前から議員の |
| 1回の呼び出しで、複数の法案に対する議員の投票状況を取得します。 |
| 議員が主提案者である法案のみを取得します（共同提案者は除外）。 |
ツール | 説明 |
| 詳細な法案情報（提案者、履歴、投票、テキスト）を取得します |
| 番号で法案を検索します（AB 858、AB858、AB-858、A.B. 858に対応）。正確な法案検索に最適です。 |
| 個々の議員の投票を含む投票詳細を取得します |
ツール | 説明 |
| サードパーティID（VoteSmart、OpenSecretsなど）を含む議員情報を取得します |
| 会期中に活動している全議員を取得します |
ツール | 説明 |
| 法案の全文検索を行います。AB858のような法案番号のバリエーションも受け付けますが、完全一致には |
ツール | 説明 |
| 州ごとの利用可能な会期を一覧表示します |
エージェントに目標、州、期間、出力形式を伝えます。
プロンプト例:
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).高品質な結果を得るために、エージェントに以下の順序で実行するよう指示してください:
legiscan_get_session_list で適切な会期を特定する。
legiscan_search または legiscan_find_bill_by_number で対象の法案を見つける。
legiscan_get_bill で提案者/履歴/投票の参照情報を取得する。
legiscan_get_roll_call で個別の投票詳細を取得する。
legiscan_get_person は議員の補足情報が必要な場合のみ使用する。
legiscan_find_legislator から開始する場合は、返された session.session_id または同じ state を後続の提案ワークフローに渡し続け、結果が意図した議会と期間内に収まるようにしてください。
これらはツール呼び出しの回数を減らし、エージェントへの指示を簡素化します:
legiscan_find_legislator: 名前クエリから people_id を取得します。
legiscan_get_primary_authored: 主提案法案と共同提案法案を分離します。
legiscan_get_legislator_votes: 1回のリクエストで多数の法案にわたる投票位置を取得します。
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.複合ツールは、一般的なワークフローにおけるエージェントとツール間の往復回数を劇的に削減します:
ワークフロー | 手動MCPステップ | 複合ツール使用時 |
1人の議員の10法案に対する投票を取得 | 議員検索 → 法案検索/解決 → 各法案の調査 → 各ロールコールの調査 |
|
150の提案法案から主提案法案をフィルタリング | 提案リスト → 各法案の取得 → 提案者の調査 | 1回のツール呼び出し（ |
名前による議員検索 | 会期発見 → 会期中の人物検索 → 手動マッチング | 1回のツール呼び出し |
州コードは2文字の文字列として検証され、自動的に大文字に変換されます（ca → CA）。ZZ のような無効なコードはローカル検証は通過しますが、LegiScanからAPIエラーが返されます。
結果の曖昧さを減らすため、プロンプトでは常に州と会期を指定してください。
追跡可能性を監査できるように、エージェントに中間出力で bill_id、roll_call_id、people_id を表示するよう依頼してください。
議員検索では、少なくとも名と姓を提供してください（名前の入力は2文字以上である必要があります）。
legiscan_get_primary_authored は利用可能なすべての会期を返す可能性がありますが、state または session_id を渡すことで、結果を意図した議会と期間に合わせることができます。
legiscan_get_legislator_votes はリクエストごとに最大100個の bill_ids を受け付けます。大規模なジョブはチャンクに分割してください。
legiscan_search は AB858 のようなコンパクトな法案番号クエリを、標準的なスペース形式を使用して再試行します。正確な法案解決には legiscan_find_bill_by_number を優先してください。
下流工程での分析を予定している場合は、最終出力をテーブルやCSV形式で出力するよう依頼してください。
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: モック化されたネットワーク呼び出しを使用した高速な決定論的テスト。
npm run test:e2e: 実際の立法分析タスクに基づくリサーチワークフローテスト。LEGISCAN_API_KEY が利用できない場合はスキップされます。
npm run test:live: 実際のLegiScan API統合テスト。LEGISCAN_API_KEY が必要です。
無料の公開APIキーには 月間30,000クエリ の制限があります
複合ツールはリクエストをバッチ処理（最大10並列）し、不要な重複を避けるために単一リクエスト内で繰り返し検索をキャッシュします
複合ツールはMCPワークフローの摩擦を軽減しますが、LegiScan APIの使用量は調査する法案やロールコールの数に応じて増加します
コンテナイメージをローカルでビルドします:
docker build -t legiscan-mcp .実行時にAPIキーを指定して実行します:
docker run --rm -i \
-e LEGISCAN_API_KEY=your-api-key-here \
legiscan-mcpGlamaチェックはGitHubリリースを想定しています。次のリポジトリ変更をマージした後、GitHubから、または以下を使用して v1.0.0 などのタグを作成して公開してください:
git tag v1.0.0
git push origin v1.0.0コンテナイメージをローカルでビルドします:
docker build -t legiscan-mcp .実行時にAPIキーを指定して実行します:
docker run --rm -i \
-e LEGISCAN_API_KEY=your-api-key-here \
legiscan-mcpGlamaチェックはGitHubリリースを想定しています。変更をプッシュした後、v1.0.0 などのタグを作成して公開してください。
MIT - 詳細は LICENSE を参照してください。
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.
