openfec-mcp-server

Openfec Search Candidates

openfec_search_candidates

Read-onlyIdempotent

Find federal candidates by name, state, office, party, or cycle. Retrieve a specific candidate by FEC ID with financial totals. Candidate IDs start with H (House), S (Senate), or P (President) followed by exactly eight letters or digits.

Input Schema

TableJSON Schema

Name	Required	Description
`page`	No	Search-results page number (1-indexed). Defaults to 1 on the search path.
`cycle`	No	Two-year election cycle (even year, e.g., 2024).
`party`	No	Three-letter party code (e.g., DEM, REP, LIB).
`query`	No	Full-text candidate name search.
`state`	No	Two-letter US state code (e.g., AZ, CA).
`office`	No	Filter by office: H=House, S=Senate, P=President.
`district`	No	Two-digit district number for House candidates.
`per_page`	No	Search results per page. Defaults to 20 on the search path.
`candidate_id`	No	FEC candidate ID: H, S, or P followed by exactly eight letters or digits (e.g., P00003392, H2CO07170). Get IDs from openfec_search_candidates results. When provided, returns a single candidate with full detail.
`election_year`	No	Specific election year the candidate ran in.
`include_totals`	No	Include financial totals (receipts, disbursements, cash on hand). Defaults to true when fetching by candidate_id.
`candidate_status`	No	Candidate status: C=present, F=future, N=not yet, P=prior.
`has_raised_funds`	No	Only candidates whose committee has received receipts.
`incumbent_challenge`	No	Incumbent status: I=incumbent, C=challenger, O=open seat.

Output Schema

TableJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Guidance when no candidates matched — echoes filters and suggests how to broaden.
`totals`	No	Financial totals (receipts, disbursements, cash_on_hand) when include_totals is true. One row per candidate per cycle.
`candidates`	No	Candidate result set; one record per match.
`pagination`	No	Page-based pagination metadata.
`totalCount`	No	Total matching candidates before pagination.
`missing_totals`	No	Candidates whose financial totals were not retrieved because the totals fetch hit its page cap. Re-query each one on its own with candidate_id to get its totals.
`search_criteria`	No	Echo of the search filters this call applied, as the server parsed them, minus paging arguments. Always present — compare it against what you sent to confirm every filter was honoured.

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds behavioral detail: when candidate_id is provided, it returns a single candidate with full detail, and include_totals defaults to true in that case. This goes beyond the annotations and informs the agent about the tool's behavior for different input combinations, which is valuable context.

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

Conciseness5/5

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

The description is two sentences with zero unnecessary words. The primary purpose is stated first, followed by a useful technical detail about candidate ID format. It is front-loaded, efficient, and every sentence earns its place.

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

Completeness4/5

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

The description covers the two main usage modes (search and retrieve by ID) and includes a key format note. With an output schema present, return values need not be explained. It omits detailed filter combinations or pagination behavior, but those are covered by the schema's parameter descriptions. For a search tool with many optional parameters, this is reasonably complete.

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

Parameters3/5

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

Schema coverage is 100%, so all parameters are already described in the schema. The description reinforces the candidate_id format but does not add new meaning beyond that. Since the schema fully documents parameters, the description's contribution is minimal, warranting the baseline score for high coverage.

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?

The description clearly states two primary functions: searching federal candidates by various filters (name, state, office, party, cycle) and retrieving a specific candidate by FEC ID with financial totals. It also specifies the ID format, distinguishing candidate IDs from other entity types. This is a specific verb+resource with clear scope.

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

Usage Guidelines4/5

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

The description gives clear context: it is for finding candidates and for retrieving a single candidate by ID. It does not explicitly compare with sibling tools like openfec_search_committees, but the unique focus on candidates and the distinction between search and ID-based retrieval provide adequate usage guidance. No explicit exclusions or alternatives are mentioned, but the title and description make the tool's purpose unambiguous.

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

All openfec-mcp-server tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.1/5.0

Disambiguation5/5

Each tool targets a clearly distinct FEC resource or action, and even closely related tools are explicitly differentiated. Independent versus coordinated expenditures and legal search versus legal document retrieval are described in enough detail that an agent should not misselect.

Naming Consistency5/5

All tools share the openfec_ prefix and follow a predictable verb_noun snake_case pattern: get for direct retrieval, lookup for calendar/election lookups, and search for queryable datasets. The naming is highly consistent across the full tool set.

Tool Count5/5

Twelve tools is well-scoped for a campaign-finance data server covering candidates, committees, money flows, filings, legal documents, calendar, and elections. Each tool represents a meaningful slice of the domain without unnecessary overlap or bloat.

Completeness4/5

The tool surface covers core FEC workflows thoroughly: candidates, committees, contributions, disbursements, independent and coordinated expenditures, filings, legal documents, calendar, and elections. The only notable gaps are specialized FEC categories such as electioneering communications and communication costs, which are not exposed.

Openfec Search Candidates

Input Schema

Output Schema

TDQS

Glama MCP Gateway

TDQS

Resources