KeyVex

get_roll_call_votes

Read-only

Returns congressional roll-call vote metadata (House + Senate) from api.congress.gov. Use this when the user asks about: recent votes in either chamber, votes on a specific bill, votes by date range, or to chain to per-member positions via the source_data_url. Sources: api.congress.gov v3 for House votes; senate.gov XML (legislative/LIS/roll_call_lists/) for Senate votes — joined into one collection. Captures roll-call (recorded) votes only — voice votes and unanimous-consent passages aren't roll calls and don't appear here. v1A returns vote-level metadata: chamber, roll call number, vote type, result, the legislation being voted on (linked via bill_id), and links to the Clerk's authoritative XML data. Per-member positions (yea/nay/present/not voting per bioguide_id) live in the XML at source_data_url; agents fetch that directly when they need member detail. v1.1 will add a separate roll_call_member_votes tool/ collection for queryable per-member positions. Vote identifiers are stable composite keys: '{chamber}-{congress}- {session}-{rcNumber}', e.g., 'house-119-1-240' or 'senate-119-1-15'. Common vote_type values: 'Yea-And-Nay' (regular recorded vote), '2/3 Yea-And-Nay' (suspension of rules, requires 2/3 majority), 'Recorded Vote', 'Quorum'. Common result values: 'Passed', 'Failed', 'Agreed to', 'Rejected', 'Motion Agreed To', 'Motion Failed'. When a vote is on a bill, legislation_type + legislation_number are populated and bill_id is set to the composite key — use that to join to get_bills. For procedural votes (motion to recommit, motion to adjourn, etc.), those fields may be empty. Amendment + Senate detail: House votes ON AN AMENDMENT carry amendment_number, amendment_author (sponsor + label), and amendment_type (e.g. 'HAMDT'). Senate votes carry vote_title (descriptive title — e.g. a confirmation or motion), measure (the specific measure a question references, e.g. 'S.Amdt. 5740'), and en_bloc_matters[] (one {issue, question, result} per matter when a batch of nominations is decided en bloc). All are empty / [] where not applicable.

Input Schema

TableJSON Schema

Name	Required	Description
`limit`	No	Maximum votes to return. Default 50, max 500.
`since`	No	Vote-start date lower bound (ISO YYYY-MM-DD inclusive).
`until`	No	Vote-start date upper bound (ISO YYYY-MM-DD inclusive).
`result`	No	Substring match against result text (e.g., 'passed', 'failed', 'agreed').
`bill_id`	No	Filter to votes on a specific bill (composite key like '119-HR-134'). Use to chain a bill lookup → votes on that bill.
`chamber`	No	Filter to House or Senate roll calls.
`sort_by`	No	Default: start_date (most recent votes first).
`vote_id`	No	Composite vote identifier ('{chamber}-{congress}-{session}-{rcNumber}', e.g., 'house-119-1-240'). Direct doc lookup, fastest path.
`congress`	No	Congress number (e.g., 119).
`sort_order`	No	Default: desc.
`session_number`	No	Session within the Congress. Session 1 = first calendar year of the Congress; Session 2 = second year.
`legislation_type`	No	Filter to votes on a specific legislation type.

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 4, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint/openWorldHint/destructiveHint=false, and the description goes well beyond that: it discloses the two upstream sources (api.congress.gov v3 and senate.gov XML), the join into one collection, what is excluded (non-recorded votes), what v1A returns vs. what a future v1.1 tool will add, and where per-member positions live. This is unusually rich behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and usage before diving into metadata details, which is good structure. However it is quite long and includes some enumerations (vote_type/result values) that border on redundancy for a schema that already documents parameters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden and does so: it enumerates the returned metadata fields (chamber, roll call number, vote type, result, legislation link, XML links) and explains amendment/Senate-specific fields. An agent has everything needed to call and interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds value by explaining the vote_id composite key pattern, that bill_id is a join key to get_bills, and that legislation fields are empty for procedural votes. It reinforces but doesn't fully supersede the schema's own parameter docs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Returns congressional roll-call vote metadata (House + Senate)') and clearly distinguishes itself from siblings like get_bills and get_member_profile by scoping to vote-level data. The composite key format and chamber scope make it unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly enumerates when to use it ('recent votes in either chamber, votes on a specific bill, votes by date range') and when not ('voice votes and unanimous-consent passages aren't roll calls and don't appear here'). It also names the chaining path to get_bills and clarifies that per-member detail requires fetching source_data_url rather than this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All KeyVex tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?