openfec-mcp-server

Openfec Get Committee Totals

openfec_get_committee_totals

Read-onlyIdempotent

Get pre-aggregated committee financial totals — receipts, disbursements, cash on hand, debts, and the itemized/unitemized breakdown — without paginating Schedule A. Use mode "single" (the default) with a committee_id for one committee's totals, one row per two-year cycle it has filed. Use mode "by_entity_type" to rank or screen every committee of one type (presidential, pac, party, pac-party, house-senate, ie-only) by state, designation, or a receipts/disbursements threshold.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`mode`	No	Query mode. "single" returns one committee's totals, one row per cycle. "by_entity_type" returns a page of committees of one entity type, filterable and sortable across committees.	single
`page`	No	Page number (1-indexed). Read pagination.pages in the response to see how many pages exist — a long-running committee can have more cycles than one page holds.
`sort`	No	Sort field. A "-" prefix sorts descending: "-receipts" ranks the biggest fundraisers first in by_entity_type mode, "-cycle" puts a committee's most recent cycle first in single mode.
`cycle`	No	Two-year election cycle (e.g., 2024). Even years only. Omit in single mode to get every cycle the committee has filed.
`per_page`	No	Results per page.
`entity_type`	No	Committee entity type for the grouped search. Required in by_entity_type mode. house-senate covers both chambers as one group; ie-only is committees that report only independent expenditures.
`committee_id`	No	Committee ID (e.g., C00703975). Get IDs from openfec_search_committees results. Required in single mode; in by_entity_type mode it narrows the grouped search to that one committee.
`max_receipts`	No	Maximum total receipts in dollars. by_entity_type mode only.
`min_receipts`	No	Minimum total receipts in dollars. by_entity_type mode only.
`committee_type`	No	Committee type code — H (House), S (Senate), P (Presidential), O (Super PAC), N/Q (PAC), X/Y (party). by_entity_type mode only.
`committee_state`	No	Two-letter state code of the committee. by_entity_type mode only.
`max_disbursements`	No	Maximum total disbursements in dollars. by_entity_type mode only.
`min_disbursements`	No	Minimum total disbursements in dollars. by_entity_type mode only.
`organization_type`	No	Sponsoring organization type — C (corporation), L (labor), M (membership), T (trade), V (cooperative), W (corporation without capital stock). by_entity_type mode only.
`committee_designation`	No	Committee designation — A (authorized), B (lobbyist PAC), D (leadership PAC), J (joint fundraiser), P (principal campaign), U (unauthorized). by_entity_type mode only.

Output Schema

TableJSON Schema

Name	Required	Description
`mode`	No	Query mode as the server resolved it. Rows mean different things by mode — single rows are cycles of one committee, by_entity_type rows are different committees — so read this rather than inferring from the fields present.
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Guidance when the response carries no totals: how to broaden a search that matched nothing, or which requested position ran out when totals did match.
`results`	No	Committee totals result set; one row per cycle in single mode, one row per committee in by_entity_type mode.
`pagination`	No	Page-based pagination metadata.
`totalCount`	No	Total matching totals rows before pagination.
`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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 22, 2026

changedOutput schema / properties / notice / description

Previous value: -"Guidance when no totals matched — echoes filters and suggests how to broaden."New value: +"Guidance when the response carries no totals: how to broaden a search that matched nothing, or which requested position ran out when totals did match."

addedOutput schema / properties / pagination / properties / count_is_approximate

Added value: +{
+  "description": "True when OpenFEC reports this count as an estimate rather than a tally, which it does on its highest-volume datasets. Absent means the count is a tally. An estimated count — and the pages derived from it — can be off by a wide margin; treat it as an order of magnitude, not a figure to quote.",
+  "type": "boolean"
+}

Changed1 schema field changedSep 19, 2026

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `committee_id_required_for_single_mode`: Mode single invoked without a committee_id `entity_type_required_for_group_mode`: Mode by_entity_type invoked without an entity_type `inputs_not_applicable_to_mode`: A grouped-search filter (entity_type, committee_state, committee_type, committee_designation, organization_type, or a receipts/disbursements bound) was supplied alongside mode single, which cannot apply it `committee_totals_not_found`: Single-committee lookup matched no totals row — the committee_id does not exist, it filed nothing in the requested cycle, or it has never filed a financial report at all Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `committee_id_required_for_single_mode`: Mode single invoked without a committee_id. `entity_type_required_for_group_mode`: Mode by_entity_type invoked without an entity_type. `inputs_not_applicable_to_mode`: A grouped-search filter (entity_type, committee_state, committee_type, committee_designation, organization_type, or a receipts/disbursements bound) was supplied alongside mode single, which cannot apply it. `committee_totals_not_found`: Single-committee lookup matched no totals row — the committee_id does not exist, it filed nothing in the requested cycle, or it has never filed a financial report at all. Other values are possible when a failure originates below the handler."

Changed6 schema fields changedAug 25, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "results",
+      "mode",
+      "pagination",
+      "search_criteria",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `committee_id_required_for_single_mode`: Mode single invoked without a committee_id `entity_type_required_for_group_mode`: Mode by_entity_type invoked without an entity_type `inputs_not_applicable_to_mode`: A grouped-search filter (entity_type, committee_state, committee_type, committee_designation, organization_type, or a receipts/disbursements bound) was supplied alongside mode single, which cannot apply it `committee_totals_not_found`: Single-committee lookup matched no totals row — the committee_id does not exist, it filed nothing in the requested cycle, or it has never filed a financial report at all Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "committee_id_required_for_single_mode",
+            "entity_type_required_for_group_mode",
+            "inputs_not_applicable_to_mode",
+            "committee_totals_not_found"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "results",
-  "mode",
-  "pagination",
-  "search_criteria",
-  "totalCount"
-]

AddedJul 26, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already mark the operation as read-only and idempotent, so the description can focus on additional behavior. It discloses that results are pre-aggregated, that single mode returns one row per two-year cycle, and that by_entity_type mode supports ranking across committees. This goes beyond the annotations without contradicting them.

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?

Three tightly written sentences front-load the tool's purpose and data contents, then give mode usage guidance. Every sentence earns its place and no words are wasted.

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 15-parameter tool with two modes, the description provides enough high-level orientation: how to select a mode, what each mode returns, and how this tool relates to Schedule A data. The detailed input schema and output schema cover the remaining specifics, so nothing needed for correct invocation is missing.

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 description coverage is 100%, so the baseline is 3 even without additional param detail in the tool description. The description adds helpful mode-level framing, but it mostly restates the schema's mode and committee_id semantics rather than adding new parameter information.

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 opens with a specific verb and resource: 'Get pre-aggregated committee financial totals' and enumerates the exact data fields returned. It also distinguishes this tool from raw Schedule A lookup by the phrase 'without paginating Schedule A.'

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?

The description explicitly explains when to use each mode: 'single' for one committee's totals and 'by_entity_type' for ranking or screening committees by type, state, or thresholds. It also states the default mode and that committee_id is the key input for the single mode.

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

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.