Skip to main content
Glama
Sign In

DataPorium

by tech.dataporium
OverviewDiscussionsAdmin

get_election_results

Read-onlyIdempotent

US election results with margins, swing, turnout and partisan lean. Coverage: president and US Senate by state for every election 1976 to 2024, US House by district 1976 to 2024 and county results of the presidential race 2000 to 2024; county, city or town, congressional district and precinct results, governors, other statewide offices, state legislature seats and statewide ballot measures for 2016, 2018, 2020, 2022 and 2024. Results are certified; election-night rows (status live) are unofficial counts and a race is only called when called_at is set. party_margin/rd_margin_pct = Republican share minus Democratic share in points (positive = Republican lead, R+3.2 means Republicans led by 3.2 points); swing_pct is the change of that margin against the previous comparable race in the same area (positive = toward Republicans); flipped = the winning party changed. view "races" (default): races with winner or leader, runner-up, votes and shares, margin, swing, flip; filter by year, office (president, us_senate, us_house, governor, lt_governor, attorney_general, secretary_of_state, treasurer, other_statewide, state_senate, state_house, ballot_measure, judicial; several with commas), state (two-letter code), name (race or candidate text) and filters such as {"margin_max": 5} (close races), {"flipped": true}, {"winner_party": "R"}, {"status": "live"}. Each row has race_id: use it as race in view "results". view "results": one race (race = race_id such as "2024-president", "2024-us-senate-tx", "2022-governor-az") with every candidate (votes and share) and the result by area: level state, county, cousub (city or town), cd (district) or precinct (precinct needs county = 5-digit code); state limits to a state; name searches area names; sort total_votes, rd_margin, swing, dem_pct, rep_pct, turnout or name. view "candidates": people who ran: name, state, office, year, filters {"party": "D", "won": true, "in_congress": true}; with slug (from a candidate row) one candidate with every race. view "geography": one area with its races, partisan lean, bellwether record, split tickets, turnout and demographics: level state, county, cousub, cd or national and area_code (state: 2-digit code such as 48; county: 5-digit code such as 48453), or for a county give state and county name instead of area_code. view "area": the latest elections for a state, county (name) and/or city in one call (state, county, city). view "summary": analysis = trend (national presidential vote by year), seats (seats won by party and change), legislatures (control of state legislature chambers), flips and swing (areas that changed party or moved most; year, office, level state or county), bellwethers, split_tickets, lean (partisan lean index), demographics (county results next to income, education, age and race) or coverage (what is loaded). view "turnout": turnout by state or county and year (share of citizen voting-age adults, registered voters where reported); level state or county, state, name, filters {"min_turnout": 60}. On election night the answer also has election_night_note ("Election night: unofficial, still counting, last update HH:MM UTC"): share it; live rows are only ever "Leading" (leader_label), never a winner. The answer has website_link: share it so the user can see the pages on dataporium.tech.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_election_results"
  }
}

Input Schema

NameRequiredDescriptionDefault
cityNoCity or town name (with state), for view 'area'.
nameNoText to search: a race or candidate name, or an area name.
raceNoA race_id from view 'races', e.g. '2024-president', '2024-us-senate-tx' or '2022-governor-az'.
slugNoCandidate slug from a candidates row, for one candidate with every race.
sortNoSort field (depends on the view, e.g. year, margin, total_votes, rd_margin, swing, turnout, name).
viewNo'races' (list races), 'results' (one race by area), 'candidates', 'geography' (one area in full), 'area' (latest elections of a state, county or city), 'summary' (analysis, see analysis) or 'turnout'.races
yearNoElection year, e.g. 2024.
levelNoArea level: state, county, cousub (city or town), cd (congressional district), precinct or national; for turnout state or county.
limitNoRows to return, 1 to 100 (default 25).
orderNo
stateNoTwo-letter state code, e.g. 'TX'.
countyNoCounty name, e.g. 'Travis' (with state), or for precinct results the 5-digit county code.
officeNoOffice: president, us_senate, us_house, governor, lt_governor, attorney_general, secretary_of_state, treasurer, other_statewide, state_senate, state_house, ballot_measure or judicial; several separated by commas.
offsetNoRows to skip, for the next page.
filtersNoExtra API filters, e.g. {"margin_max": 5, "flipped": true}. list_filters('get_election_results') shows all.
analysisNoFor view 'summary': trend, seats, legislatures, flips, swing, bellwethers, split_tickets, lean, demographics or coverage.
area_codeNoArea code: 2-digit state code (48), 5-digit county code (48453) or 10-digit city or town code.

Output Schema

NameRequiredDescriptionDefault
dataNoThe records: a list of objects (or one object) with the requested data.
noteNoPresent when the answer was shortened, with how to get the rest.
rowsNoNumber of records the API returned (before any shortening).
errorNoPresent when the call failed, with the reason.
detailNoExtra error detail from the API, e.g. which filter is required.
pagingNoFor paged answers: offset, rows_shown, total and next_offset (call again with offset=next_offset for more rows).
endpointNoDataPorium API endpoint that answered, e.g. /company-info.
filters_sentNoFilters sent to the API for this answer.
allowed_filtersNoOn an unknown-filter error: the filters this endpoint accepts.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedOutput schema / properties / paging
      Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "For paged answers: offset, rows_shown, total and next_offset (call again with offset=next_offset for more rows).",
+  "title": "Paging"
+}
  2. Added

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, but the description adds substantive behavior the schema cannot: results are certified, status 'live' rows are unofficial counts, a race is only called when called_at is set, live rows are never a winner (only 'Leading'), and it instructs sharing of election_night_note and website_link. It also defines the derived fields (rd_margin_pct sign convention, swing_pct direction, flipped) which are easy to misinterpret.

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?

Roughly 350 words is long, but with 7 views and 17 parameters nearly every sentence carries a specific fact (coverage windows, margin sign conventions, per-view filter/sort lists). It is front-loaded with purpose and coverage, though the dense unformatted block makes scanning harder than it needs to be.

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 tool of this complexity the description is effectively complete: coverage per office/year, view-by-view behavior and required parameters, computed-field definitions, election-night caveats, and pagination via limit/offset. An output schema exists so return shapes need not be re-explained, and the operational caveats it does add are exactly what an agent needs to answer safely.

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 94%, so the baseline is already 3, but the description goes further by tying parameters to views (race_id feeds 'race' in view results, area_code formats per level, precinct needs the 5-digit county code) and by giving concrete filter examples like {"margin_max": 5, "flipped": true}. It adds real meaning over the schema, though some parameter interactions remain implicit.

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?

Names a specific verb+resource ('US election results') and immediately scopes it: margins, swing, turnout, partisan lean, with explicit coverage windows per office (president/Senate by state 1976-2024, House by district, county presidential 2000-2024, etc.). This is unmistakably distinct from the finance-oriented siblings and an agent can tell what data it returns 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?

The description routes the agent between the seven views explicitly: 'races' (default) lists races, 'results' is one race by area, 'candidates' is people who ran, 'geography' is one area in full, 'summary' uses analysis, etc. It also names the alternative tool list_filters for discovering the full filter set, so both internal and external alternatives are covered.

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

All DataPorium 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