Skip to main content
Glama

KeyVex

by com.keyvex
OverviewDiscussionsAdmin

get_fec_candidate_profile

Read-only

Returns FEC-registered candidate profiles (House, Senate, President) and — when include_committees=true (default) — each candidate's associated FEC committees in the same response. Use this when the user asks about: who's running in race X, the campaign finance ID for a member, what PAC is sponsoring a candidate, or to bridge from a Congressional member name to their FEC committee_id before looking up contributions (v1.1 tool). Source: api.open.fec.gov — the official Federal Election Commission public-disclosure API. Records include current sitting members, primary challengers, defeated candidates, future-cycle registrants, and presidential candidates. Cycles tracked: 2022, 2024, 2026. Filter by candidate_id for the fastest direct lookup. Otherwise use candidate_name (case-insensitive substring) optionally narrowed by office + state + cycle. FEC names are typically filed as LASTNAME, FIRSTNAME (e.g., 'MCCORMICK, DAVE' for Dave McCormick). Office codes: H (House), S (Senate), P (President). Party codes: DEM (Democratic), REP (Republican), LIB (Libertarian), GRE (Green), IND (Independent), OTH (Other). Incumbent_challenge: I (Incumbent), C (Challenger), O (Open seat). When active_only=true, only candidates with candidate_status='C' (currently filing) are returned. Committee designations on returned committees: P (Principal campaign committee — the primary donation recipient), A (Authorized — accepts donations on candidate's behalf), B (Lobbyist), D (Leadership PAC), J (Joint fundraiser), U (Unauthorized). The Principal (P) committee is the one you want for 'donations to X's campaign'. Committee types: H (House campaign), S (Senate campaign), P (Presidential campaign), Q (PAC qualified), N (PAC non-qualified), O (Super PAC), I (Independent expenditure non-PAC), X/Y/Z (Party), V/W (Carey/hybrid). For 'follow the money to Senator X', look for designation=P, committee_type=S among the returned committees.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
cycleNoElection cycle year (e.g., 2026). Returns candidates whose cycles[] includes this value. Common cycles: 2022, 2024, 2026.
limitNoMaximum candidates to return. Default 50, max 500.
partyNoParty code: DEM | REP | LIB | GRE | IND | OTH.
stateNo2-letter state abbreviation (e.g., 'PA', 'CA'). Empty for President. Combine with office=S to find the senators from a state.
officeNoOffice code: H=House, S=Senate, P=President. Narrows ambiguous name matches.
sort_byNoSort key. Default: last_file_date (most recent first).
districtNoHouse district as 2-digit string ('01'-'53') or 'AL' for at-large. Senate/President leave blank.
sort_orderNoDefault: desc.
active_onlyNoWhen true, restricts to candidate_inactive=false (currently active filers). Default false (includes withdrawn / defeated / inactive).
candidate_idNoFEC-assigned candidate ID (immutable across cycles), e.g., 'S6PA00091' for Pat Toomey, 'P80003338' for Mitt Romney's 2008 presidential bid. Direct doc lookup, fastest path.
candidate_nameNoCase-insensitive substring against the FEC-filed candidate name (typically LASTNAME, FIRSTNAME format). Example: 'mccormick' or 'collins'.
include_committeesNoWhen true (default), each returned candidate is enriched with a `committees` array containing all FEC committees linked via candidate_ids[]. The principal campaign committee (designation='P') is listed first. Set false to skip the committee fetch for faster responses when you only need candidate profile fields.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnlyHint/openWorldHint/destructiveHint=false, so the safety profile is covered. The description still adds real behavioral context beyond that: the default include_committees=true triggers a committee enrichment fetch, the cycles tracked (2022/2024/2026), and that active_only=true restricts to status='C'. It does not discuss pagination or rate limits, so a 4 rather than a 5.

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 triggers before the reference-code detail, and most sentences earn their place. However the office codes, party codes, and incumbent_challenge codes restate enums already present in the schema, adding length without new information.

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?

For a 12-parameter, zero-required, no-output-schema tool, the description covers lookup strategy, filtering dimensions, default behaviors, and the FEC domain code systems an agent would otherwise have to guess. Nothing needed to call it correctly is missing.

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 baseline is 3; the description nonetheless adds meaning beyond the schema by explaining the LASTNAME, FIRSTNAME filing convention, the designation=P 'principal committee is the one you want for donations' heuristic, and committee_type semantics for following money. The office and party code lists largely duplicate the schema enums, which caps this below 5.

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 (FEC-registered candidate profiles plus their committees) and clearly bounds scope: House, Senate, President. It also implicitly distinguishes itself from the sibling contribution/disbursement tools by naming itself the bridge to committee_id, so an agent can place it without opening the schema.

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?

Gives explicit triggering questions ('who's running in race X', 'the campaign finance ID for a member', 'what PAC is sponsoring a candidate') and the workflow position ('bridge from a Congressional member name to their FEC committee_id before looking up contributions'). It also states the fastest lookup path (candidate_id) versus the name-based path.

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

All KeyVex toolsInspect
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