Un servidor del Protocolo de Contexto de Modelo (MCP) que brinda a los agentes de terminal acceso estructurado a la API de LegiScan para obtener datos legislativos de los 50 estados de EE. UU. y el Congreso.
Creado para flujos de trabajo de investigación donde diriges a un agente (Codex, Claude Code, Claude Desktop, etc.) para recopilar rápidamente el historial de proyectos de ley, el contexto de los patrocinadores y los registros de votación.
10 herramientas MCP optimizadas para flujos de trabajo de investigación legislativa
Herramientas compuestas que condensan flujos de trabajo de investigación de varios pasos en llamadas a una sola herramienta MCP
Procesamiento por lotes por solicitud y almacenamiento en caché de búsqueda para consultas repetidas de proyectos de ley y votaciones nominales
Definiciones de tipo TypeScript completas para todas las respuestas de la API
Normalización de números de proyectos de ley (maneja formatos AB 858, AB858, AB-858)
Barreras de validación de entrada para códigos de estado, consultas de nombres de legisladores y grandes lotes de proyectos de ley
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 buildCrea una cuenta gratuita en LegiScan
Regístrate para obtener acceso a la API en https://legiscan.com/legiscan
Copia tu clave de API
Añade este servidor a cualquier host MCP que utilice tu agente de terminal.
Rutas de configuración de Claude Desktop:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Para otros clientes MCP (Codex CLI, Claude Code, etc.), añade la misma entrada mcpServers.legiscan en el archivo de configuración MCP de ese cliente.
{
"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"
}
}
}
}Herramienta | Descripción |
| Encuentra el people_id de un legislador por nombre. Admite coincidencias parciales. |
| Obtén cómo votó un legislador en múltiples proyectos de ley en una sola llamada. |
| Obtén solo los proyectos de ley donde el legislador es el autor principal (no copatrocinador). |
Herramienta | Descripción |
| Obtén información detallada del proyecto de ley (patrocinadores, historial, votos, textos) |
| Encuentra un proyecto de ley por número (maneja AB 858, AB858, AB-858, A.B. 858). Ideal para búsquedas exactas. |
| Obtén detalles de la votación con los votos individuales de los legisladores |
Herramienta | Descripción |
| Obtén información del legislador con identificadores de terceros (VoteSmart, OpenSecrets, etc.) |
| Obtén todos los legisladores activos en una sesión |
Herramienta | Descripción |
| Búsqueda de texto completo en la legislación. Acepta variantes de números de proyectos de ley como AB858, pero usa |
Herramienta | Descripción |
| Enumera las sesiones legislativas disponibles por estado |
Dale a tu agente un objetivo, estado, marco temporal y formato de salida.
Ejemplo de 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).Para obtener resultados de alta calidad, dile al agente que siga este orden:
legiscan_get_session_list para identificar la sesión correcta.
legiscan_search o legiscan_find_bill_by_number para localizar los proyectos de ley objetivo.
legiscan_get_bill para referencias de patrocinadores/historial/votos.
legiscan_get_roll_call para detalles de votos individuales.
legiscan_get_person solo cuando se necesite enriquecimiento de datos del legislador.
Si comienzas con legiscan_find_legislator, sigue pasando el session.session_id devuelto o el mismo state a los flujos de trabajo de autoría posteriores para que los resultados permanezcan en la legislatura y el marco temporal previstos.
Estas reducen el volumen de llamadas a herramientas y simplifican las instrucciones para tu agente:
legiscan_find_legislator: obtén people_id a partir de una consulta de nombre.
legiscan_get_primary_authored: separa los proyectos de ley de autoría principal de los copatrocinados.
legiscan_get_legislator_votes: extrae posiciones de voto en muchos proyectos de ley en una sola solicitud.
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.Las herramientas compuestas reducen drásticamente los viajes de ida y vuelta entre agente y herramienta para flujos de trabajo comunes:
Flujo de trabajo | Pasos manuales de MCP | Con herramientas compuestas |
Obtener votos de 1 legislador en 10 proyectos de ley | Encontrar legislador → buscar/resolver proyectos → inspeccionar cada proyecto → inspeccionar cada votación | 1 llamada a herramienta una vez que tengas los |
Filtrar autoría principal de 150 proyectos patrocinados | Lista de patrocinados → obtener cada proyecto → inspeccionar patrocinadores | 1 llamada a herramienta, opcionalmente delimitada por |
Encontrar legislador por nombre | Descubrimiento de sesión → búsqueda de personas en sesión → coincidencia manual | 1 llamada a herramienta |
Los códigos de estado se validan como cadenas de dos letras y se convierten automáticamente a mayúsculas (ca → CA). Los códigos no válidos como ZZ pasan la validación local pero devuelven un error de API de LegiScan.
Fija siempre el estado y la sesión en tu prompt para reducir resultados ambiguos.
Pide al agente que muestre bill_id, roll_call_id y people_id en la salida intermedia para que puedas auditar la trazabilidad.
Para la búsqueda de legisladores, proporciona al menos un nombre y un apellido (la entrada de nombre debe tener al menos 2 caracteres).
legiscan_get_primary_authored puede devolver todas las sesiones disponibles, pero pasar state o session_id mantiene los resultados alineados con la legislatura y el marco temporal previstos.
legiscan_get_legislator_votes acepta hasta 100 bill_ids por solicitud; divide los trabajos más grandes en fragmentos.
legiscan_search reintenta consultas compactas de números de proyectos de ley como AB858 usando un formato canónico con espacios. Para una resolución exacta de proyectos de ley, prefiere legiscan_find_bill_by_number.
Solicita las salidas finales en un formato de tabla o compatible con CSV si planeas realizar análisis posteriores.
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: Pruebas deterministas rápidas con llamadas de red simuladas.
npm run test:e2e: Pruebas de flujo de trabajo de investigación basadas en tareas reales de análisis legislativo. Se omite si LEGISCAN_API_KEY no está disponible.
npm run test:live: Pruebas de integración de la API real de LegiScan. Requiere LEGISCAN_API_KEY.
Las claves de API públicas gratuitas tienen un límite de 30,000 consultas por mes.
Las herramientas compuestas procesan solicitudes por lotes (máximo 10 concurrentes) y almacenan en caché las búsquedas repetidas dentro de una sola solicitud para evitar duplicaciones innecesarias.
Las herramientas compuestas reducen la fricción del flujo de trabajo MCP, pero el uso de la API de LegiScan sigue escalando con el número de proyectos de ley y votaciones distintas que inspecciones.
Construye la imagen del contenedor localmente:
docker build -t legiscan-mcp .Ejecútalo con tu clave de API proporcionada en tiempo de ejecución:
docker run --rm -i \
-e LEGISCAN_API_KEY=your-api-key-here \
legiscan-mcpLas comprobaciones de Glama esperan un lanzamiento de GitHub. Después de fusionar los cambios de tu repositorio, crea y publica una etiqueta como v1.0.0 desde GitHub o con:
git tag v1.0.0
git push origin v1.0.0Construye la imagen del contenedor localmente:
docker build -t legiscan-mcp .Ejecútalo con tu clave de API proporcionada en tiempo de ejecución:
docker run --rm -i \
-e LEGISCAN_API_KEY=your-api-key-here \
legiscan-mcpLas comprobaciones de Glama esperan un lanzamiento de GitHub. Crea y publica una etiqueta como v1.0.0 después de enviar los cambios.
MIT - consulta LICENSE para más detalles.
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.
