터미널 에이전트가 미국 50개 주 및 의회의 입법 데이터를 위해 LegiScan API에 구조화된 방식으로 액세스할 수 있도록 하는 MCP(Model Context Protocol) 서버입니다.
에이전트(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"
}
}
}
}도구 | 설명 |
| 이름으로 의원의 people_id를 찾습니다. 부분 일치를 지원합니다. |
| 한 번의 호출로 여러 법안에 대한 의원의 투표 결과를 가져옵니다. |
| 의원이 공동 발의자가 아닌 주 발의자인 법안만 가져옵니다. |
도구 | 설명 |
| 상세 법안 정보(발의자, 이력, 투표, 텍스트)를 가져옵니다. |
| 번호로 법안을 찾습니다(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: 한 번의 요청으로 여러 법안에 걸친 투표 입장을 가져옵니다.
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 단계 | 복합 도구 사용 시 |
10개 법안에 대한 1명 의원의 투표 가져오기 | 의원 찾기 → 법안 검색/해결 → 각 법안 검사 → 각 호명 투표 검사 |
|
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.
