ElectionsMCP MCP server
An MCP server that allows agents to build user-controlled election scenarios, model presidential and primary races, explore geography, compare candidates, and coordinate campaign work through tools like create_simulation, aggregate_precincts, and render_view.
Endpoint and access
No sign-in to connect and list tools. Individual tools may still need a vendor account, credentials, or permissions; check the documented prerequisites.
Get a key by signing in at https://www.electionsmcp.com.Auth (optional): header "Authorization: Bearer " or "x-electionsmcp-key: ". No key = a read/simulate sandbox; a key saves to the durable tier.
MCP endpoint (Legacy SSE)
https://www.electionsmcp.com/sseWhat you can do with it
- Build presidential or primary election scenarios with custom vote-share and turnout assumptions
- Aggregate precinct-level data and render maps for supported geography
- Compare candidate paths and versioned scenario outcomes
- Coordinate campaign tasks and add annotations to maps
Source and maintenance
Vendor evidenceRegistry 0.2.0
Protocol and capabilities
- Server
- electionsmcp 1.0.0
- MCP protocol
- 2025-06-18
- Tools
- 48 advertised
- Resources
- Not advertised
- Resource templates
- Not advertised
- Prompts
- 55 advertised
Server-advertised capabilities
{
"tools": {},
"prompts": {}
}Server-provided instructions
Untrusted server output shown for inspection. It is not Koskamo guidance and is excluded from knowledge search.
Tools
48 advertised
resolve_geography
Advertised read-only
Turn a place name or shorthand into its canonical geo_id — resolve natural-language or structured location input. Handles "CA-03"/"NC-4" (congressional districts), bare state names/abbreviations, "<County> County…
resolve_geography input schema
{
"type": "object",
"required": [
"query"
],
"properties": {
"year": {
"type": "integer",
"description": "Disambiguates post-redistricting boundaries; defaults to current cycle."
},
"query": {
"type": "string",
"description": "\"CA-03\", \"El Dorado County CA\", \"the 4th state senate district in California\", \"Pennsylvania\""
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}resolve_geography annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}resolve_candidate
Advertised read-only
WHO holds or runs for WHAT — turn a candidate/officeholder name into their seat + next race. Given a name (full, last-name, or a registry alias — "Lauren Boebert", "Boebert"), returns the person(s) who match with their…
resolve_candidate input schema
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "A candidate or officeholder name — full (\"Lauren Boebert\"), last-name (\"Boebert\"), or any registry alias. Matching folds free-typed names onto the canonical person."
},
"cycle": {
"type": "integer",
"description": "Optional — keep only matches whose next_race is in this cycle (e.g. 2026)."
},
"limit": {
"type": "integer",
"default": 8,
"maximum": 25,
"minimum": 1,
"description": "Max people to return when a name is ambiguous (default 8)."
},
"party": {
"type": "string",
"description": "Optional — keep only matches of this party (D/R/I), normalized by leading letter. For a stage/party-scoped picker."
},
"office": {
"type": "string",
"description": "Optional — keep only matches whose current OR next-race office matches (house, senate, governor, state_senate, state_assembly, …); the \"us_\" prefix is optional (\"house\" == \"us_house\")."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}resolve_candidate annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}search_candidates
Advertised read-only
BROWSE the canonical candidate registry WITHOUT a name — the nameless companion to resolve_candidate (which requires a name). Filter the registry of canonical people by party, office, and/or a name substring:…
search_candidates input schema
{
"type": "object",
"properties": {
"q": {
"type": "string",
"description": "Optional — case-insensitive substring on the candidate name or any alias (typeahead)."
},
"limit": {
"type": "integer",
"default": 50,
"maximum": 200,
"minimum": 1,
"description": "Max results (default 50). `total` reports the full match count; `truncated:true` when the list was trimmed."
},
"party": {
"type": "string",
"description": "Optional — only this party (D/R/I/L/G), normalized by leading letter."
},
"office": {
"type": "string",
"description": "Optional — match the registry office label. Keywords president / senate / house / governor are normalized; anything else is a case-insensitive substring on the label. The \"us_\" prefix is ignored."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}search_candidates annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}lookup_address
Advertised read-only
Resolve a US street address, ZIP, state, or U.S. House district and show workspace campaigns covering the result. Street addresses return a geocoded point and containing districts, with a precinct when coverage exists.…
lookup_address input schema
{
"type": "object",
"required": [
"address"
],
"properties": {
"address": {
"type": "string",
"description": "A full street address (\"123 Main St, Dallas, TX\"), a 5-digit ZIP, a district code (\"NC-4\", \"AK-AL\"), a state name/abbreviation, or a canonical state/House geography ID."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
},
"include_officials": {
"type": "boolean",
"default": true,
"description": "Attach the sitting officeholder for each resolved seat (from the committed legislator file)."
}
},
"additionalProperties": false
}lookup_address annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}list_contests
Advertised read-only
Discover contests for a geography and election cycle. Filter general, primary (dem_primary/rep_primary), or all stages; count describes the returned top-level rows. National presidential primaries are discoverable in…
list_contests input schema
{
"type": "object",
"required": [
"geo_id"
],
"properties": {
"cycle": {
"type": "integer",
"description": "Defaults to the next election year from today."
},
"stage": {
"enum": [
"primary",
"general",
"all"
],
"type": "string",
"default": "all",
"description": "primary selects the dem_primary and rep_primary variants; general excludes them; all returns both."
},
"geo_id": {
"type": "string",
"description": "\"us\" (national), a state as \"us-pa\" / postal \"PA\" / FIPS \"42\", or a district id — all accepted."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}list_contests output schema
{
"$id": "https://www.electionsmcp.com/schemas/mcp/list_contests/v1",
"type": "object",
"oneOf": [
{
"allOf": [
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"result_status": {
"enum": [
"error",
"unavailable"
]
}
},
"additionalProperties": true
}
]
},
{
"allOf": [
{
"not": {
"required": [
"error"
]
}
},
{
"type": "object",
"required": [],
"properties": {
"result_status": {
"enum": [
"success",
"empty",
"partial",
"unavailable"
]
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"cycle",
"geo_id",
"count",
"contests"
],
"properties": {
"count": {
"type": "integer",
"minimum": 0
},
"cycle": {
"type": "integer"
},
"stage": {
"enum": [
"general",
"primary",
"all"
]
},
"geo_id": {
"type": "string"
},
"contests": {
"type": "array",
"items": {
"type": "object",
"required": [
"contest_id",
"office",
"geo_id",
"level",
"stage"
],
"properties": {
"level": {
"type": "string"
},
"stage": {
"type": "string"
},
"geo_id": {
"type": "string"
},
"office": {
"type": "string"
},
"contest_id": {
"type": "string"
}
},
"additionalProperties": true
}
},
"not_on_ballot": {
"type": "array",
"items": {
"type": "object",
"required": [],
"properties": {},
"additionalProperties": true
}
},
"office_coverage": {
"type": "object",
"required": [],
"properties": {
"status": {
"enum": [
"complete",
"partial"
]
},
"offices_checked": {
"type": "array",
"items": {
"type": "string"
}
},
"unknown_offices": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": true
},
"unknown_offices": {
"type": "array",
"items": {
"type": "object",
"required": [],
"properties": {},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
]
}
],
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"contract_version",
"result_status",
"workspace_id",
"affected",
"delta",
"latency_ms",
"category"
],
"properties": {
"delta": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"affected": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"category": {
"type": "string"
},
"latency_ms": {
"type": "integer",
"minimum": 0
},
"workspace_id": {
"type": "string"
},
"result_status": {
"enum": [
"success",
"empty",
"partial",
"unavailable",
"error"
]
},
"contract_version": {
"const": 1
}
},
"description": "Versioned MCP result. success/empty describe completed reads; partial retains explicit missing coverage or another search page; unavailable describes a missing dependency. error/unavailable with an error code also set MCP isError. Existing provenance and context fields remain authoritative.",
"additionalProperties": true
}list_contests annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}election_calendar
Advertised read-only
The election planning calendar. National form ({cycle}) returns federal contests, governors and by_state office lists; state form ({state,cycle}) returns a four-year horizon. Other statewide executive offices use the…
election_calendar input schema
{
"type": "object",
"properties": {
"cycle": {
"type": "integer",
"description": "Defaults to the next election year from today."
},
"state": {
"type": "string",
"description": "Postal abbreviation (\"PA\") for the per-state 4-year horizon; omit for the national summary."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}election_calendar annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}set_performance
Advertised destructive
Set a candidate's vote share, such as the Democratic candidate to 54%, in one specific county, district, state, or precinct (the general-election override). Routes a county/state/district geo_id to a feature override…
set_performance input schema
{
"type": "object",
"required": [
"scenario_id",
"geo_id",
"shares"
],
"properties": {
"level": {
"enum": [
"custom",
"president",
"senate",
"governor",
"attorney_general",
"secretary_of_state",
"treasurer",
"house",
"state_senate",
"state_assembly"
],
"type": "string",
"description": "EM-136: explicit office for the override. A bare state geo (us-pa) otherwise defaults to senate — pass level to target president or governor instead (president is stored as a state-level aggregate that roll_up_race and get_view honor). For a district geo it must match the geo grain. tk_3c0569e9b02541: a COUNTY geo (us-me-county-23001) accepts any STATEWIDE office — level:\"senate\"/\"governor\"/exec stores the county edit in THAT race's store, folding into its state rollup with precinct > county > state > baseline precedence (default without level stays president). A PRECINCT geo (us-me-vtd-…) with level tags the edit's office so it folds into that race's statewide total (same tag set_precinct_pcts writes)."
},
"geo_id": {
"type": "string"
},
"margin": {
"type": "number",
"description": "Shorthand for two-candidate D−R margin in points; sets D/R shares around 50."
},
"shares": {
"type": "object",
"description": "candidate_id → share. Accepts 0–1 or 0–100.",
"additionalProperties": {
"type": "number"
}
},
"turnout": {
"type": "number",
"description": "0–1 expected turnout (stored as metadata on precinct overrides)."
},
"rebalance": {
"enum": [
"undecided",
"proportional"
],
"type": "string",
"default": "undecided"
},
"scenario_id": {
"type": "string",
"description": "The simulation_id (scenario_id alias until the scenario model lands)."
},
"total_votes": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Explicit vote volume for a custom campaign city or reviewed precinct. Use level:\"custom\" and geo_id from get_campaign_vote_data. A precinct requires its own total; source-election turnout is never copied automatically."
},
"simulation_id": {
"type": "string"
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
},
"expected_version": {
"type": "string",
"description": "Optional optimistic-concurrency token: the scenario updated_at you last read. If the scenario changed since, the write is refused with version_conflict + the current token instead of overwriting concurrent edits."
}
},
"additionalProperties": false
}set_performance annotations
{
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": true
}target_precincts
Advertised read-only
Return structured precinct model rows: precinct_id, name, county, county_fips, baseline_share, modeled_share, ballots_est, overridden, and gap_to_goal. The response does not include demographic columns or demographic…
target_precincts input schema
{
"type": "object",
"required": [
"scenario_id"
],
"properties": {
"limit": {
"type": "integer",
"default": 500,
"maximum": 10000,
"minimum": 1
},
"filter": {
"type": "object",
"description": "Precinct property → condition map within the requested geography. Properties: external_id, GEOID, name, state, county, county_fips, shape_id, votes_dem, votes_rep, votes_total, pct_dem_lead, official_boundary, lat, lng, population, mhi, median_home, pct_bachelors, pct_foreign_born, unemp_pct, median_age, owner_occ_pct, modeled_margin_pp, modeled_pct_dem_lead, flipped, overridden. A bare scalar means exact equality; an array means membership. Object operators: gt, gte, lt, lte, in, not_in. Comparisons take finite numbers; in/not_in take arrays of scalars. Conditions are ANDed. pct_dem_lead is a baseline two-party share lead in -1..1. Scenario-scoped target_precincts, aggregate_precincts and apply_swing_to_query also accept modeled_margin_pp (D minus R over ALL modeled ballots, percentage points), modeled_pct_dem_lead (same margin / 100), modeled_share.CANDIDATE_ID (0..1 all-ballot share), flipped (winner differs from baseline, including ties) and overridden (saved precinct or county share override). These require a supported general statewide scenario with an allocated local model; missing shares never match numeric comparisons. Example: {external_id:{in:[\"48009-11\"]},votes_total:{gte:500}}. Unknown properties/operators and malformed conditions are rejected before matching or writing."
},
"geo_id": {
"type": "string",
"description": "District or state geography — accepts the resolve_geography slug (\"us-pa\"), postal (\"PA\"), or FIPS (\"42\") (EM-056). Defaults to the simulation's race_scope geography."
},
"margin": {
"type": "number",
"default": 1,
"description": "plurality: win by at least this many votes."
},
"offset": {
"type": "integer",
"default": 0,
"minimum": 0,
"description": "Page start; pass next.offset from the prior result with the same scope and filters."
},
"context": {
"type": "string",
"description": "Free-text constraints, echoed back (e.g. \"field ops in Orange and Durham only\")."
},
"goal_mode": {
"enum": [
"plurality",
"majority",
"share"
],
"type": "string",
"default": "plurality",
"description": "plurality = beat the leading opponent (default); majority = 50.01% share; share = explicit target_pct."
},
"target_pct": {
"type": "number",
"default": 0.5001
},
"scenario_id": {
"type": "string",
"description": "The scenario/simulation handle (EM-056: simulation_id is accepted as an alias)."
},
"candidate_id": {
"type": "string",
"default": "D"
},
"rolloff_rate": {
"type": "number",
"maximum": 1.5,
"minimum": 0.05,
"description": "Explicit roll-off rate (see compute_vote_goal)."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}target_precincts annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}create_scenario
Create a new Scenario (a modeled path) — optionally inside a Race and seeded from a contest_id or an existing scenario (import_from). Seeds an immutable baseline version (v1). Returns scenario_id + version_id. (A…
create_scenario input schema
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"race_id": {
"type": "string",
"description": "Optional; the Race this scenario belongs to."
},
"contest_id": {
"type": "string",
"description": "Optional; sets the scenario's race_scope from a canonical contest_id."
},
"baseline_id": {
"type": "string",
"description": "Optional explicit source pin. Only 2024_president_mixed_grain is currently selectable. Known county sources return baseline_selection_unavailable; unreconciled sources return baseline_not_model_eligible; unknown IDs return unknown_baseline. No source is silently substituted."
},
"campaign_id": {
"type": "string",
"description": "Custom campaign to model inside its exact attached city boundary."
},
"import_from": {
"type": "string",
"description": "Optional; copy overrides+candidates from an existing scenario_id."
},
"idempotency_key": {
"type": "string",
"maxLength": 160,
"minLength": 1,
"description": "Optional workspace-scoped retry key for listed races; required for custom campaign models. Identical retries return the same scenario and baseline version. Reusing a key with different creation inputs returns idempotency_conflict."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
},
"boundary_version": {
"type": "string"
},
"expected_campaign_revision": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": false
}create_scenario annotations
{
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": false,
"destructiveHint": false
}get_view
Advertised read-only
Read the exact map/view state the application renders for a canonical scenario: headline totals, selected geography, modeled feature colors, annotations, primary-calendar playhead, candidate roster, presence, and a…
get_view input schema
{
"type": "object",
"required": [
"simulation_id"
],
"properties": {
"view": {
"enum": [
"result",
"difference"
],
"type": "string",
"description": "difference uses compare_simulation_id as B and simulation_id as A; returns the zero-centered B-minus-A color scale and exact county/precinct rows."
},
"cycle": {
"type": "integer",
"maximum": 2040,
"minimum": 2024
},
"grain": {
"enum": [
"city",
"county",
"precinct"
],
"type": "string",
"description": "With a state scoped, the grain of the local features returned: \"county\" (default) or \"precinct\". Applies to a statewide-level race (senate/governor/exec — its own overrides) AND to a PRIMARY sim scoped to a state (its per-county/precinct share-leader map from primary.feature_shares — mirroring render_view; a state-scoped primary defaults to county instead of the national delegate calendar). Ignored without a state."
},
"level": {
"enum": [
"custom",
"president",
"senate",
"house",
"governor",
"attorney_general",
"secretary_of_state",
"treasurer",
"state_senate",
"state_assembly"
],
"type": "string",
"description": "Which map the view renders. Default president (or whatever set_view last scoped). house = HOUSE CONTROL (per-state delegation winners + the 218 banner); state_senate/state_assembly = one state's chamber (state required)."
},
"state": {
"type": "string",
"description": "Optional postal code or 2-digit FIPS — scope the map to one state. president → its county breakdown; senate/governor/exec → that RACE's local county (default) or precinct features from its own overrides (each with modeled margin, baseline_margin, and a basis label: direct_override | county_override | state_override_uniform | presidential_proxy / race_returns) — never the presidential county baseline relabeled. On a PRIMARY sim, scoping to a state returns that state's per-COUNTY (default; grain:\"precinct\" for finer) share-leader features from primary.feature_shares — modeled counties filled by the county primary WINNER's candidate color, unmodeled grey — instead of the national delegate calendar (which is the unscoped view)."
},
"version_a": {
"type": "string",
"description": "Difference comparison: exact saved version of A. Omit only when its latest version matches the live model."
},
"version_b": {
"type": "string",
"description": "Difference comparison: exact saved version of B. Omit only when its latest version matches the live model."
},
"version_id": {
"type": "string",
"description": "Exact saved version for a custom city model."
},
"campaign_id_a": {
"type": "string",
"description": "Optional campaign custody for A when the model belongs to multiple readable campaigns. Does not grant access."
},
"campaign_id_b": {
"type": "string",
"description": "Optional campaign custody for B when the model belongs to multiple readable campaigns. Does not grant access."
},
"simulation_id": {
"type": "string"
},
"expected_hash_a": {
"type": "string",
"description": "Optional expected immutable version hash for A; mismatches refuse."
},
"expected_hash_b": {
"type": "string",
"description": "Optional expected immutable version hash for B; mismatches refuse."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
},
"difference_scale_pp": {
"type": "number",
"maximum": 200,
"description": "Difference-only symmetric color extent: legend runs from negative this value through zero to positive this value. Omit to fit the largest absolute delta; out-of-scale values are disclosed as clamped.",
"exclusiveMinimum": 0
},
"compare_simulation_id": {
"type": "string",
"description": "Compare B against simulation_id (A), using D-minus-R margin(B) minus margin(A). Requires one explicit state and county/precinct grain; both saved general-election models must share office/cycle/electorate and be readable."
},
"expected_version_hash": {
"type": "string"
}
},
"additionalProperties": false
}get_view annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}render_view
Advertised read-only
A headless server-rendered IMAGE of the map — the rendered view a viewer sees, as SVG or PNG, WITHOUT a browser (tk_0b6d3501 P2). For a scenario + level (president | senate | house | governor | the execs) it draws the…
render_view input schema
{
"type": "object",
"required": [
"simulation_id"
],
"properties": {
"asof": {
"type": [
"integer",
"null"
],
"description": "PRIMARY sims — render the delegate banner/standings AS OF this calendar checkpoint (contests counted; the same asof roll_up_primary / render_chart take). Omit to honor the scenario's STORED playhead (set_primary_asof) so the served image matches the viewer's scoreboard; null = the full projected calendar. The county/precinct share-leader FILLS are the scenario's stored shares and do NOT move with asof — only the delegate banner does. The primary mode + party are auto-detected from the sim's mode (dem_primary_2028 / rep_primary_2028); there is no mode/party arg. Ignored for general-election renders (the response echoes the effective asof when it applied)."
},
"view": {
"enum": [
"result",
"swing",
"difference"
],
"type": "string",
"description": "\"result\" (default) = the outcome map; \"swing\" = colour by margin CHANGE vs the baseline (where the scenario MOVES the map). \"difference\" = margin(B)-margin(A), requires compare_simulation_id and one explicit state; supports saved general-election county/precinct maps, with a zero-centered in-frame legend. It refuses unallocated whole-race edits. Result/swing work at NATIONAL scope (president: every state by its swing), STATE scope (president county map AND the statewide-race local county/precinct maps), and CUSTOM maps."
},
"grain": {
"enum": [
"county",
"precinct",
"house",
"state_senate",
"state_assembly"
],
"type": "string",
"description": "When scoped to ONE state (state/geo_id/feature_id), the geographic grain to render: \"county\" (default) per-county; \"precinct\" per-precinct (finest, within-county) — both work at president level AND at the statewide-race levels (senate/governor/exec, which render that race's own overrides/fold, tk_3c0569e9b02541); or a DISTRICT layer (president level only) — \"house\" = U.S. congressional districts (us-cd119), \"state_senate\" = state-senate districts (us-sldu), \"state_assembly\" = state-house districts (us-sldl). Districts are fetched on-demand and filled by their vote baseline (House: county→CD presidential aggregation; state-leg: RoutPoint 2024 returns where covered, else presidential-lean) + the scenario's district overrides (set_performance at that level). A few states lack a layer and fall back to county."
},
"level": {
"enum": [
"president",
"senate",
"house",
"governor",
"attorney_general",
"secretary_of_state",
"treasurer"
],
"type": "string",
"description": "Which map to render. Default president. house = HOUSE CONTROL: states shaded by delegation majority, D/R seat tally, 218 banner (for one state's district map use grain:\"house\" with a state scope instead)."
},
"share": {
"type": "boolean",
"description": "PUBLISH this map to a hostable URL: mints a share token and returns share.hosted_image_url / hosted_svg_url + a public page_url (/f/<token>) that resolve for ANYONE — cross-workspace, embeddable in an <img> or iframe. Default false (URLs are owner/public-scoped only). Anyone with the link sees the map; revoke with revoke_share(token)."
},
"state": {
"type": "string",
"description": "Optional — scope the image to a state (postal \"NC\" or 2-digit FIPS). president → that state's per-county choropleth; senate/governor/exec → that RACE's LOCAL county map from its own overrides (5-digit county edits + its state override as uniform swing) over the labeled inherited-proxy baseline — never a presidential map substituted (tk_3c0569e9b02541). Other levels ring the state on the national map."
},
"theme": {
"type": "string",
"description": "MAP THEME preset for the rendered image (list_map_themes: control | analyst | field | civic | accessible | broadcast | terrain) — the SAME token resolution the live wall uses, so a civic-themed report map and the analyst on-screen map disagree only in paint, never in data. Omit = the classic dark card."
},
"title": {
"type": "string",
"description": "CUSTOM MAP: a title for the card (e.g. \"Rust Belt swing\"). Defaults to the state list (or the region group / region name)."
},
"format": {
"enum": [
"svg",
"png"
],
"type": "string",
"description": "Image format. Default svg (png needs the resvg renderer on the host; degrades to svg if absent)."
},
"geo_id": {
"type": "string",
"description": "Optional — a geo slug like \"us-nc\" to scope to that state."
},
"layers": {
"type": "object",
"properties": {
"highlights": {
"type": "boolean"
}
},
"description": "Draw saved highlight annotations on matching visible geography. Omit to honor set_view layers.highlights (default true); false hides them for this export only. Pins and notes are not rendered.",
"additionalProperties": false
},
"region": {
"type": "string",
"description": "CUSTOM MAP — with region_group, render exactly ONE region in the group (its slug)."
},
"states": {
"type": "array",
"items": {
"type": "string"
},
"description": "CUSTOM MAP (president): a list of states (postal \"PA\" or 2-digit FIPS) → a cropped county choropleth of just those states' counties, in their real relative positions, zoomed to the region. Combine with features[]. e.g. [\"PA\",\"OH\",\"MI\"] for a Rust Belt map."
},
"features": {
"type": "array",
"items": {
"type": "string"
},
"description": "CUSTOM MAP (president): an explicit list of geo_ids to include — county FIPS (5-digit), state FIPS (2-digit), or \"us-xx\". Hand-pick any counties across states; the map crops to exactly them. Combine with states[]."
},
"version_a": {
"type": "string",
"description": "Difference comparison: exact saved version of A. Omit only when its latest version matches the live model."
},
"version_b": {
"type": "string",
"description": "Difference comparison: exact saved version of B. Omit only when its latest version matches the live model."
},
"feature_id": {
"type": "string",
"description": "Optional — a state fips (37) or county/precinct id (37xxx) to scope to its state."
},
"region_group": {
"type": "string",
"description": "CUSTOM MAP — a saved workspace map region-group slug. Expands to its member counties or states; add region to render one named region. Ignored if states[] or features[] are passed."
},
"campaign_id_a": {
"type": "string",
"description": "Optional campaign custody for A when the model belongs to multiple readable campaigns. Does not grant access."
},
"campaign_id_b": {
"type": "string",
"description": "Optional campaign custody for B when the model belongs to multiple readable campaigns. Does not grant access."
},
"simulation_id": {
"type": "string"
},
"share_ttl_days": {
"type": "number",
"description": "Days the shared URL stays live (default 90, max 365). Only with share:true."
},
"expected_hash_a": {
"type": "string",
"description": "Optional expected immutable version hash for A; mismatches refuse."
},
"expected_hash_b": {
"type": "string",
"description": "Optional expected immutable version hash for B; mismatches refuse."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
},
"comparison_layout": {
"enum": [
"difference",
"triptych"
],
"type": "string",
"description": "Difference-only 1200x630 card: one B-minus-A map (default), or the same-grain A | B | B-minus-A maps with explicit legends."
},
"difference_scale_pp": {
"type": "number",
"maximum": 200,
"description": "Difference-only symmetric color extent: legend runs from negative this value through zero to positive this value. Omit to fit the largest absolute delta; out-of-scale values are disclosed as clamped.",
"exclusiveMinimum": 0
},
"compare_simulation_id": {
"type": "string",
"description": "Compare B against simulation_id (A), using D-minus-R margin(B) minus margin(A). Requires one explicit state and county/precinct grain; both saved general-election models must share office/cycle/electorate and be readable."
}
},
"additionalProperties": false
}render_view annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}render_chart
Advertised read-only
share_comparison compares candidate shares for two saved versions of one model or two same-contest statewide general-election models. Returns canonical integer candidate votes, all-ballot shares, D-minus-R margins,…
render_chart input schema
{
"type": "object",
"anyOf": [
{
"required": [
"simulation_id"
]
},
{
"required": [
"simulation_id_a"
],
"properties": {
"type": {
"const": "share_comparison"
}
}
}
],
"required": [
"type"
],
"properties": {
"asof": {
"type": [
"integer",
"null"
],
"description": "For the primary charts — evaluate the race at this calendar checkpoint (contests counted), the same asof roll_up_primary takes: standings/clinch totals, the momentum timeline's end, and the calendar strip's counted set all stop there. Omit to use the scenario's STORED playhead (set_primary_asof) when one is set, else the full projected calendar. The response echoes the effective asof + contests_counted so a caption like \"Through FL\" can be verified against the data (tk_2840156e3f1d8b)."
},
"type": {
"enum": [
"delegate_standings",
"clinch_dial",
"delegate_momentum",
"calendar_strip",
"ranking_board",
"swing_bars",
"chamber_control",
"seat_hemicycle",
"decisive_seats",
"share_comparison"
],
"type": "string",
"description": "Which widget. share_comparison = saved candidate shares before/after, with paired version anchors and one state. Primary: delegate_standings (bars+clinch), clinch_dial (gauge), delegate_momentum (lines), calendar_strip (calendar grid), ranking_board (portrait tiles ranked by delegates + per-candidate clinch state/date; response carries the rows as data). General: swing_bars (state Δ vs 2024), chamber_control (down-ballot D/R scorecard), seat_hemicycle (the 1200×630 parliament-arch CONTROL CARD — every seat a dot, majority tick, big D/R counts), decisive_seats (the 1200×630 closest-races board with margin-band ratings + FLIP tags)."
},
"cycle": {
"type": "integer",
"description": "Election cycle for seat_hemicycle / decisive_seats (defaults to the sim's cycle, else 2026) — drives the Senate class + governor calendar."
},
"level": {
"enum": [
"president",
"senate",
"governor",
"attorney_general",
"secretary_of_state",
"treasurer"
],
"type": "string",
"description": "share_comparison only: statewide office; defaults to the saved scope. Both versions must match office, state, cycle and general-election stage."
},
"party": {
"enum": [
"d",
"r"
],
"type": "string",
"description": "For the primary charts — which party's race (defaults to the sim's primary mode)."
},
"share": {
"type": "boolean",
"description": "PUBLISH to a hostable URL: mints a share token and returns share.hosted_image_url / hosted_svg_url that resolve for ANYONE (cross-workspace, embeddable). Default false. Revoke with revoke_share(token)."
},
"state": {
"type": "string",
"description": "State postal or FIPS. Required for share_comparison and state-leg seat_hemicycle/decisive_seats."
},
"style": {
"type": "object",
"properties": {
"ink": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$",
"description": "Main text color, as six-digit hex."
},
"font": {
"enum": [
"sans",
"serif",
"mono"
],
"type": "string",
"description": "Portable font family. Custom fonts, URLs, and CSS are not accepted."
},
"accent": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$",
"description": "Heading and threshold color, as six-digit hex. Candidate colors stay with the scenario roster."
},
"background": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$",
"description": "Canvas color, as six-digit hex."
}
},
"description": "Optional brand overrides for the supported themed charts. Does not remove attribution or change candidate colors or model data.",
"additionalProperties": false
},
"theme": {
"enum": [
"control",
"analyst",
"field",
"civic",
"accessible",
"broadcast",
"terrain",
"print"
],
"type": "string",
"description": "Chart audience palette, using the map-theme registry. Supported by primary charts, swing_bars and chamber_control. Default control."
},
"title": {
"type": "string",
"description": "Optional eyebrow/title for the chart."
},
"clinch": {
"type": "boolean",
"description": "ranking_board only — show each candidate's clinch line on the tiles (CLINCHES <state> · <date>, or how many delegates short). Default true; pass false for a name+delegates-only board. The response's rows[] carry the clinch data either way."
},
"format": {
"enum": [
"svg",
"png"
],
"type": "string",
"description": "Image format. Default svg (png needs the resvg renderer; degrades to svg if absent)."
},
"office": {
"enum": [
"house",
"senate",
"governor",
"state_senate",
"state_assembly"
],
"type": "string",
"description": "For seat_hemicycle / decisive_seats — which chamber (default house). state_senate/state_assembly also need state."
},
"version_a": {
"type": "string",
"description": "Difference comparison: exact saved version of A. Omit only when its latest version matches the live model."
},
"version_b": {
"type": "string",
"description": "Difference comparison: exact saved version of B. Omit only when its latest version matches the live model."
},
"overlay_race": {
"type": "object",
"properties": {
"state": {
"type": "string"
},
"office": {
"type": "string"
},
"district": {
"type": "string"
}
},
"description": "The single race to swap in from overlay_from_simulation_id: {office, state, district}. office must match the card's chamber; statewide offices need only state; house takes the district GEOID (\"0604\") or the bare number with its state; state chambers take the district external_id.",
"additionalProperties": false
},
"campaign_id_a": {
"type": "string",
"description": "Optional campaign custody for A when the model belongs to multiple readable campaigns. Does not grant access."
},
"campaign_id_b": {
"type": "string",
"description": "Optional campaign custody for B when the model belongs to multiple readable campaigns. Does not grant access."
},
"simulation_id": {
"type": "string",
"description": "Scenario to render; for share_comparison this is A, or the single model with version_a/version_b."
},
"highlight_race": {
"type": "object",
"properties": {
"state": {
"type": "string"
},
"office": {
"type": "string"
},
"district": {
"type": "string"
}
},
"description": "Mark one race on the card (same shape as overlay_race): its dot wears an amber ring on seat_hemicycle, and decisive_seats always includes it on the board with its true closest-races rank.",
"additionalProperties": false
},
"share_ttl_days": {
"type": "number",
"description": "Days the shared URL stays live (default 90, max 365). Only with share:true."
},
"expected_hash_a": {
"type": "string",
"description": "Optional expected immutable version hash for A; mismatches refuse."
},
"expected_hash_b": {
"type": "string",
"description": "Optional expected immutable version hash for B; mismatches refuse."
},
"simulation_id_a": {
"type": "string",
"description": "share_comparison only: A model, alternative to simulation_id. Conflicting aliases refuse."
},
"simulation_id_b": {
"type": "string",
"description": "share_comparison only: B model in the same contest. Omit for two explicit versions of A."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
},
"compare_simulation_id": {
"type": "string",
"description": "share_comparison only: alias for simulation_id_b."
},
"context_simulation_id": {
"type": "string",
"description": "seat_hemicycle / decisive_seats only — compute the WHOLE chamber rollup from THIS scenario (a linked national/statewide view's scenario) instead of simulation_id. Pair with overlay_from_simulation_id + overlay_race to swap exactly one race's result in from a campaign's scenario: one seat changes hands, the counts move by that seat, nothing else. The two scenarios must model the same cycle and be general-election models — a disagreement is a typed refusal (context_cycle_mismatch / context_mode_mismatch), never a silent mix."
},
"overlay_from_simulation_id": {
"type": "string",
"description": "seat_hemicycle / decisive_seats only — the scenario that supplies the ONE overlaid race's modeled result. Travels with overlay_race; passing one without the other is refused (overlay_incomplete)."
}
},
"additionalProperties": false
}render_chart annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}set_view
Advertised destructive
Set the active scenario view and selected map context: race stage, calendar playhead, geography grain, result source, selected feature, camera, map theme, and rail. The same persisted view state and deep link are used…
set_view input schema
{
"type": "object",
"required": [
"simulation_id"
],
"properties": {
"asof": {
"type": [
"integer",
"null"
],
"minimum": 0,
"description": "The primary calendar playhead — contests counted in the race-so-far (the number set_primary_asof takes). null = full calendar. Writes sim.primary.asof (the store the viewer's scoreboard/map run at), so this one DOES change the sim document. Primary sims only (a general sim answers with an asof_ignored warning)."
},
"rail": {
"enum": [
"select",
"notes",
"strategy",
"none"
],
"type": "string",
"description": "Which right-rail panel the viewer should have open."
},
"zoom": {
"type": "number",
"maximum": 20,
"minimum": 0,
"description": "Optional camera zoom; omit to fit the geo's bounds."
},
"cycle": {
"type": "integer",
"maximum": 2040,
"minimum": 2024
},
"level": {
"enum": [
"custom",
"president",
"senate",
"governor",
"attorney_general",
"secretary_of_state",
"treasurer",
"house",
"state_senate",
"state_assembly"
],
"type": "string",
"description": "The map/level the view should show."
},
"stage": {
"enum": [
"general",
"d_primary",
"r_primary",
"top_two"
],
"type": "string",
"description": "The race stage the viewer should see. Persisted on view_state + broadcast live; a primary-mode sim's own mode remains the identity truth (this is the VIEW)."
},
"state": {
"type": "string",
"description": "Postal code or 2-digit FIPS to scope to (pass empty string to clear to the national view)."
},
"layers": {
"type": "object",
"description": "View toggles such as precincts/highlights plus the canonical \"actuals:pres_2024\" baseline layer.",
"additionalProperties": {
"type": [
"boolean",
"null"
]
}
},
"source": {
"enum": [
"auto",
"state",
"county",
"precinct",
"flat"
],
"type": "string",
"description": "The per-state Outcome SOURCE control (which grain governs the shown outcome). Stored on view_state; the sim's own grain_pref pin stays set_primary_grain_pref's job."
},
"contest": {
"type": "string",
"description": "Playhead targeting by contest instead of a number: a state postal code (\"FL\"), 2-digit FIPS, or full name — the playhead jumps to INCLUDE that contest (same semantics as set_primary_asof)."
},
"map_grain": {
"enum": [
"states",
"counties",
"precincts",
"state",
"county",
"precinct"
],
"type": "string",
"description": "The Map View grain toggle: states | counties | precincts (singular accepted, stored plural)."
},
"map_theme": {
"type": "string",
"description": "Pin a MAP THEME audience preset on this view (list_map_themes has the registry: control | analyst | field | civic | accessible | broadcast | terrain). The open viewer restyles live; \"none\" clears the pin. Colors only — data, winners and margins never change."
},
"selected_geo": {
"type": "object",
"required": [
"feature_id"
],
"properties": {
"level": {
"enum": [
"custom",
"state",
"county",
"district",
"precinct"
],
"type": "string"
},
"feature_id": {
"type": "string"
}
},
"description": "The selected feature on the map ({level, feature_id} — e.g. {level:\"county\", feature_id:\"12086\"} for Miami-Dade). Pass feature_id:\"\" to clear the selection.",
"additionalProperties": false
},
"camera_geo_id": {
"type": "string",
"description": "Optional geo to frame the camera on (defaults to the scoped state). 2-digit state / 5-digit county / district GEOID / precinct id."
},
"contest_index": {
"type": "integer",
"minimum": 1,
"description": "Playhead targeting by 1-based calendar ordinal (list_primary_calendar order)."
},
"simulation_id": {
"type": "string"
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}set_view annotations
{
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": true
}get_scenario
Advertised read-only
A Scenario at its latest version (or a specified version_id): metadata (incl. latest_hash) + the version's top_line (margin / EC / viability) + its content hash/prev_hash. EM-119: pass a version_id (or…
get_scenario input schema
{
"type": "object",
"required": [
"scenario_id"
],
"properties": {
"version_id": {
"type": "string",
"description": "Optional; defaults to the latest version. When set, the response includes the full per-precinct `state` for that version."
},
"scenario_id": {
"type": "string"
},
"include_state": {
"type": "boolean",
"description": "Include the full per-precinct `state` even for the latest version (for redrawing the map)."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
},
"expected_version_hash": {
"type": "string",
"maxLength": 160,
"minLength": 1,
"description": "Optional exact content hash from list_scenario_versions. Requires version_id; a mismatch is refused rather than returning a different saved model."
}
},
"additionalProperties": false
}get_scenario output schema
{
"$id": "https://www.electionsmcp.com/schemas/mcp/get_scenario/v1",
"type": "object",
"oneOf": [
{
"allOf": [
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"result_status": {
"enum": [
"error",
"unavailable"
]
}
},
"additionalProperties": true
}
]
},
{
"allOf": [
{
"not": {
"required": [
"error"
]
}
},
{
"type": "object",
"required": [],
"properties": {
"result_status": {
"enum": [
"success",
"empty",
"partial",
"unavailable"
]
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"scenario",
"version",
"context"
],
"properties": {
"state": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"context": {
"type": "object",
"required": [],
"properties": {},
"additionalProperties": true
},
"version": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"scenario": {
"type": "object",
"required": [
"scenario_id",
"version_count"
],
"properties": {
"name": {
"type": "string"
},
"contest_id": {
"type": [
"string",
"null"
]
},
"race_scope": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"scenario_id": {
"type": "string"
},
"version_count": {
"type": "integer",
"minimum": 0
},
"latest_version": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"provenance": {
"type": "object",
"required": [],
"properties": {},
"additionalProperties": true
}
},
"additionalProperties": true
}
]
}
],
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"contract_version",
"result_status",
"workspace_id",
"affected",
"delta",
"latency_ms",
"category"
],
"properties": {
"delta": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"affected": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"category": {
"type": "string"
},
"latency_ms": {
"type": "integer",
"minimum": 0
},
"workspace_id": {
"type": "string"
},
"result_status": {
"enum": [
"success",
"empty",
"partial",
"unavailable",
"error"
]
},
"contract_version": {
"const": 1
}
},
"description": "Versioned MCP result. success/empty describe completed reads; partial retains explicit missing coverage or another search page; unavailable describes a missing dependency. error/unavailable with an error code also set MCP isError. Existing provenance and context fields remain authoritative.",
"additionalProperties": true
}get_scenario annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}commit_version
Advertised destructive
Save the scenario's current state as a new immutable, hash-stamped version in the append-only chain. Records a diff vs the parent version and the recomputed top_line, and returns a content `hash` (+ `prev_hash`…
commit_version input schema
{
"type": "object",
"required": [
"scenario_id"
],
"properties": {
"title": {
"type": "string",
"description": "Optional SHORT card title (<=80 chars), distinct from the longer summary — what the VERSIONS card shows as its heading, e.g. \"Orange County flip\"."
},
"summary": {
"type": "string",
"description": "Human-readable note on what changed, e.g. \"Flipped Orange County to D+40\"."
},
"insight_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional — insight ids (ins_…) this version explains. Validated against the sim's insights; unknown ids are reported in `unlinked` and dropped."
},
"scenario_id": {
"type": "string"
},
"include_diff": {
"type": "boolean",
"default": false,
"description": "Inline the full before/after diff in the response (can be very large). Default false: return compact diff_stats only; fetch the full diff via diff_versions when needed."
},
"annotation_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional — annotation ids (pins/highlights/notes on this sim) this version explains. Validated against the sim's annotations; unknown ids are reported in `unlinked` and dropped, never invented."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}commit_version annotations
{
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": false,
"destructiveHint": true
}list_scenarios
Advertised read-only
Page saved scenarios/simulations in this workspace by updated_at descending and scenario_id ascending, without version blobs. Returns scenario_id, name, level, cycle, contest_id, race_id, tags, durable_id, published…
list_scenarios input schema
{
"type": "object",
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Return only scenarios carrying any of these tags."
},
"limit": {
"type": "integer",
"default": 100,
"maximum": 500,
"minimum": 1
},
"offset": {
"type": "integer",
"default": 0,
"minimum": 0,
"description": "Use previous next_offset with unchanged tags and limit. Ordered by updated_at descending, scenario_id ascending. Restart at 0 after inventory changes."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}list_scenarios annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}diff_versions
Advertised read-only
Structured diff between two immutable versions. Raw before/after remain stored override patches (null means no saved override). Precinct cells also include effective_before/effective_after shares with their…
diff_versions input schema
{
"type": "object",
"required": [
"scenario_id",
"version_a",
"version_b"
],
"properties": {
"limit": {
"type": "integer",
"default": 100,
"maximum": 500,
"minimum": 1,
"description": "Maximum changed precinct cells in this page. Summary counts cover the full version pair."
},
"offset": {
"type": "integer",
"default": 0,
"minimum": 0,
"description": "Use precinct_page.next_offset to continue in stable precinct-id order."
},
"version_a": {
"type": "string"
},
"version_b": {
"type": "string"
},
"scenario_id": {
"type": "string"
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}diff_versions annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}get_early_voting_turnout
Advertised read-only
Read early voting, absentee/mail, election-day, and provisional vote-method breakdowns alongside registered-voter, ballots-cast, and undervote/overvote turnout statistics by race and candidate from RoutPoint v2…
get_early_voting_turnout input schema
{
"type": "object",
"required": [
"state"
],
"properties": {
"state": {
"type": "string",
"description": "Two-letter state postal code (e.g. \"TX\", \"NC\", \"GA\", \"FL\", \"PA\", \"MI\", \"AZ\")."
},
"office": {
"type": "string",
"description": "Optional office substring filter (e.g. \"U.S. Senate\", \"Governor\")."
},
"district": {
"type": "string",
"description": "Optional district code filter for legislative or congressional races (e.g. \"10\", \"11\")."
},
"source_id": {
"type": "string",
"description": "Optional 64-character SHA-256 source identifier for a specific county/state return file."
},
"county_fips": {
"type": "string",
"description": "Optional 5-digit county FIPS code (e.g. \"48081\", \"37021\") to scope returns and turnout to one county."
},
"office_level": {
"enum": [
"president",
"us_senate",
"us_house",
"governor",
"lt_governor",
"attorney_general",
"secretary_of_state",
"treasurer",
"state_senate",
"state_assembly",
"other"
],
"type": "string",
"description": "Optional canonical office level filter."
},
"election_date": {
"type": "string",
"description": "Optional election date in YYYY-MM-DD format (e.g. \"2024-11-05\", \"2026-03-03\", \"2026-08-18\"). Defaults to the most recent covered election for the state."
},
"election_type": {
"enum": [
"general",
"primary",
"runoff",
"special",
"municipal",
"recall"
],
"type": "string",
"description": "Optional election stage filter."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
},
"include_precincts": {
"type": "boolean",
"description": "When true, include per-precinct early voting, mail, election-day, and turnout breakdowns inside each race."
}
},
"additionalProperties": false
}get_early_voting_turnout annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}get_county_voter_turnout_and_registration
Advertised read-only
Read county voter registration, party registration (DEM/REP/UNA/Other), voting-age population, 2024/2022/2020/2026 ballots cast and turnout percentages, 2020-to-2024 partisan swing, and competitiveness tiers across…
get_county_voter_turnout_and_registration input schema
{
"type": "object",
"properties": {
"sort": {
"enum": [
"ballots_cast_2024",
"turnout_2024_pct",
"registered_voters",
"partisan_swing_2020_to_2024_pct",
"margin_2024_pct",
"ballots_cast_2026"
],
"type": "string",
"description": "Sort order (default ballots_cast_2024)."
},
"tier": {
"enum": [
"tossup_battleground",
"lean_dem",
"lean_rep",
"safe_dem",
"safe_rep"
],
"type": "string",
"description": "Optional competitiveness tier filter."
},
"limit": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Maximum counties to return (default 100, max 500)."
},
"state": {
"type": "string",
"description": "Optional two-letter state code (e.g. \"PA\", \"GA\", \"NC\", \"MI\", \"WI\", \"AZ\", \"NV\", \"TX\")."
},
"offset": {
"type": "integer",
"minimum": 0,
"description": "Pagination offset (default 0)."
},
"county_fips": {
"type": "string",
"description": "Optional 5-digit county FIPS code (e.g. \"37183\" for Wake NC, \"04013\" for Maricopa AZ)."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}get_county_voter_turnout_and_registration annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}get_state_historical_turnout
Advertised read-only
Read 50-year statewide prior-cycle turnout and vote totals (1976 through 2026 across all 50 states and DC): ballots cast, registered voters, voting-age population, turnout percentage, DEM/REP vote shares, margin, and…
get_state_historical_turnout input schema
{
"type": "object",
"properties": {
"year": {
"type": "integer",
"maximum": 2028,
"minimum": 1976,
"description": "Optional election year filter (1976 through 2026)."
},
"limit": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Maximum rows to return (default 100, max 500)."
},
"state": {
"type": "string",
"description": "Optional two-letter state code (e.g. \"PA\", \"GA\", \"MI\", \"WI\", \"CA\", \"TX\")."
},
"offset": {
"type": "integer",
"minimum": 0,
"description": "Pagination offset (default 0)."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}get_state_historical_turnout annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}get_live_early_vote_returns
Advertised read-only
Read live 2026-11-03 General Election pre-election mail ballot requests, mail ballots returned, early in-person ballots, and ballot composition by voter registration party (DEM/REP/UNA/Other) from continuously…
get_live_early_vote_returns input schema
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Maximum county rows to return (default 100, max 500)."
},
"state": {
"type": "string",
"description": "Optional two-letter state code (e.g. \"NC\", \"VA\", \"GA\", \"PA\")."
},
"offset": {
"type": "integer",
"minimum": 0,
"description": "Pagination offset (default 0)."
},
"county_fips": {
"type": "string",
"description": "Optional 5-digit county FIPS code (e.g. \"37183\")."
},
"election_date": {
"type": "string",
"description": "Election date in YYYY-MM-DD format (default \"2026-11-03\")."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
},
"include_precincts": {
"type": "boolean",
"description": "With county_fips (Texas): also return cumulative 2026 early ballots per precinct, aggregated from the SOS early-voting roster."
}
},
"additionalProperties": false
}get_live_early_vote_returns annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}get_precinct_election_returns
Advertised read-only
Read precinct-level election returns and normalized early-voting, absentee/mail, election-day, and provisional breakdowns across 87.7M precinct rows (linked to mapsmcp_precinct_id) from RoutPoint v2.
get_precinct_election_returns input schema
{
"type": "object",
"properties": {
"year": {
"type": "integer",
"description": "Optional election year (e.g. 2024, 2022, 2026)."
},
"limit": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Maximum rows to return (default 100, max 500)."
},
"party": {
"type": "string",
"description": "Optional party filter."
},
"state": {
"type": "string",
"description": "Two-letter state postal code (e.g. \"TX\", \"NC\", \"GA\", \"PA\")."
},
"office": {
"type": "string",
"description": "Optional office name filter."
},
"offset": {
"type": "integer",
"minimum": 0,
"description": "Pagination offset (default 0)."
},
"district": {
"type": "string",
"description": "Optional legislative or congressional district code."
},
"contest_id": {
"type": "integer",
"description": "Optional RoutPoint contest identifier for single-contest precinct returns."
},
"county_fips": {
"type": "string",
"description": "Optional 5-digit county FIPS code."
},
"election_id": {
"type": "integer",
"description": "Optional RoutPoint election identifier."
},
"office_level": {
"enum": [
"president",
"us_senate",
"us_house",
"governor",
"lt_governor",
"state_senate",
"state_assembly",
"state_house"
],
"type": "string",
"description": "Optional canonical office level."
},
"election_date": {
"type": "string",
"description": "Optional election date in YYYY-MM-DD format."
},
"election_type": {
"enum": [
"general",
"primary",
"runoff",
"special",
"municipal",
"recall"
],
"type": "string",
"description": "Optional election stage (default general)."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
},
"mapsmcp_precinct_id": {
"type": "string",
"description": "Optional MapsMCP precinct UUID filter."
}
},
"additionalProperties": false
}get_precinct_election_returns annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}get_county_officials
Advertised read-only
Read current local, county, municipal, judicial, and school-board officials (40,431 local officials; 97,231 total officials) by 5-digit county FIPS or state from RoutPoint v2.
get_county_officials input schema
{
"type": "object",
"properties": {
"q": {
"type": "string",
"description": "Optional name or title search query."
},
"fips": {
"type": "string",
"description": "Optional 5-digit county FIPS code (e.g. \"48201\" for Harris County TX, \"17031\" for Cook County IL)."
},
"limit": {
"type": "integer",
"maximum": 200,
"minimum": 1,
"description": "Maximum officials to return (default 100, max 200)."
},
"party": {
"type": "string",
"description": "Optional party filter."
},
"state": {
"type": "string",
"description": "Optional two-letter state code (e.g. \"TX\", \"IL\", \"CA\")."
},
"offset": {
"type": "integer",
"minimum": 0,
"description": "Pagination offset (default 0)."
},
"office_level": {
"enum": [
"county",
"municipal",
"judicial",
"school_board",
"statewide",
"state_legislative",
"federal"
],
"type": "string",
"description": "Optional office level filter."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}get_county_officials annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}get_county_economic_and_wealth_profile
Advertised read-only
Read a county’s economic vitality dossier (Census 15-sector business patterns, establishments, employees, payroll, average annual wage, new SOS LLC/Corp formations, SEC Form D capital raises, Form 4/FEC major donors,…
get_county_economic_and_wealth_profile input schema
{
"type": "object",
"properties": {
"fips": {
"type": "string",
"description": "Optional 5-digit county FIPS code (e.g. \"06087\" for Santa Cruz County CA, \"36061\" for New York County NY) for a full county dossier."
},
"sort": {
"enum": [
"avg_annual_wage_usd",
"economic_vitality_score",
"total_annual_payroll_usd",
"total_employees"
],
"type": "string",
"description": "Sort field when ranking counties in a state (default avg_annual_wage_usd)."
},
"limit": {
"type": "integer",
"maximum": 200,
"minimum": 1,
"description": "Maximum counties to return when ranking a state (default 50, max 200)."
},
"state": {
"type": "string",
"description": "Optional two-letter state code (e.g. \"CA\", \"TX\", \"NY\") to rank counties across a state."
},
"offset": {
"type": "integer",
"minimum": 0,
"description": "Pagination offset (default 0)."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}get_county_economic_and_wealth_profile annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}billing_status
Advertised read-only
BILLING — your subscription state: {billing_enabled, logged_in, plan (personal|team|null), status, active, renews, can_save}. billing_enabled is false until the server is configured with Stripe; while it is false,…
billing_status input schema
{
"type": "object",
"properties": {
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}billing_status annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}connection_status
Advertised read-only
WHO AM I — how THIS session is authenticated and which workspace this request resolved to. Returns authentication fields plus workspace {workspace_id, role, selection_source}. Modern MCP clients select a workspace with…
connection_status input schema
{
"type": "object",
"properties": {
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}connection_status output schema
{
"$id": "https://www.electionsmcp.com/schemas/mcp/connection_status/v1",
"type": "object",
"oneOf": [
{
"allOf": [
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"result_status": {
"enum": [
"error",
"unavailable"
]
}
},
"additionalProperties": true
}
]
},
{
"allOf": [
{
"not": {
"required": [
"error"
]
}
},
{
"type": "object",
"required": [],
"properties": {
"result_status": {
"enum": [
"success",
"empty",
"partial",
"unavailable"
]
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"logged_in",
"auth_method",
"tool_profile",
"workspace"
],
"properties": {
"first_run": {
"type": "object",
"required": [],
"properties": {},
"additionalProperties": true
},
"logged_in": {
"type": "boolean"
},
"workspace": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"workspace_id",
"role",
"selection_source"
],
"properties": {
"role": {
"type": [
"string",
"null"
]
},
"workspace_id": {
"type": "string"
},
"selection_source": {
"type": "string"
}
},
"additionalProperties": true
}
]
},
"connection": {
"type": "object",
"required": [],
"properties": {},
"additionalProperties": true
},
"onboarding": {
"type": "object",
"required": [],
"properties": {},
"additionalProperties": true
},
"auth_method": {
"enum": [
"anonymous",
"session",
"api_key",
"oauth"
]
},
"tool_profile": {
"type": "string"
}
},
"additionalProperties": true
}
]
}
],
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"contract_version",
"result_status",
"workspace_id",
"affected",
"delta",
"latency_ms",
"category"
],
"properties": {
"delta": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"affected": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"category": {
"type": "string"
},
"latency_ms": {
"type": "integer",
"minimum": 0
},
"workspace_id": {
"type": "string"
},
"result_status": {
"enum": [
"success",
"empty",
"partial",
"unavailable",
"error"
]
},
"contract_version": {
"const": 1
}
},
"description": "Versioned MCP result. success/empty describe completed reads; partial retains explicit missing coverage or another search page; unavailable describes a missing dependency. error/unavailable with an error code also set MCP isError. Existing provenance and context fields remain authoritative.",
"additionalProperties": true
}connection_status annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}set_candidates
Advertised destructive
Replace the entire candidate roster for a simulation+level in one call (add / edit / remove / reorder). Each candidate: {id?, name, party, color?, incumbent?}; ids auto-assigned if omitted. Use this to set the real…
set_candidates input schema
{
"type": "object",
"required": [
"simulation_id",
"level",
"candidates"
],
"properties": {
"level": {
"enum": [
"president",
"senate",
"governor",
"house",
"state_senate",
"state_assembly",
"attorney_general",
"secretary_of_state",
"treasurer",
"custom"
],
"type": "string"
},
"candidates": {
"type": "array",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"color": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"party": {
"type": [
"string",
"null"
]
},
"incumbent": {
"type": "boolean"
}
},
"additionalProperties": false
},
"minItems": 0
},
"simulation_id": {
"type": "string"
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
},
"expected_version": {
"type": "string",
"description": "The last-read updated_at token; custom model writes refuse stale edits."
}
},
"additionalProperties": false
}set_candidates annotations
{
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": true
}set_turnout
Advertised destructive
Set the turnout (mobilization) model. PRESIDENT (default, unchanged): each dial is a percentage-point boost toward toward_candidate_id in counties over an ACS threshold (college = >20% BA share, immig = >15%…
set_turnout input schema
{
"type": "object",
"required": [
"simulation_id"
],
"properties": {
"clear": {
"type": "boolean",
"description": "Race-scoped levels only: true removes every turnout (ballots) factor on this level and its set_turnout levers, returning ballots to the baseline. Vote-share edits stay. Do not combine with turnout_change_pct or a cohort."
},
"immig": {
"type": "number",
"maximum": 50,
"minimum": -50
},
"level": {
"enum": [
"president",
"senate",
"governor",
"house",
"state_senate",
"state_assembly",
"attorney_general",
"secretary_of_state",
"treasurer"
],
"type": "string",
"default": "president",
"description": "president (default) = the classic ACS-threshold dials below. Any other level = the race-scoped ballots lever (turnout_change_pct + cohort)."
},
"source": {
"type": "string",
"maxLength": 300,
"description": "Where this user-authored assumption came from (user statement, field report, or source citation) — stored on the lever's audit entry."
},
"college": {
"type": "number",
"maximum": 50,
"minimum": -50
},
"geo_ids": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 500,
"description": "Explicit geography cohort — 5-digit county FIPS on statewide levels (e.g. \"23005\" = Cumberland ME), district external ids on house/state-leg, or precinct external ids (they contain a dash, e.g. \"34013-0001\") on any race level. Precinct ids apply at precinct grain where the scenario uses the canonical precinct baseline; ids that cannot take a factor are returned in excluded[] with a reason (never widened to a county). The receipt's precinct_impact lists the counties (and districts) that move."
},
"hiUnemp": {
"type": "number",
"maximum": 50,
"minimum": -50
},
"lowHome": {
"type": "number",
"maximum": 50,
"minimum": -50
},
"counties": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 500,
"description": "Alias of geo_ids for county cohorts."
},
"highHome": {
"type": "number",
"maximum": 50,
"minimum": -50
},
"criterion": {
"type": "object",
"required": [
"field",
"op",
"value"
],
"properties": {
"op": {
"enum": [
"gte",
"lte",
"gt",
"lt"
],
"type": "string"
},
"field": {
"enum": [
"pct_bachelors",
"pct_foreign_born",
"median_home",
"mhi",
"population",
"unemp_pct",
"median_age",
"owner_occ_pct"
],
"type": "string"
},
"value": {
"type": "number"
}
},
"description": "ACS-style county matcher (statewide levels): e.g. {field:\"population\", op:\"lt\", value:30000} = rural counties. Filters WITHIN geo_ids when both are passed; scope a bare criterion with state_fips.",
"additionalProperties": false
},
"assumption": {
"type": "string",
"maxLength": 600,
"description": "The modeling assumption in plain words (e.g. \"youth demobilization scenario\") — stored on the lever's audit entry."
},
"state_fips": {
"type": "string",
"description": "2-digit state FIPS to scope a criterion cohort to one state (e.g. \"23\" = Maine)."
},
"simulation_id": {
"type": "string"
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
},
"turnout_change_pct": {
"type": "number",
"maximum": 300,
"minimum": -90,
"description": "Race-scoped levels only: percent change to BALLOTS cast in the matched geography (-12 = 12% fewer, +8 = 8% more). Composes multiplicatively with prior levers; the factor is clamped to [0.05, 5]."
},
"toward_candidate_id": {
"type": "string",
"default": "D"
}
},
"additionalProperties": false
}set_turnout annotations
{
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": true
}add_map_comment
Advertised destructive
Leave a Google-Docs-style COMMENT on the scenario map — a threaded, resolvable discussion anchored to a place. CAMPAIGN ISOLATION: when working inside a campaign, pass campaign_id; the scenario must be filed under it…
add_map_comment input schema
{
"type": "object",
"required": [
"simulation_id",
"body"
],
"properties": {
"lat": {
"type": "number",
"description": "Free-point anchor latitude (use with lng)."
},
"lng": {
"type": "number",
"description": "Free-point anchor longitude (use with lat)."
},
"body": {
"type": "string",
"description": "The comment text (supports @mentions by email/handle)."
},
"level": {
"type": "string",
"description": "Feature anchor level (county|precinct|state|house|state_senate|state_assembly). Defaults to the sim level."
},
"title": {
"type": "string",
"description": "Optional short name for the post (a strategy/target/event has one; plain chat does not — feeds fall back to a body excerpt). Indexed for full-text search alongside body."
},
"object": {
"type": "object",
"required": [
"kind",
"ref"
],
"properties": {
"ref": {
"type": "string"
},
"kind": {
"enum": [
"strategy",
"strategy_step",
"annotation",
"version",
"candidate",
"person",
"report_widget"
],
"type": "string"
}
},
"description": "Anchor the comment to an OBJECT (a strategy / strategy step / annotation / version / candidate / workspace person / canonical report widget), not a map place — the comment is ABOUT that object. A person ref must resolve inside this workspace and, when campaign-scoped, the person must be assigned to that campaign. A report_widget ref is verified against this exact saved scenario version.",
"additionalProperties": false
},
"payload": {
"type": "object",
"description": "Category-specific structured fields, stored as-is. Examples — target: { priority, channel, universe_ref }; action: { status, assignee, due_at, priority }; need: { qty, unit, urgency }; event: { event_kind, starts_at, ends_at }."
},
"regions": {
"type": "array",
"items": {
"type": "string"
},
"description": "The post's MANY-TO-MANY location — the region/turf/shapefile ids this post covers (a multi-area comment's selected regions, a canvass turf, a target's shapes). ONE comment can anchor to MANY areas: pass every id here. Written to the post_regions junction (\"what is happening in this region?\" stays one indexed query) AND stamped by the server onto the comment's payload.regions, so every reader of the post gets the full set back and the open map frames all of it. Returns regions_saved = what actually landed."
},
"category": {
"enum": [
"note",
"target",
"canvass",
"action",
"need",
"event",
"strategy"
],
"type": "string",
"description": "UNIFIED WAR ROOM OBJECTS: what kind of floater this placement is. Every category shares the same anchor model and starts a thread; the category drives the icon, the War Room grouping, and which payload fields make sense. A canvass_kind implies category \"canvass\" automatically."
},
"icon_type": {
"type": "string",
"description": "The icon/subtype within the category — e.g. note: why|risk|fact|question; target: by role; canvass: the drop kind; action: follow_up|call|door|research|decision."
},
"parent_id": {
"type": "string",
"description": "Reply to this comment id (creates a thread; inherits the parent's anchor)."
},
"feature_id": {
"type": "string",
"description": "Anchor to this feature (5-digit county FIPS / precinct external_id / 2-digit state FIPS / district GEOID)."
},
"attachments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": "string"
},
"kind": {
"enum": [
"link",
"view"
],
"type": "string"
},
"mime": {
"type": "string"
},
"name": {
"type": "string"
},
"size": {
"type": "number"
},
"object_path": {
"type": "string"
}
}
},
"description": "Attachments on the message: [{name,url,mime,size,object_path?,kind?}]. An UPLOADED FILE rides as the object_path returned by /api/chat-upload — the bucket is private, so each read mints a fresh short-lived signed url into `url` (never store or share one; it expires). kind:\"link\" for pasted links; kind:\"view\" for a PINNED MAP VIEW whose url is a same-origin /sim?… deep link (the message carries the exact map context, and clicking the chip restores it)."
},
"campaign_id": {
"type": "string",
"description": "Campaign that owns this War Room message. The simulation must be tagged into it. Omit only for scenario-global discussion."
},
"region_kind": {
"type": "string",
"description": "What grain the regions[] ids are (precinct|county|state|district). Defaults to the anchor level."
},
"canvass_data": {
"type": "object",
"description": "Optional structured data for a field pin: { label, status, support_score, contacted_at, … } — anything your campaign tracks per pin."
},
"canvass_kind": {
"enum": [
"supporter",
"voter",
"door",
"target",
"note"
],
"type": "string",
"description": "Make this a color-coded FIELD-MAP PIN (Map View canvassing) instead of a plain comment: supporter (green) | voter (amber) | door (blue) | target (red) | note (teal). Use with a point anchor (lng+lat) or a feature_id. The body is the pin label."
},
"simulation_id": {
"type": "string"
},
"audience_scope": {
"type": "object",
"required": [
"audience",
"precinct_ids",
"boundary_version"
],
"properties": {
"audience": {
"enum": [
"campaign",
"leadership",
"finance"
],
"type": "string"
},
"precinct_ids": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"maxLength": 160,
"minLength": 1
},
"maxItems": 5000,
"minItems": 1,
"uniqueItems": true
},
{
"type": "null"
}
],
"description": "Exact precinct IDs. Preserve leading zeros. Null means campaign-wide."
},
"boundary_version": {
"type": [
"string",
"null"
],
"maxLength": 120,
"description": "The exact boundary version for these precinct IDs; required for precinct access."
}
},
"description": "Who can read this discussion or assignment. Replies and work originating in a discussion inherit its audience.",
"additionalProperties": false
},
"report_context": {
"type": "object",
"required": [
"report_id",
"widget_id"
],
"properties": {
"report_id": {
"type": "string"
},
"widget_id": {
"type": "string"
}
},
"description": "Bind this discussion to the exact immutable report widget the user is viewing. The report and widget must belong to simulation_id and the caller's workspace; the resulting receipt uses that report's pinned version and truthful widget coverage.",
"additionalProperties": false
},
"idempotency_key": {
"type": "string",
"description": "Optional retry key. Replays return the same post and immutable context instead of duplicating the message."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}add_map_comment annotations
{
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": false,
"destructiveHint": true
}list_map_comments
Advertised read-only
List one campaign's map comments on a scenario (oldest-first), each with its campaign_id, anchor, author, body, @mentions, parent_id, and resolved state. Pass campaign_id inside a campaign; only that exact campaign is…
list_map_comments input schema
{
"type": "object",
"required": [
"simulation_id"
],
"properties": {
"campaign_id": {
"type": "string",
"description": "Exact campaign War Room to read. The simulation must be filed under it."
},
"comment_ids": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 50,
"description": "Read only these comments (a delta after a live event named them). The reply carries subset:true plus missing[] for ids that are not in this War Room."
},
"simulation_id": {
"type": "string"
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
},
"include_resolved": {
"type": "boolean",
"description": "Include resolved comments (default true)."
}
},
"additionalProperties": false
}list_map_comments annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}apply_uniform_swing
Advertised destructive
Apply an incremental swing in points toward one candidate at the requested office. A saved race_scope restricts writes to that state or district and refuses a different office or unresolved geography. Unscoped and…
apply_uniform_swing input schema
{
"type": "object",
"required": [
"simulation_id",
"level",
"swing_pp"
],
"properties": {
"as_of": {
"type": "string",
"description": "YYYY-MM-DD timeline point at which to evaluate the decayed swing. Default: decay_start_date (full magnitude). Only used when decay_halflife is set."
},
"level": {
"enum": [
"president",
"senate",
"governor",
"house",
"state_senate",
"state_assembly",
"attorney_general",
"secretary_of_state",
"treasurer"
],
"type": "string"
},
"swing_pp": {
"type": "number",
"maximum": 50,
"minimum": -50
},
"simulation_id": {
"type": "string"
},
"decay_halflife": {
"type": "number",
"description": "Optional. Half-life in DAYS: past decay_start_date the applied swing halves every this-many days (exponential fade toward baseline). Omit for a permanent swing (today's behavior).",
"exclusiveMinimum": 0
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
},
"decay_start_date": {
"type": "string",
"description": "YYYY-MM-DD the shift lands / peaks (decay measured forward from here). Default: today. Only used when decay_halflife is set."
},
"toward_candidate_id": {
"type": "string",
"default": "D"
}
},
"additionalProperties": false
}apply_uniform_swing annotations
{
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": false,
"destructiveHint": true
}get_tally
Advertised read-only
Compute the current per-candidate tally for a simulation+level. For President: state-aggregated EVs. For others: feature counts. For level:"senate" the default is the 50-state per-candidate race scoreboard; pass…
get_tally input schema
{
"type": "object",
"required": [
"simulation_id",
"level"
],
"properties": {
"cycle": {
"type": "integer",
"description": "Election cycle for chamber control (level:\"senate\", chamber:true); default 2028. Ignored otherwise."
},
"level": {
"enum": [
"custom",
"president",
"senate",
"governor",
"house",
"state_senate",
"state_assembly",
"attorney_general",
"secretary_of_state",
"treasurer"
],
"type": "string"
},
"chamber": {
"type": "boolean",
"description": "level:\"senate\" only — return real chamber control ({D,R,I,seats_up,held_over,majority_status}) via the same math as senate_control, instead of the 50-state race scoreboard."
},
"simulation_id": {
"type": "string"
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}get_tally annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}list_simulations
Advertised read-only
List saved simulations in this workspace (id, name, level, cycle, mode, contest_id, last-modified; rows stamped with an identity also carry created_by/updated_by member user_ids). Optional filters narrow a large…
list_simulations input schema
{
"type": "object",
"properties": {
"q": {
"type": "string",
"description": "Case-insensitive substring match on the simulation name."
},
"mode": {
"type": "string",
"description": "Filter by president modeling mode: general | dem_primary_2028 | rep_primary_2028."
},
"cycle": {
"type": "integer",
"description": "Filter by election cycle year (e.g. 2028)."
},
"level": {
"type": "string",
"description": "Filter by office/level (e.g. president, senate, house, governor)."
},
"limit": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Max rows to return (pagination page size)."
},
"owner": {
"type": "string",
"description": "Filter to sims created by this member user_id (the stable UUID from list_members) — \"my sims\" / \"Dana's sims\". Sims saved before identity stamping have no owner and never match."
},
"offset": {
"type": "integer",
"minimum": 0,
"description": "Rows to skip before returning (pagination cursor)."
},
"race_id": {
"type": "string",
"description": "Filter to sims bound to this race_id."
},
"contest_id": {
"type": "string",
"description": "Filter to sims bound to this contest_id."
},
"updated_since": {
"type": "string",
"description": "Only sims modified at or after this ISO timestamp/date."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}list_simulations annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}get_simulation
Advertised read-only
Read the canonical simulation/scenario state, including candidates, race scope, geography overrides, active version identity, provenance, and optional summary or selected dot-path fields.
get_simulation input schema
{
"type": "object",
"required": [
"simulation_id"
],
"properties": {
"fields": {
"description": "Optional read shaping: the string \"summary\" → the compact identity card (target <5KB); an array of dot-paths (e.g. [\"id\",\"mode\",\"primary.asof\",\"primary.grain_pref\",\"updated_at\"]) → just those values from the document (plus mode_truth / campaign_identity / provenance as pickable top-level paths). Omit for the full state."
},
"simulation_id": {
"type": "string"
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}get_simulation annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}list_flipped
Advertised read-only
List baseline-to-model winner changes. Defaults to state for statewide offices, county for president, and district for house/state legislature. Explicit grain:county|precinct uses canonical integer local votes for a…
list_flipped input schema
{
"type": "object",
"required": [
"simulation_id",
"level"
],
"properties": {
"grain": {
"enum": [
"state",
"county",
"precinct",
"district"
],
"type": "string"
},
"level": {
"enum": [
"president",
"senate",
"governor",
"house",
"state_senate",
"state_assembly",
"attorney_general",
"secretary_of_state",
"treasurer"
],
"type": "string"
},
"limit": {
"type": "integer",
"default": 100,
"maximum": 5000,
"minimum": 1
},
"state": {
"type": "string",
"description": "One postal code/FIPS for explicit county/precinct enumeration; may be inferred from a saved state race."
},
"offset": {
"type": "integer",
"default": 0,
"minimum": 0
},
"simulation_id": {
"type": "string"
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}list_flipped annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}compare_simulations
Advertised read-only
Compare two simulations. Without grain, returns the existing chamber/feature comparison. With grain:county|precinct and one state, compares exact saved canonical vote rows: margin(B)-margin(A), winners, flips, ballots…
compare_simulations input schema
{
"type": "object",
"required": [
"simulation_id_a",
"simulation_id_b",
"level"
],
"properties": {
"grain": {
"enum": [
"county",
"precinct",
"district"
],
"type": "string",
"description": "Return canonical local outcomes instead of a chamber tally. county|precinct for president/statewide races; district|precinct for House and state-legislative races."
},
"level": {
"enum": [
"president",
"senate",
"governor",
"house",
"state_senate",
"state_assembly",
"attorney_general",
"secretary_of_state",
"treasurer"
],
"type": "string"
},
"limit": {
"type": "integer",
"default": 500,
"maximum": 2000,
"minimum": 1
},
"state": {
"type": "string",
"description": "Required for county/precinct comparison: one state postal code or FIPS."
},
"format": {
"enum": [
"json",
"csv",
"geojson"
],
"type": "string",
"description": "Local comparison table format; CSV/GeoJSON add a private complete-file download URL."
},
"offset": {
"type": "integer",
"default": 0,
"minimum": 0
},
"version_a": {
"type": "string",
"description": "Difference comparison: exact saved version of A. Omit only when its latest version matches the live model."
},
"version_b": {
"type": "string",
"description": "Difference comparison: exact saved version of B. Omit only when its latest version matches the live model."
},
"campaign_id_a": {
"type": "string",
"description": "Optional campaign custody for A when the model belongs to multiple readable campaigns. Does not grant access."
},
"campaign_id_b": {
"type": "string",
"description": "Optional campaign custody for B when the model belongs to multiple readable campaigns. Does not grant access."
},
"expected_hash_a": {
"type": "string",
"description": "Optional expected immutable version hash for A; mismatches refuse."
},
"expected_hash_b": {
"type": "string",
"description": "Optional expected immutable version hash for B; mismatches refuse."
},
"simulation_id_a": {
"type": "string"
},
"simulation_id_b": {
"type": "string"
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}compare_simulations annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}share_simulation
Advertised destructive
Mint a public, read-only link to the exact canonical scenario/version. Authenticate for durable workspace ownership; revoke_share disables the link.
share_simulation input schema
{
"type": "object",
"required": [
"simulation_id"
],
"properties": {
"sections": {
"type": "array",
"items": {
"enum": [
"race_result",
"map",
"impact",
"notes",
"widgets"
],
"type": "string"
},
"description": "Optional public-share section allowlist. Single-race shares remain race-scoped even when impact is requested.",
"uniqueItems": true
},
"ttl_days": {
"type": "integer",
"default": 30,
"maximum": 365,
"minimum": 1
},
"campaign_id": {
"type": "string",
"description": "Optional campaign that contains this simulation. The share is authorized against that campaign and its frozen context/manifest retain the campaign id."
},
"simulation_id": {
"type": "string"
},
"include_deltas": {
"type": "boolean",
"default": false,
"description": "Include modeled margin/share deltas from the canonical baseline for this exact race."
},
"include_impact": {
"type": "boolean",
"default": false,
"description": "Include national impact only for an unscoped national model. Ignored for a single-race or primary scope."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}share_simulation annotations
{
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": false,
"destructiveHint": true
}roll_up_race
Advertised read-only
Roll up precincts to a race outcome under the current simulation. Sums baseline votes for all precincts inside the district boundary, applying overrides in precedence order: a per-precinct override wins, else…
roll_up_race input schema
{
"type": "object",
"required": [
"simulation_id"
],
"properties": {
"level": {
"enum": [
"custom",
"president",
"senate",
"governor",
"attorney_general",
"secretary_of_state",
"treasurer",
"house",
"state_senate",
"state_assembly"
],
"type": "string"
},
"region": {
"type": "string",
"description": "Optional — with region_group, scope to exactly ONE region in the group (its slug), rolling up only that region's member counties."
},
"district_id": {
"type": "string",
"description": "District external id (for level=president/senate/governor, the state). EM-056: accepts a resolve_geography handle in any format — the slug \"us-pa\", postal \"PA\", or FIPS \"42\" — and also reads geo_id/state as aliases."
},
"region_group": {
"type": "string",
"description": "Optional saved county-grain workspace map region-group slug. Returns one modeled race rollup per named region."
},
"simulation_id": {
"type": "string"
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}roll_up_race output schema
{
"$id": "https://www.electionsmcp.com/schemas/mcp/roll_up_race/v1",
"type": "object",
"oneOf": [
{
"allOf": [
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"result_status": {
"enum": [
"error",
"unavailable"
]
}
},
"additionalProperties": true
}
]
},
{
"allOf": [
{
"not": {
"required": [
"error"
]
}
},
{
"type": "object",
"required": [],
"properties": {
"result_status": {
"enum": [
"success",
"empty",
"partial",
"unavailable"
]
}
},
"additionalProperties": true
},
{
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"votes",
"pct",
"winner",
"precincts_used"
],
"properties": {
"pct": {
"type": "object",
"required": [],
"properties": {},
"additionalProperties": true
},
"votes": {
"type": "object",
"required": [
"D",
"R",
"other",
"total"
],
"properties": {
"D": {
"type": "number"
},
"R": {
"type": "number"
},
"other": {
"type": "object",
"required": [],
"properties": {},
"additionalProperties": true
},
"total": {
"type": "number"
}
},
"additionalProperties": true
},
"winner": {
"type": [
"string",
"null"
]
},
"margin_pp": {
"type": "number"
},
"precincts_used": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"group_by",
"total",
"regions",
"empty_regions",
"precincts_matched"
],
"properties": {
"total": {
"type": "object",
"required": [],
"properties": {},
"additionalProperties": true
},
"regions": {
"type": "array",
"items": {
"type": "object",
"required": [],
"properties": {},
"additionalProperties": true
}
},
"group_by": {
"const": "region_group"
},
"empty_regions": {
"type": "integer",
"minimum": 0
},
"precincts_matched": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
}
],
"required": [
"simulation_id",
"context",
"level",
"district_id",
"baseline_source",
"baseline_coverage"
],
"properties": {
"level": {
"type": "string"
},
"context": {
"type": "object",
"required": [],
"properties": {},
"additionalProperties": true
},
"district_id": {
"type": "string"
},
"simulation_id": {
"type": "string"
},
"baseline_source": {
"type": "string"
},
"baseline_coverage": {
"type": [
"object",
"null"
],
"additionalProperties": true
}
}
}
]
}
],
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"contract_version",
"result_status",
"workspace_id",
"affected",
"delta",
"latency_ms",
"category"
],
"properties": {
"delta": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"affected": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"category": {
"type": "string"
},
"latency_ms": {
"type": "integer",
"minimum": 0
},
"workspace_id": {
"type": "string"
},
"result_status": {
"enum": [
"success",
"empty",
"partial",
"unavailable",
"error"
]
},
"contract_version": {
"const": 1
}
},
"description": "Versioned MCP result. success/empty describe completed reads; partial retains explicit missing coverage or another search page; unavailable describes a missing dependency. error/unavailable with an error code also set MCP isError. Existing provenance and context fields remain authoritative.",
"additionalProperties": true
}roll_up_race annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}apply_swing_to_query
Advertised destructive
Apply a uniform swing or an explicit per-precinct weights vector to a filtered cohort in one atomic call. Weights select only their named IDs, support canonical statewide mechanisms, and optionally rescale a persuasion…
apply_swing_to_query input schema
{
"type": "object",
"required": [
"simulation_id",
"state",
"filter"
],
"properties": {
"mix": {
"type": "number",
"default": 0.5,
"maximum": 1,
"minimum": 0,
"description": "mode:\"mixed\" only — the fraction of swing_pp delivered via persuasion (the rest via turnout)."
},
"mode": {
"enum": [
"persuasion",
"turnout",
"mixed"
],
"type": "string",
"description": "HOW the swing happens (EM-008). persuasion = conversion (×2 margin, ballots hold); turnout = one-sided ballots (×1 margin, votes_total moves); mixed = mix persuasion + the rest turnout. Omit for the classic call."
},
"level": {
"enum": [
"senate",
"governor",
"attorney_general",
"secretary_of_state",
"treasurer",
"house",
"state_senate",
"state_assembly",
"president"
],
"type": "string",
"description": "The office these swung precincts model — folds them into that race's state rollup (same tag as set_precinct_pcts). REQUIRED for mode:\"turnout\"/\"mixed\" (the ballots ride that race's lever kernel; president excluded)."
},
"state": {
"type": "string",
"description": "Postal, FIPS, or resolve_geography slug (\"us-pa\") — required, scopes the query (EM-056: all formats accepted; also fills from geo_id)."
},
"filter": {
"type": "object",
"description": "Precinct property → condition map within the requested geography. Properties: external_id, GEOID, name, state, county, county_fips, shape_id, votes_dem, votes_rep, votes_total, pct_dem_lead, official_boundary, lat, lng, population, mhi, median_home, pct_bachelors, pct_foreign_born, unemp_pct, median_age, owner_occ_pct, modeled_margin_pp, modeled_pct_dem_lead, flipped, overridden. A bare scalar means exact equality; an array means membership. Object operators: gt, gte, lt, lte, in, not_in. Comparisons take finite numbers; in/not_in take arrays of scalars. Conditions are ANDed. pct_dem_lead is a baseline two-party share lead in -1..1. Scenario-scoped target_precincts, aggregate_precincts and apply_swing_to_query also accept modeled_margin_pp (D minus R over ALL modeled ballots, percentage points), modeled_pct_dem_lead (same margin / 100), modeled_share.CANDIDATE_ID (0..1 all-ballot share), flipped (winner differs from baseline, including ties) and overridden (saved precinct or county share override). These require a supported general statewide scenario with an allocated local model; missing shares never match numeric comparisons. Example: {external_id:{in:[\"48009-11\"]},votes_total:{gte:500}}. Unknown properties/operators and malformed conditions are rejected before matching or writing."
},
"source": {
"type": "string",
"maxLength": 300,
"description": "mode calls that move ballots: stored on the lever's audit entry."
},
"weights": {
"type": "object",
"description": "Alternative to swing_pp: exact precinct external_id -> signed swing percentage points. Only these IDs change; all must be inside the state/filter with canonical ballots. Requires explicit D/R target, mode, statewide level and a cap covering the whole vector. President supports persuasion only. Optional target_margin_pp rescales a persuasion vector by a nonnegative factor (closest to 1 when several solutions exist), preserving its signs; target scope is weighted IDs only. Shares use sum-preserving 2-decimal rounding; receipt reports achieved margin/residual, clamps, weighted mean and one audit entry. Incremental; do not blindly replay after timeout.",
"maxProperties": 20000,
"minProperties": 1,
"additionalProperties": {
"type": "number",
"maximum": 50,
"minimum": -50
}
},
"swing_pp": {
"type": "number",
"maximum": 50,
"minimum": -50,
"description": "Percentage-point swing toward the target candidate. mode:\"turnout\": the percent of each precinct's ballots added for the target side."
},
"assumption": {
"type": "string",
"maxLength": 600,
"description": "mode calls that move ballots: stored on the lever's audit entry."
},
"max_precincts": {
"type": "integer",
"default": 5000,
"maximum": 20000,
"minimum": 1,
"description": "Safety cap on how many precincts get mutated."
},
"simulation_id": {
"type": "string"
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
},
"target_margin_pp": {
"type": "number",
"maximum": 100,
"minimum": -100,
"description": "Alternative to swing_pp: desired margin of the target party over the other major party, as a percentage of all modeled ballots in the filtered cohort. Requires mode:persuasion, explicit toward_candidate_id and statewide level (including president). Cannot be combined with swing_pp."
},
"toward_candidate_id": {
"type": "string",
"description": "The candidate id receiving the swing (e.g. \"D\", \"R\", or a custom id). Inferred to the level's first candidate of opposite party if omitted."
}
},
"additionalProperties": false
}apply_swing_to_query annotations
{
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": false,
"destructiveHint": true
}get_campaign_onboarding
Advertised read-only
CAMPAIGN ONBOARDING — guide a campaign manager or joining staff member through setup in their connected AI. Read one step or the complete guide: connection, campaign identity, team access, optional data imports, first…
get_campaign_onboarding input schema
{
"type": "object",
"properties": {
"section": {
"enum": [
"connection",
"campaign",
"team",
"data",
"work",
"complete",
"all"
],
"type": "string",
"default": "connection",
"description": "The next conversational step. Read connection first; all returns the complete guide when campaign tools are available."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}get_campaign_onboarding annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}help
Advertised read-only
Orient an AI client to campaign onboarding through get_campaign_onboarding, user-controlled election modeling, candidate and presidential-primary workflows, supported geography, scenario versions, contextual War Room…
help input schema
{
"type": "object",
"properties": {
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}help annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}get_catalog
Advertised read-only
DISCOVERY — browse workflow/category groups, search tool names and descriptions, or fetch one complete schema and AI guide with tool. No arguments returns a compact counted index of the authorized inventory. Core…
get_catalog input schema
{
"type": "object",
"properties": {
"tool": {
"type": "string",
"description": "Exact retained tool name — returns the complete inputSchema and versioned AI guidance matching its use-<tool> MCP prompt when it is present in this session's tools/list."
},
"limit": {
"type": "integer",
"default": 20,
"maximum": 50,
"minimum": 1,
"description": "Maximum tool entries per discovery page, subject to the response byte budget. Repeat the same filters with next_cursor as cursor until null."
},
"query": {
"type": "string",
"description": "Text search over this session's retained tool names and descriptions. Ranked: exact name, name substring, then description matches."
},
"cursor": {
"type": "string",
"maxLength": 512,
"description": "Opaque next_cursor from the previous discovery page. Keep the same query, category and workflow; restart if the authorized catalog changed."
},
"category": {
"type": "string",
"description": "Browse one category (e.g. \"Scenario\") in bounded pages. The category count is the full matching inventory, not this page length."
},
"workflow": {
"enum": [
"modeling",
"campaign_operations",
"imports",
"account_and_support",
"staff_support",
"discovery"
],
"type": "string",
"description": "Opt into a workflow from the compact index. Filters browsing or search within the authorized inventory; never grants access or changes the connection profile."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
},
"expected_catalog_version": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Optional catalog_version from a previous tools/list or get_catalog response. Returns catalog_changed so clients can detect schema drift and refresh cached bindings."
}
},
"additionalProperties": false
}get_catalog output schema
{
"$id": "https://www.electionsmcp.com/schemas/mcp/get_catalog/v1",
"type": "object",
"oneOf": [
{
"allOf": [
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"result_status": {
"enum": [
"error",
"unavailable"
]
}
},
"additionalProperties": true
}
]
},
{
"allOf": [
{
"not": {
"required": [
"error"
]
}
},
{
"type": "object",
"required": [],
"properties": {
"result_status": {
"enum": [
"success",
"empty",
"partial",
"unavailable"
]
}
},
"additionalProperties": true
},
{
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"tool"
],
"properties": {
"tool": {
"type": "object",
"required": [
"name",
"category",
"description"
],
"properties": {
"name": {
"type": "string"
},
"category": {
"type": "string"
},
"annotations": {
"type": "object",
"required": [],
"properties": {},
"additionalProperties": true
},
"description": {
"type": "string"
},
"inputSchema": {
"type": "object",
"required": [],
"properties": {},
"additionalProperties": true
},
"outputSchema": {
"type": "object",
"required": [],
"properties": {},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"query",
"matched",
"returned_count",
"truncated",
"next_cursor",
"matches"
],
"properties": {
"query": {
"type": "string"
},
"matched": {
"type": "integer",
"minimum": 0
},
"matches": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"category",
"description"
],
"properties": {
"name": {
"type": "string"
},
"category": {
"type": "string"
},
"annotations": {
"type": "object",
"required": [],
"properties": {},
"additionalProperties": true
},
"description": {
"type": "string"
},
"inputSchema": {
"type": "object",
"required": [],
"properties": {},
"additionalProperties": true
},
"outputSchema": {
"type": "object",
"required": [],
"properties": {},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"truncated": {
"type": "boolean"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"returned_count": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"total_tools",
"returned_tools",
"categories"
],
"properties": {
"mode": {
"enum": [
"category_index",
"category",
"workflow"
]
},
"matched": {
"type": "integer",
"minimum": 0
},
"truncated": {
"type": "boolean"
},
"workflows": {
"type": "array",
"items": {
"type": "object",
"required": [
"workflow",
"label",
"count"
],
"properties": {
"count": {
"type": "integer",
"minimum": 0
},
"label": {
"type": "string"
},
"workflow": {
"type": "string"
},
"recommended_tools": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": true
}
},
"categories": {
"type": "array",
"items": {
"type": "object",
"required": [
"category",
"count",
"tools"
],
"properties": {
"count": {
"type": "integer",
"minimum": 0
},
"tools": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"category",
"description"
],
"properties": {
"name": {
"type": "string"
},
"category": {
"type": "string"
},
"annotations": {
"type": "object",
"required": [],
"properties": {},
"additionalProperties": true
},
"description": {
"type": "string"
},
"inputSchema": {
"type": "object",
"required": [],
"properties": {},
"additionalProperties": true
},
"outputSchema": {
"type": "object",
"required": [],
"properties": {},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"category": {
"type": "string"
}
},
"additionalProperties": true
}
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"total_tools": {
"type": "integer",
"minimum": 0
},
"returned_count": {
"type": "integer",
"minimum": 0
},
"returned_tools": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
}
],
"required": [
"profile"
],
"properties": {
"profile": {
"type": "object",
"required": [
"active",
"visible_in_tools_list",
"catalog_scope"
],
"properties": {
"active": {
"type": "string"
},
"catalog_scope": {
"type": "string"
},
"visible_in_tools_list": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"workflow": {
"enum": [
"modeling",
"campaign_operations",
"imports",
"account_and_support",
"staff_support",
"discovery"
]
}
}
}
]
}
],
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"contract_version",
"result_status",
"workspace_id",
"affected",
"delta",
"latency_ms",
"category"
],
"properties": {
"delta": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"affected": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"category": {
"type": "string"
},
"latency_ms": {
"type": "integer",
"minimum": 0
},
"workspace_id": {
"type": "string"
},
"result_status": {
"enum": [
"success",
"empty",
"partial",
"unavailable",
"error"
]
},
"contract_version": {
"const": 1
}
},
"description": "Versioned MCP result. success/empty describe completed reads; partial retains explicit missing coverage or another search page; unavailable describes a missing dependency. error/unavailable with an error code also set MCP isError. Existing provenance and context fields remain authoritative.",
"additionalProperties": true
}get_catalog annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}list_primary_calendar
Advertised read-only
Read the 2028 primary calendar with source dates, schedule certainty, modeled delegate coverage, missing jurisdictions, and threshold basis. New calendars include the six DNC-approved early dates; other unverified…
list_primary_calendar input schema
{
"type": "object",
"required": [
"party"
],
"properties": {
"party": {
"enum": [
"D",
"R"
],
"type": "string"
},
"simulation_id": {
"type": "string",
"description": "Optional. If given (and party=D), returns the sim's user-defined Dem calendar when one is set."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}list_primary_calendar annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}set_primary_shares
Advertised destructive
Set a party's presidential-primary vote shares — one state, or MANY states in a single call. SINGLE STATE: pass `state` + `shares` (unchanged behavior; echoes the full running roll_up). BATCH: pass `states` = { "SC":…
set_primary_shares input schema
{
"type": "object",
"required": [
"simulation_id",
"party"
],
"properties": {
"party": {
"enum": [
"D",
"R"
],
"type": "string"
},
"state": {
"type": "string",
"description": "SINGLE-STATE mode: State FIPS (\"19\") or 2-letter abbr (\"IA\"). Provide `state`+`shares` OR `states`, not both."
},
"shares": {
"type": "object",
"description": "SINGLE-STATE mode: Map of candidate_id → percentage (0-100), e.g. {\"vance\": 42, \"desantis\": 30}. Must reference set_primary_candidates ids. Empty ({}) un-models the state."
},
"states": {
"type": "object",
"description": "BATCH mode: Map of state (FIPS or 2-letter abbr) → its {candidate_id: pct} shares, e.g. {\"SC\":{\"newsom\":31,\"harris\":24},\"NH\":{...}}. Writes all states in one atomic call; an invalid state fails the whole batch (nothing is written). Empty ({}) for a state un-models it."
},
"simulation_id": {
"type": "string"
},
"include_rollup": {
"type": "boolean",
"description": "BATCH mode only: also return the full delegate roll_up alongside the default trimmed `delta` summary. Ignored in single-state mode (which always echoes the full roll_up)."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}set_primary_shares annotations
{
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": true
}roll_up_primary
Advertised read-only
The running delegate count — OR, for a race-scoped downballot sim, that race's own share rollup. DOWNBALLOT (tk_2110d54c1d0871): when the scenario is race-scoped to a non-presidential office (set_race_scope…
roll_up_primary input schema
{
"type": "object",
"required": [
"simulation_id",
"party"
],
"properties": {
"asof": {
"type": [
"integer",
"null"
],
"description": "Optional. Contests counted; omit/null = full calendar."
},
"party": {
"enum": [
"D",
"R"
],
"type": "string"
},
"state": {
"type": "string",
"description": "Optional. Scope the read to ONE contest (postal/FIPS/name): returns a `state` block with that contest's calendar position, modeling grain, and delegate allocation — and when the state sits BEYOND this call's asof, the response says so EXPLICITLY (top-level excluded_by_asof:true + contest_index + current_asof, never a silent absence). The \"is FL on the map?\" one-call answer."
},
"by_district": {
"type": "boolean",
"description": "Optional (Democratic only). Also return district_allocation: the SAME authoritative count broken out by DNC Rule 14 pool — per state, the district/at-large/PLEO pool sizes, and per congressional district its delegates, the threshold used, whether it used district-specific shares (modeled:true) or the statewide share, and who won its delegates; standings carry district_delegates + statewide_delegates per candidate. authoritative:true — it is not a second count; its totals equal the top-level standings."
},
"simulation_id": {
"type": "string"
},
"include_states": {
"type": "boolean",
"description": "Optional. Also return by_state[]: per voted contest — delegates each candidate won, plus eff_shares (the effective per-state candidate shares after the county/precinct rollup), modeled_by (\"precinct\"|\"county\"|\"state\"|null — which grain drove the state), modeled_count, and coverage_pct (grain-relative % of 2024 turnout modeled, or null). For must-win / anchor-state analysis and source/coverage display. When this call's asof cuts off states that HAVE durable modeling, the response also carries excluded_modeled_states[] + current_asof so those states are named, never silently missing from by_state."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}roll_up_primary output schema
{
"$id": "https://www.electionsmcp.com/schemas/mcp/roll_up_primary/v1",
"type": "object",
"oneOf": [
{
"allOf": [
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
},
"result_status": {
"enum": [
"error",
"unavailable"
]
}
},
"additionalProperties": true
}
]
},
{
"allOf": [
{
"not": {
"required": [
"error"
]
}
},
{
"type": "object",
"required": [],
"properties": {
"result_status": {
"enum": [
"success",
"empty",
"partial",
"unavailable"
]
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"party",
"total_delegates",
"delegates_to_win",
"allocated",
"uncalled",
"contests_counted",
"contests_total",
"standings",
"context"
],
"properties": {
"rule": {
"type": "string"
},
"party": {
"type": "string"
},
"context": {
"type": "object",
"required": [],
"properties": {},
"additionalProperties": true
},
"by_state": {
"type": "array",
"items": {
"type": "object",
"required": [],
"properties": {},
"additionalProperties": true
}
},
"uncalled": {
"type": "number"
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"required": [],
"properties": {},
"additionalProperties": true
}
},
"allocated": {
"type": "number"
},
"standings": {
"type": "array",
"items": {
"type": "object",
"required": [
"candidate_id",
"delegates"
],
"properties": {
"name": {
"type": "string"
},
"delegates": {
"type": "number"
},
"candidate_id": {
"type": "string"
}
},
"additionalProperties": true
}
},
"contests_total": {
"type": "integer",
"minimum": 0
},
"total_delegates": {
"type": "number"
},
"contests_counted": {
"type": "integer",
"minimum": 0
},
"contests_modeled": {
"type": "integer",
"minimum": 0
},
"delegates_to_win": {
"type": "number"
}
},
"additionalProperties": true
}
]
}
],
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"contract_version",
"result_status",
"workspace_id",
"affected",
"delta",
"latency_ms",
"category"
],
"properties": {
"delta": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"affected": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"category": {
"type": "string"
},
"latency_ms": {
"type": "integer",
"minimum": 0
},
"workspace_id": {
"type": "string"
},
"result_status": {
"enum": [
"success",
"empty",
"partial",
"unavailable",
"error"
]
},
"contract_version": {
"const": 1
}
},
"description": "Versioned MCP result. success/empty describe completed reads; partial retains explicit missing coverage or another search page; unavailable describes a missing dependency. error/unavailable with an error code also set MCP isError. Existing provenance and context fields remain authoritative.",
"additionalProperties": true
}roll_up_primary annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}primary_batch_edit
Advertised destructive
ATOMIC batch-edit transaction for a PRIMARY scenario — validate, preview, apply, and roll back a whole SET of candidate / share / calendar edits as ONE transaction. Pass edits:[{op, ...}, …] where each entry carries…
primary_batch_edit input schema
{
"type": "object",
"required": [
"simulation_id",
"edits"
],
"properties": {
"edits": {
"type": "array",
"items": {
"type": "object"
},
"description": "Ordered heterogeneous list of primary edits, each an object {op, …opArgs}. op is one of set_primary_shares, set_primary_county_shares, set_primary_precinct_shares, set_primary_candidates, set_primary_asof, clear_primary_shares, define_dem_calendar, clear_dem_calendar, set_primary_grain_pref, set_primary_demo_levers. The remaining fields are exactly the args that single-edit tool takes, e.g. {\"op\":\"set_primary_shares\",\"party\":\"d\",\"state\":\"SC\",\"shares\":{\"newsom\":31,\"harris\":24}}. Applied in array order onto the working copy."
},
"force": {
"type": "boolean",
"description": "Apply despite soft WARNINGS (just-over-100 totals, viability flags, mode/geo/calendar notes). Still BLOCKS on hard errors (unknown candidate, malformed edit, shares over 100.5). Default false."
},
"party": {
"type": "string",
"description": "Default party (d/r) for edits that omit their own party. Defaults to the sim's primary party."
},
"dry_run": {
"type": "boolean",
"description": "DEFAULT true — preview only: returns before/after/delta/warnings/errors/viability_flags and writes NOTHING. Pass false to actually apply."
},
"simulation_id": {
"type": "string",
"description": "The scenario/simulation to edit (sim_…)."
},
"setup_evidence": {
"type": "object",
"description": "For automatic public-profile initialization: {kind:\"primary_profile_start\",model:\"geographic-context-v1\",profile_version:\"2026-09-05.v1\",ranking:[{id,name}]}. Use the same ordered ranking; the server validates the catalog and final roster/shares before one atomic save. Dry runs return proposed evidence; only applied evidence with version identity confirms success."
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
},
"checkpoint_label": {
"type": "string",
"description": "Optional label for the pre-batch rollback checkpoint version created on apply."
},
"expected_version_hash": {
"type": "string",
"pattern": "^v1:[0-9a-f]{32}$",
"description": "Copy expected_version_hash from the setup dry run to refuse overwriting an intervening edit. Exact already-applied replay returns the existing version."
}
},
"additionalProperties": false
}primary_batch_edit annotations
{
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": true
}set_race_scope
Advertised destructive
Bind the canonical scenario to one race/campaign so its map, tally, candidates, War Room context, operations, outputs, and MCP actions share the same race identity.
set_race_scope input schema
{
"type": "object",
"required": [
"simulation_id"
],
"properties": {
"cycle": {
"type": "integer",
"default": 2028,
"maximum": 2100,
"minimum": 1900
},
"level": {
"enum": [
"president",
"senate",
"governor",
"attorney_general",
"secretary_of_state",
"treasurer",
"house",
"state_senate",
"state_assembly"
],
"type": "string",
"description": "DEPRECATED alias for `office` (kept for back-compat). Prefer `office`."
},
"stage": {
"enum": [
"general",
"d_primary",
"r_primary"
],
"type": "string",
"default": "general"
},
"office": {
"enum": [
"president",
"senate",
"governor",
"attorney_general",
"secretary_of_state",
"treasurer",
"house",
"state_senate",
"state_assembly"
],
"type": "string",
"description": "The office (seat) this race is for. This is the canonical parameter name; the older `level` is still accepted as an alias."
},
"rebind": {
"type": "boolean",
"default": false,
"description": "Deliberately re-district a campaign already bound to a DIFFERENT geography. Without it, re-scoping a bound sim is rejected (scope_locked) — a campaign is tied to the district it was created in."
},
"candidate": {
"type": "string",
"description": "A candidate/officeholder name (\"Lauren Boebert\") — resolved via resolve_candidate to their office + geography + cycle, so you scope their race in ONE call and they are auto-added to the roster as the incumbent. Ignored if geography_id is also given. If the name is in no source (never guessed) the call errors — pass office + geography_id instead."
},
"candidates": {
"type": "array",
"description": "Optional array of real candidates running this race: [{id, name, party, color, incumbent?}]. Overwrites the office's candidate list. If omitted, keeps existing candidates."
},
"geography_id": {
"type": "string",
"description": "Accepts the canonical resolve_geography slug at every office — president \"us\" / \"US\"; senate & governor \"us-pa\", \"PA\", or FIPS \"42\"; house \"us-ny-cd-17\", \"NY-17\", or the FIPS+CD external_id \"3617\". State-leg takes its district external_id from list_features. Omit when you pass `candidate`."
},
"simulation_id": {
"type": "string"
},
"workspace_scope": {
"type": "string",
"pattern": "^[uw]-[a-z0-9](?:[a-z0-9-]{0,61})$",
"maxLength": 64,
"minLength": 3,
"description": "Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not change the connection default. Must agree with MCP metadata and the effective HTTP workspace selector (header, otherwise connector URL). OAuth connections can only use their granted workspace. Membership and campaign permissions still apply."
}
},
"additionalProperties": false
}set_race_scope annotations
{
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": true
}call_tool
Advertised destructiveOpen-world
Run any other tool you are authorized for that is not in this list. Find it and its exact input schema with get_catalog (search, a workflow, or {tool: name}), then call call_tool({ name, arguments }). The named tool…
call_tool input schema
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "The exact tool name, as get_catalog returns it."
},
"arguments": {
"type": "object",
"description": "That tool's arguments, exactly as its get_catalog schema describes.",
"additionalProperties": true
}
},
"additionalProperties": false
}call_tool annotations
{
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": false,
"destructiveHint": true
}Prompts
55 advertised
check-in — Check in
Your AI checks its connection, whether it can save, and what it can do. First-run step 1: connection_status or help completes it.
open-race — Open a practice model
It starts a separate practice model of a real race on the supported 2024 presidential baseline. First-run step 2. Name any race: a state and office, or a district code like CA-03.
- race
- The race to open, e.g. "2026 Iowa Senate" or "CA-03". Defaults to the first-run race.
model-swing — Model a swing and save it
It moves the vote in the practice model, then commits a version you can compare later. First-run step 3: a swing tool then commit_version completes it.
- points
- Size of the uniform swing in points (default 2).
- toward
- "the Democrat" or "the Republican" (default the Democrat).
- version_name
- Name for the committed version (default "First swing").
connect-check — Check my connection
Read-only first-use verification: connection_status, billing_status, help. Configuration is not connection; a saved URL proves nothing until these answer.
daily-brief — Daily leadership brief
The campaign manager's daily loop in one ask: status, due and overdue work, unassigned work, Discussions needing a reply, then three next actions with the tool that does each. Changes nothing.
- campaign_id
- Which campaign. Omit when the workspace has exactly one.
field-program — Build a field program from my voter file
The field-data pipeline end to end: check the campaign's field_data block, upload and map the voter file, finish the precinct crosswalk, score it, save universes, and export a custody-marked list. Every write asks for the person's go-ahead first.
- campaign_id
- Which campaign. Omit when the workspace has exactly one.
- format
- List format to end with: dialer, texting, canvass or mail (default canvass).
onboard-campaign — Set up my campaign
Lead campaign setup or staff onboarding through the connected AI, using existing tools and verified saved work. Reading this prompt changes nothing.
- section
- connection (default), campaign, team, data, work, complete, or all.
use-resolve_geography — Use resolve geography
AI guidance for resolve_geography: Turn a place name or shorthand into its canonical geo_id — resolve natural-language or structured location input. Handles "CA-03"/"NC-4" (congressional districts), bare state names/abbreviations, "<County> County…
- query
- Required for execution. "CA-03", "El Dorado County CA", "the 4th state senate district in California", "Pennsylvania"
- year
- Disambiguates post-redistricting boundaries; defaults to current cycle.
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-resolve_candidate — Use resolve candidate
AI guidance for resolve_candidate: WHO holds or runs for WHAT — turn a candidate/officeholder name into their seat + next race. Given a name (full, last-name, or a registry alias — "Lauren Boebert", "Boebert"), returns the person(s) who match with their…
- name
- Required for execution. A candidate or officeholder name — full ("Lauren Boebert"), last-name ("Boebert"), or any registry alias. Matching…
- party
- Optional — keep only matches of this party (D/R/I), normalized by leading letter. For a stage/party-scoped picker.
- office
- Optional — keep only matches whose current OR next-race office matches (house, senate, governor, state_senate,…
- cycle
- Optional — keep only matches whose next_race is in this cycle (e.g. 2026).
- limit
- Max people to return when a name is ambiguous (default 8).
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-search_candidates — Use search candidates
AI guidance for search_candidates: BROWSE the canonical candidate registry WITHOUT a name — the nameless companion to resolve_candidate (which requires a name). Filter the registry of canonical people by party, office, and/or a name substring:…
- party
- Optional — only this party (D/R/I/L/G), normalized by leading letter.
- office
- Optional — match the registry office label. Keywords president / senate / house / governor are normalized; anything…
- q
- Optional — case-insensitive substring on the candidate name or any alias (typeahead).
- limit
- Max results (default 50). `total` reports the full match count; `truncated:true` when the list was trimmed.
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-lookup_address — Use lookup address
AI guidance for lookup_address: Resolve a US street address, ZIP, state, or U.S. House district and show workspace campaigns covering the result. Street addresses return a geocoded point and containing districts, with a precinct when coverage exists.…
- address
- Required for execution. A full street address ("123 Main St, Dallas, TX"), a 5-digit ZIP, a district code ("NC-4", "AK-AL"), a state…
- include_officials
- Attach the sitting officeholder for each resolved seat (from the committed legislator file).
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-list_contests — Use list contests
AI guidance for list_contests: Discover contests for a geography and election cycle. Filter general, primary (dem_primary/rep_primary), or all stages; count describes the returned top-level rows. National presidential primaries are discoverable in…
- geo_id
- Required for execution. "us" (national), a state as "us-pa" / postal "PA" / FIPS "42", or a district id — all accepted.
- cycle
- Defaults to the next election year from today.
- stage
- primary selects the dem_primary and rep_primary variants; general excludes them; all returns both.
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-election_calendar — Use election calendar
AI guidance for election_calendar: The election planning calendar. National form ({cycle}) returns federal contests, governors and by_state office lists; state form ({state,cycle}) returns a four-year horizon. Other statewide executive offices use the…
- state
- Postal abbreviation ("PA") for the per-state 4-year horizon; omit for the national summary.
- cycle
- Defaults to the next election year from today.
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-set_performance — Use set performance
AI guidance for set_performance: Set a candidate's vote share, such as the Democratic candidate to 54%, in one specific county, district, state, or precinct (the general-election override). Routes a county/state/district geo_id to a feature override…
- expected_version
- Optional optimistic-concurrency token: the scenario updated_at you last read. If the scenario changed since, the write…
- simulation_id
- Supply string as text; the guide includes the full tool schema.
- total_votes
- Explicit vote volume for a custom campaign city or reviewed precinct. Use level:"custom" and geo_id from…
- scenario_id
- Required for execution. The simulation_id (scenario_id alias until the scenario model lands).
- geo_id
- Required for execution. Supply string as text; the guide includes the full tool schema.
- shares
- Required for execution. candidate_id → share. Accepts 0–1 or 0–100.
- turnout
- 0–1 expected turnout (stored as metadata on precinct overrides).
- margin
- Shorthand for two-candidate D−R margin in points; sets D/R shares around 50.
- rebalance
- Supply string as text; the guide includes the full tool schema.
- level
- EM-136: explicit office for the override. A bare state geo (us-pa) otherwise defaults to senate — pass level to target…
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-target_precincts — Use target precincts
AI guidance for target_precincts: Return structured precinct model rows: precinct_id, name, county, county_fips, baseline_share, modeled_share, ballots_est, overridden, and gap_to_goal. The response does not include demographic columns or demographic…
- scenario_id
- Required for execution. The scenario/simulation handle (EM-056: simulation_id is accepted as an alias).
- geo_id
- District or state geography — accepts the resolve_geography slug ("us-pa"), postal ("PA"), or FIPS ("42") (EM-056).…
- goal_mode
- plurality = beat the leading opponent (default); majority = 50.01% share; share = explicit target_pct.
- margin
- plurality: win by at least this many votes.
- target_pct
- Supply number as text; the guide includes the full tool schema.
- candidate_id
- Supply string as text; the guide includes the full tool schema.
- context
- Free-text constraints, echoed back (e.g. "field ops in Orange and Durham only").
- filter
- Precinct property → condition map within the requested geography. Properties: external_id, GEOID, name, state, county,…
- limit
- Supply integer as text; the guide includes the full tool schema.
- offset
- Page start; pass next.offset from the prior result with the same scope and filters.
- rolloff_rate
- Explicit roll-off rate (see compute_vote_goal).
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-create_scenario — Use create scenario
AI guidance for create_scenario: Create a new Scenario (a modeled path) — optionally inside a Race and seeded from a contest_id or an existing scenario (import_from). Seeds an immutable baseline version (v1). Returns scenario_id + version_id. (A…
- name
- Required for execution. Supply string as text; the guide includes the full tool schema.
- baseline_id
- Optional explicit source pin. Only 2024_president_mixed_grain is currently selectable. Known county sources return…
- campaign_id
- Custom campaign to model inside its exact attached city boundary.
- expected_campaign_revision
- Supply integer as text; the guide includes the full tool schema.
- boundary_version
- Supply string as text; the guide includes the full tool schema.
- idempotency_key
- Optional workspace-scoped retry key for listed races; required for custom campaign models. Identical retries return…
- race_id
- Optional; the Race this scenario belongs to.
- contest_id
- Optional; sets the scenario's race_scope from a canonical contest_id.
- import_from
- Optional; copy overrides+candidates from an existing scenario_id.
- tags
- Supply array as text; the guide includes the full tool schema.
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-get_view — Use get view
AI guidance for get_view: Read the exact map/view state the application renders for a canonical scenario: headline totals, selected geography, modeled feature colors, annotations, primary-calendar playhead, candidate roster, presence, and a…
- version_id
- Exact saved version for a custom city model.
- expected_version_hash
- Supply string as text; the guide includes the full tool schema.
- simulation_id
- Required for execution. Supply string as text; the guide includes the full tool schema.
- campaign_id_a
- Optional campaign custody for A when the model belongs to multiple readable campaigns. Does not grant access.
- campaign_id_b
- Optional campaign custody for B when the model belongs to multiple readable campaigns. Does not grant access.
- version_a
- Difference comparison: exact saved version of A. Omit only when its latest version matches the live model.
- version_b
- Difference comparison: exact saved version of B. Omit only when its latest version matches the live model.
- expected_hash_a
- Optional expected immutable version hash for A; mismatches refuse.
- expected_hash_b
- Optional expected immutable version hash for B; mismatches refuse.
- compare_simulation_id
- Compare B against simulation_id (A), using D-minus-R margin(B) minus margin(A). Requires one explicit state and…
- difference_scale_pp
- Difference-only symmetric color extent: legend runs from negative this value through zero to positive this value. Omit…
- view
- difference uses compare_simulation_id as B and simulation_id as A; returns the zero-centered B-minus-A color scale and…
- level
- Which map the view renders. Default president (or whatever set_view last scoped). house = HOUSE CONTROL (per-state…
- state
- Optional postal code or 2-digit FIPS — scope the map to one state. president → its county breakdown;…
- grain
- With a state scoped, the grain of the local features returned: "county" (default) or "precinct". Applies to a…
- cycle
- Supply integer as text; the guide includes the full tool schema.
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-render_view — Use render view
AI guidance for render_view: A headless server-rendered IMAGE of the map — the rendered view a viewer sees, as SVG or PNG, WITHOUT a browser (tk_0b6d3501 P2). For a scenario + level (president | senate | house | governor | the execs) it draws the…
- simulation_id
- Required for execution. Supply string as text; the guide includes the full tool schema.
- campaign_id_a
- Optional campaign custody for A when the model belongs to multiple readable campaigns. Does not grant access.
- campaign_id_b
- Optional campaign custody for B when the model belongs to multiple readable campaigns. Does not grant access.
- version_a
- Difference comparison: exact saved version of A. Omit only when its latest version matches the live model.
- version_b
- Difference comparison: exact saved version of B. Omit only when its latest version matches the live model.
- expected_hash_a
- Optional expected immutable version hash for A; mismatches refuse.
- expected_hash_b
- Optional expected immutable version hash for B; mismatches refuse.
- compare_simulation_id
- Compare B against simulation_id (A), using D-minus-R margin(B) minus margin(A). Requires one explicit state and…
- difference_scale_pp
- Difference-only symmetric color extent: legend runs from negative this value through zero to positive this value. Omit…
- comparison_layout
- Difference-only 1200x630 card: one B-minus-A map (default), or the same-grain A | B | B-minus-A maps with explicit…
- level
- Which map to render. Default president. house = HOUSE CONTROL: states shaded by delegation majority, D/R seat tally,…
- layers
- Draw saved highlight annotations on matching visible geography. Omit to honor set_view layers.highlights (default…
- format
- Image format. Default svg (png needs the resvg renderer on the host; degrades to svg if absent).
- state
- Optional — scope the image to a state (postal "NC" or 2-digit FIPS). president → that state's per-county choropleth;…
- geo_id
- Optional — a geo slug like "us-nc" to scope to that state.
- feature_id
- Optional — a state fips (37) or county/precinct id (37xxx) to scope to its state.
- view
- "result" (default) = the outcome map; "swing" = colour by margin CHANGE vs the baseline (where the scenario MOVES the…
- theme
- MAP THEME preset for the rendered image (list_map_themes: control | analyst | field | civic | accessible | broadcast |…
- states
- CUSTOM MAP (president): a list of states (postal "PA" or 2-digit FIPS) → a cropped county choropleth of just those…
- features
- CUSTOM MAP (president): an explicit list of geo_ids to include — county FIPS (5-digit), state FIPS (2-digit), or…
- region_group
- CUSTOM MAP — a saved workspace map region-group slug. Expands to its member counties or states; add region to render…
- region
- CUSTOM MAP — with region_group, render exactly ONE region in the group (its slug).
- title
- CUSTOM MAP: a title for the card (e.g. "Rust Belt swing"). Defaults to the state list (or the region group / region…
- grain
- When scoped to ONE state (state/geo_id/feature_id), the geographic grain to render: "county" (default) per-county;…
- asof
- PRIMARY sims — render the delegate banner/standings AS OF this calendar checkpoint (contests counted; the same asof…
- share
- PUBLISH this map to a hostable URL: mints a share token and returns share.hosted_image_url / hosted_svg_url + a public…
- share_ttl_days
- Days the shared URL stays live (default 90, max 365). Only with share:true.
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-render_chart — Use render chart
AI guidance for render_chart: share_comparison compares candidate shares for two saved versions of one model or two same-contest statewide general-election models. Returns canonical integer candidate votes, all-ballot shares, D-minus-R margins,…
- simulation_id
- Scenario to render; for share_comparison this is A, or the single model with version_a/version_b.
- simulation_id_a
- share_comparison only: A model, alternative to simulation_id. Conflicting aliases refuse.
- simulation_id_b
- share_comparison only: B model in the same contest. Omit for two explicit versions of A.
- compare_simulation_id
- share_comparison only: alias for simulation_id_b.
- campaign_id_a
- Optional campaign custody for A when the model belongs to multiple readable campaigns. Does not grant access.
- campaign_id_b
- Optional campaign custody for B when the model belongs to multiple readable campaigns. Does not grant access.
- version_a
- Difference comparison: exact saved version of A. Omit only when its latest version matches the live model.
- version_b
- Difference comparison: exact saved version of B. Omit only when its latest version matches the live model.
- expected_hash_a
- Optional expected immutable version hash for A; mismatches refuse.
- expected_hash_b
- Optional expected immutable version hash for B; mismatches refuse.
- level
- share_comparison only: statewide office; defaults to the saved scope. Both versions must match office, state, cycle…
- type
- Required for execution. Which widget. share_comparison = saved candidate shares before/after, with paired version anchors and one state.…
- party
- For the primary charts — which party's race (defaults to the sim's primary mode).
- asof
- For the primary charts — evaluate the race at this calendar checkpoint (contests counted), the same asof…
- office
- For seat_hemicycle / decisive_seats — which chamber (default house). state_senate/state_assembly also need state.
- state
- State postal or FIPS. Required for share_comparison and state-leg seat_hemicycle/decisive_seats.
- cycle
- Election cycle for seat_hemicycle / decisive_seats (defaults to the sim's cycle, else 2026) — drives the Senate class…
- context_simulation_id
- seat_hemicycle / decisive_seats only — compute the WHOLE chamber rollup from THIS scenario (a linked…
- overlay_from_simulation_id
- seat_hemicycle / decisive_seats only — the scenario that supplies the ONE overlaid race's modeled result. Travels with…
- overlay_race
- The single race to swap in from overlay_from_simulation_id: {office, state, district}. office must match the card's…
- highlight_race
- Mark one race on the card (same shape as overlay_race): its dot wears an amber ring on seat_hemicycle, and…
- theme
- Chart audience palette, using the map-theme registry. Supported by primary charts, swing_bars and chamber_control.…
- style
- Optional brand overrides for the supported themed charts. Does not remove attribution or change candidate colors or…
- title
- Optional eyebrow/title for the chart.
- clinch
- ranking_board only — show each candidate's clinch line on the tiles (CLINCHES <state> · <date>, or how many delegates…
- format
- Image format. Default svg (png needs the resvg renderer; degrades to svg if absent).
- share
- PUBLISH to a hostable URL: mints a share token and returns share.hosted_image_url / hosted_svg_url that resolve for…
- share_ttl_days
- Days the shared URL stays live (default 90, max 365). Only with share:true.
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-set_view — Use set view
AI guidance for set_view: Set the active scenario view and selected map context: race stage, calendar playhead, geography grain, result source, selected feature, camera, map theme, and rail. The same persisted view state and deep link are used…
- simulation_id
- Required for execution. Supply string as text; the guide includes the full tool schema.
- level
- The map/level the view should show.
- state
- Postal code or 2-digit FIPS to scope to (pass empty string to clear to the national view).
- cycle
- Supply integer as text; the guide includes the full tool schema.
- camera_geo_id
- Optional geo to frame the camera on (defaults to the scoped state). 2-digit state / 5-digit county / district GEOID /…
- zoom
- Optional camera zoom; omit to fit the geo's bounds.
- layers
- View toggles such as precincts/highlights plus the canonical "actuals:pres_2024" baseline layer.
- stage
- The race stage the viewer should see. Persisted on view_state + broadcast live; a primary-mode sim's own mode remains…
- asof
- The primary calendar playhead — contests counted in the race-so-far (the number set_primary_asof takes). null = full…
- contest
- Playhead targeting by contest instead of a number: a state postal code ("FL"), 2-digit FIPS, or full name — the…
- contest_index
- Playhead targeting by 1-based calendar ordinal (list_primary_calendar order).
- map_grain
- The Map View grain toggle: states | counties | precincts (singular accepted, stored plural).
- map_theme
- Pin a MAP THEME audience preset on this view (list_map_themes has the registry: control | analyst | field | civic |…
- source
- The per-state Outcome SOURCE control (which grain governs the shown outcome). Stored on view_state; the sim's own…
- selected_geo
- The selected feature on the map ({level, feature_id} — e.g. {level:"county", feature_id:"12086"} for Miami-Dade). Pass…
- rail
- Which right-rail panel the viewer should have open.
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-get_scenario — Use get scenario
AI guidance for get_scenario: A Scenario at its latest version (or a specified version_id): metadata (incl. latest_hash) + the version's top_line (margin / EC / viability) + its content hash/prev_hash. EM-119: pass a version_id (or…
- scenario_id
- Required for execution. Supply string as text; the guide includes the full tool schema.
- version_id
- Optional; defaults to the latest version. When set, the response includes the full per-precinct `state` for that…
- expected_version_hash
- Optional exact content hash from list_scenario_versions. Requires version_id; a mismatch is refused rather than…
- include_state
- Include the full per-precinct `state` even for the latest version (for redrawing the map).
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-commit_version — Use commit version
AI guidance for commit_version: Save the scenario's current state as a new immutable, hash-stamped version in the append-only chain. Records a diff vs the parent version and the recomputed top_line, and returns a content `hash` (+ `prev_hash`…
- scenario_id
- Required for execution. Supply string as text; the guide includes the full tool schema.
- title
- Optional SHORT card title (<=80 chars), distinct from the longer summary — what the VERSIONS card shows as its…
- summary
- Human-readable note on what changed, e.g. "Flipped Orange County to D+40".
- annotation_ids
- Optional — annotation ids (pins/highlights/notes on this sim) this version explains. Validated against the sim's…
- insight_ids
- Optional — insight ids (ins_…) this version explains. Validated against the sim's insights; unknown ids are reported…
- include_diff
- Inline the full before/after diff in the response (can be very large). Default false: return compact diff_stats only;…
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-list_scenarios — Use list scenarios
AI guidance for list_scenarios: Page saved scenarios/simulations in this workspace by updated_at descending and scenario_id ascending, without version blobs. Returns scenario_id, name, level, cycle, contest_id, race_id, tags, durable_id, published…
- tags
- Return only scenarios carrying any of these tags.
- limit
- Supply integer as text; the guide includes the full tool schema.
- offset
- Use previous next_offset with unchanged tags and limit. Ordered by updated_at descending, scenario_id ascending.…
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-diff_versions — Use diff versions
AI guidance for diff_versions: Structured diff between two immutable versions. Raw before/after remain stored override patches (null means no saved override). Precinct cells also include effective_before/effective_after shares with their…
- scenario_id
- Required for execution. Supply string as text; the guide includes the full tool schema.
- version_a
- Required for execution. Supply string as text; the guide includes the full tool schema.
- version_b
- Required for execution. Supply string as text; the guide includes the full tool schema.
- limit
- Maximum changed precinct cells in this page. Summary counts cover the full version pair.
- offset
- Use precinct_page.next_offset to continue in stable precinct-id order.
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-get_early_voting_turnout — Use get early voting turnout
AI guidance for get_early_voting_turnout: Read early voting, absentee/mail, election-day, and provisional vote-method breakdowns alongside registered-voter, ballots-cast, and undervote/overvote turnout statistics by race and candidate from RoutPoint v2…
- state
- Required for execution. Two-letter state postal code (e.g. "TX", "NC", "GA", "FL", "PA", "MI", "AZ").
- election_date
- Optional election date in YYYY-MM-DD format (e.g. "2024-11-05", "2026-03-03", "2026-08-18"). Defaults to the most…
- election_type
- Optional election stage filter.
- county_fips
- Optional 5-digit county FIPS code (e.g. "48081", "37021") to scope returns and turnout to one county.
- office_level
- Optional canonical office level filter.
- office
- Optional office substring filter (e.g. "U.S. Senate", "Governor").
- district
- Optional district code filter for legislative or congressional races (e.g. "10", "11").
- source_id
- Optional 64-character SHA-256 source identifier for a specific county/state return file.
- include_precincts
- When true, include per-precinct early voting, mail, election-day, and turnout breakdowns inside each race.
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-get_county_voter_turnout_and_registration — Use get county voter turnout and registration
AI guidance for get_county_voter_turnout_and_registration: Read county voter registration, party registration (DEM/REP/UNA/Other), voting-age population, 2024/2022/2020/2026 ballots cast and turnout percentages, 2020-to-2024 partisan swing, and competitiveness tiers across…
- state
- Optional two-letter state code (e.g. "PA", "GA", "NC", "MI", "WI", "AZ", "NV", "TX").
- county_fips
- Optional 5-digit county FIPS code (e.g. "37183" for Wake NC, "04013" for Maricopa AZ).
- tier
- Optional competitiveness tier filter.
- sort
- Sort order (default ballots_cast_2024).
- limit
- Maximum counties to return (default 100, max 500).
- offset
- Pagination offset (default 0).
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-get_state_historical_turnout — Use get state historical turnout
AI guidance for get_state_historical_turnout: Read 50-year statewide prior-cycle turnout and vote totals (1976 through 2026 across all 50 states and DC): ballots cast, registered voters, voting-age population, turnout percentage, DEM/REP vote shares, margin, and…
- state
- Optional two-letter state code (e.g. "PA", "GA", "MI", "WI", "CA", "TX").
- year
- Optional election year filter (1976 through 2026).
- limit
- Maximum rows to return (default 100, max 500).
- offset
- Pagination offset (default 0).
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-get_live_early_vote_returns — Use get live early vote returns
AI guidance for get_live_early_vote_returns: Read live 2026-11-03 General Election pre-election mail ballot requests, mail ballots returned, early in-person ballots, and ballot composition by voter registration party (DEM/REP/UNA/Other) from continuously…
- state
- Optional two-letter state code (e.g. "NC", "VA", "GA", "PA").
- county_fips
- Optional 5-digit county FIPS code (e.g. "37183").
- election_date
- Election date in YYYY-MM-DD format (default "2026-11-03").
- include_precincts
- With county_fips (Texas): also return cumulative 2026 early ballots per precinct, aggregated from the SOS early-voting…
- limit
- Maximum county rows to return (default 100, max 500).
- offset
- Pagination offset (default 0).
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-get_precinct_election_returns — Use get precinct election returns
AI guidance for get_precinct_election_returns: Read precinct-level election returns and normalized early-voting, absentee/mail, election-day, and provisional breakdowns across 87.7M precinct rows (linked to mapsmcp_precinct_id) from RoutPoint v2.
- state
- Two-letter state postal code (e.g. "TX", "NC", "GA", "PA").
- county_fips
- Optional 5-digit county FIPS code.
- election_id
- Optional RoutPoint election identifier.
- contest_id
- Optional RoutPoint contest identifier for single-contest precinct returns.
- mapsmcp_precinct_id
- Optional MapsMCP precinct UUID filter.
- year
- Optional election year (e.g. 2024, 2022, 2026).
- election_date
- Optional election date in YYYY-MM-DD format.
- election_type
- Optional election stage (default general).
- office
- Optional office name filter.
- office_level
- Optional canonical office level.
- district
- Optional legislative or congressional district code.
- party
- Optional party filter.
- limit
- Maximum rows to return (default 100, max 500).
- offset
- Pagination offset (default 0).
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-get_county_officials — Use get county officials
AI guidance for get_county_officials: Read current local, county, municipal, judicial, and school-board officials (40,431 local officials; 97,231 total officials) by 5-digit county FIPS or state from RoutPoint v2.
- fips
- Optional 5-digit county FIPS code (e.g. "48201" for Harris County TX, "17031" for Cook County IL).
- state
- Optional two-letter state code (e.g. "TX", "IL", "CA").
- office_level
- Optional office level filter.
- party
- Optional party filter.
- q
- Optional name or title search query.
- limit
- Maximum officials to return (default 100, max 200).
- offset
- Pagination offset (default 0).
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-get_county_economic_and_wealth_profile — Use get county economic and wealth profile
AI guidance for get_county_economic_and_wealth_profile: Read a county’s economic vitality dossier (Census 15-sector business patterns, establishments, employees, payroll, average annual wage, new SOS LLC/Corp formations, SEC Form D capital raises, Form 4/FEC major donors,…
- fips
- Optional 5-digit county FIPS code (e.g. "06087" for Santa Cruz County CA, "36061" for New York County NY) for a full…
- state
- Optional two-letter state code (e.g. "CA", "TX", "NY") to rank counties across a state.
- sort
- Sort field when ranking counties in a state (default avg_annual_wage_usd).
- limit
- Maximum counties to return when ranking a state (default 50, max 200).
- offset
- Pagination offset (default 0).
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-billing_status — Use billing status
AI guidance for billing_status: BILLING — your subscription state: {billing_enabled, logged_in, plan (personal|team|null), status, active, renews, can_save}. billing_enabled is false until the server is configured with Stripe; while it is false,…
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-connection_status — Use connection status
AI guidance for connection_status: WHO AM I — how THIS session is authenticated and which workspace this request resolved to. Returns authentication fields plus workspace {workspace_id, role, selection_source}. Modern MCP clients select a workspace with…
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-set_candidates — Use set candidates
AI guidance for set_candidates: Replace the entire candidate roster for a simulation+level in one call (add / edit / remove / reorder). Each candidate: {id?, name, party, color?, incumbent?}; ids auto-assigned if omitted. Use this to set the real…
- expected_version
- The last-read updated_at token; custom model writes refuse stale edits.
- simulation_id
- Required for execution. Supply string as text; the guide includes the full tool schema.
- level
- Required for execution. Supply string as text; the guide includes the full tool schema.
- candidates
- Required for execution. Supply array as text; the guide includes the full tool schema.
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-set_turnout — Use set turnout
AI guidance for set_turnout: Set the turnout (mobilization) model. PRESIDENT (default, unchanged): each dial is a percentage-point boost toward toward_candidate_id in counties over an ACS threshold (college = >20% BA share, immig = >15%…
- simulation_id
- Required for execution. Supply string as text; the guide includes the full tool schema.
- level
- president (default) = the classic ACS-threshold dials below. Any other level = the race-scoped ballots lever…
- college
- Supply number as text; the guide includes the full tool schema.
- immig
- Supply number as text; the guide includes the full tool schema.
- highHome
- Supply number as text; the guide includes the full tool schema.
- lowHome
- Supply number as text; the guide includes the full tool schema.
- hiUnemp
- Supply number as text; the guide includes the full tool schema.
- toward_candidate_id
- Supply string as text; the guide includes the full tool schema.
- turnout_change_pct
- Race-scoped levels only: percent change to BALLOTS cast in the matched geography (-12 = 12% fewer, +8 = 8% more).…
- geo_ids
- Explicit geography cohort — 5-digit county FIPS on statewide levels (e.g. "23005" = Cumberland ME), district external…
- counties
- Alias of geo_ids for county cohorts.
- criterion
- ACS-style county matcher (statewide levels): e.g. {field:"population", op:"lt", value:30000} = rural counties. Filters…
- state_fips
- 2-digit state FIPS to scope a criterion cohort to one state (e.g. "23" = Maine).
- clear
- Race-scoped levels only: true removes every turnout (ballots) factor on this level and its set_turnout levers,…
- source
- Where this user-authored assumption came from (user statement, field report, or source citation) — stored on the…
- assumption
- The modeling assumption in plain words (e.g. "youth demobilization scenario") — stored on the lever's audit entry.
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-add_map_comment — Use add map comment
AI guidance for add_map_comment: Leave a Google-Docs-style COMMENT on the scenario map — a threaded, resolvable discussion anchored to a place. CAMPAIGN ISOLATION: when working inside a campaign, pass campaign_id; the scenario must be filed under it…
- audience_scope
- Who can read this discussion or assignment. Replies and work originating in a discussion inherit its audience.
- simulation_id
- Required for execution. Supply string as text; the guide includes the full tool schema.
- campaign_id
- Campaign that owns this War Room message. The simulation must be tagged into it. Omit only for scenario-global…
- body
- Required for execution. The comment text (supports @mentions by email/handle).
- idempotency_key
- Optional retry key. Replays return the same post and immutable context instead of duplicating the message.
- feature_id
- Anchor to this feature (5-digit county FIPS / precinct external_id / 2-digit state FIPS / district GEOID).
- level
- Feature anchor level (county|precinct|state|house|state_senate|state_assembly). Defaults to the sim level.
- lng
- Free-point anchor longitude (use with lat).
- lat
- Free-point anchor latitude (use with lng).
- parent_id
- Reply to this comment id (creates a thread; inherits the parent's anchor).
- attachments
- Attachments on the message: [{name,url,mime,size,object_path?,kind?}]. An UPLOADED FILE rides as the object_path…
- object
- Anchor the comment to an OBJECT (a strategy / strategy step / annotation / version / candidate / workspace person /…
- report_context
- Bind this discussion to the exact immutable report widget the user is viewing. The report and widget must belong to…
- canvass_kind
- Make this a color-coded FIELD-MAP PIN (Map View canvassing) instead of a plain comment: supporter (green) | voter…
- canvass_data
- Optional structured data for a field pin: { label, status, support_score, contacted_at, … } — anything your campaign…
- title
- Optional short name for the post (a strategy/target/event has one; plain chat does not — feeds fall back to a body…
- regions
- The post's MANY-TO-MANY location — the region/turf/shapefile ids this post covers (a multi-area comment's selected…
- region_kind
- What grain the regions[] ids are (precinct|county|state|district). Defaults to the anchor level.
- category
- UNIFIED WAR ROOM OBJECTS: what kind of floater this placement is. Every category shares the same anchor model and…
- icon_type
- The icon/subtype within the category — e.g. note: why|risk|fact|question; target: by role; canvass: the drop kind;…
- payload
- Category-specific structured fields, stored as-is. Examples — target: { priority, channel, universe_ref }; action: {…
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-list_map_comments — Use list map comments
AI guidance for list_map_comments: List one campaign's map comments on a scenario (oldest-first), each with its campaign_id, anchor, author, body, @mentions, parent_id, and resolved state. Pass campaign_id inside a campaign; only that exact campaign is…
- simulation_id
- Required for execution. Supply string as text; the guide includes the full tool schema.
- campaign_id
- Exact campaign War Room to read. The simulation must be filed under it.
- include_resolved
- Include resolved comments (default true).
- comment_ids
- Read only these comments (a delta after a live event named them). The reply carries subset:true plus missing[] for ids…
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-apply_uniform_swing — Use apply uniform swing
AI guidance for apply_uniform_swing: Apply an incremental swing in points toward one candidate at the requested office. A saved race_scope restricts writes to that state or district and refuses a different office or unresolved geography. Unscoped and…
- simulation_id
- Required for execution. Supply string as text; the guide includes the full tool schema.
- level
- Required for execution. Supply string as text; the guide includes the full tool schema.
- swing_pp
- Required for execution. Supply number as text; the guide includes the full tool schema.
- toward_candidate_id
- Supply string as text; the guide includes the full tool schema.
- decay_halflife
- Optional. Half-life in DAYS: past decay_start_date the applied swing halves every this-many days (exponential fade…
- decay_start_date
- YYYY-MM-DD the shift lands / peaks (decay measured forward from here). Default: today. Only used when decay_halflife…
- as_of
- YYYY-MM-DD timeline point at which to evaluate the decayed swing. Default: decay_start_date (full magnitude). Only…
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-get_tally — Use get tally
AI guidance for get_tally: Compute the current per-candidate tally for a simulation+level. For President: state-aggregated EVs. For others: feature counts. For level:"senate" the default is the 50-state per-candidate race scoreboard; pass…
- simulation_id
- Required for execution. Supply string as text; the guide includes the full tool schema.
- level
- Required for execution. Supply string as text; the guide includes the full tool schema.
- chamber
- level:"senate" only — return real chamber control ({D,R,I,seats_up,held_over,majority_status}) via the same math as…
- cycle
- Election cycle for chamber control (level:"senate", chamber:true); default 2028. Ignored otherwise.
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-list_simulations — Use list simulations
AI guidance for list_simulations: List saved simulations in this workspace (id, name, level, cycle, mode, contest_id, last-modified; rows stamped with an identity also carry created_by/updated_by member user_ids). Optional filters narrow a large…
- level
- Filter by office/level (e.g. president, senate, house, governor).
- mode
- Filter by president modeling mode: general | dem_primary_2028 | rep_primary_2028.
- cycle
- Filter by election cycle year (e.g. 2028).
- contest_id
- Filter to sims bound to this contest_id.
- race_id
- Filter to sims bound to this race_id.
- q
- Case-insensitive substring match on the simulation name.
- updated_since
- Only sims modified at or after this ISO timestamp/date.
- owner
- Filter to sims created by this member user_id (the stable UUID from list_members) — "my sims" / "Dana's sims". Sims…
- limit
- Max rows to return (pagination page size).
- offset
- Rows to skip before returning (pagination cursor).
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-get_simulation — Use get simulation
AI guidance for get_simulation: Read the canonical simulation/scenario state, including candidates, race scope, geography overrides, active version identity, provenance, and optional summary or selected dot-path fields.
- simulation_id
- Required for execution. Supply string as text; the guide includes the full tool schema.
- fields
- Optional read shaping: the string "summary" → the compact identity card (target <5KB); an array of dot-paths (e.g.…
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-list_flipped — Use list flipped
AI guidance for list_flipped: List baseline-to-model winner changes. Defaults to state for statewide offices, county for president, and district for house/state legislature. Explicit grain:county|precinct uses canonical integer local votes for a…
- simulation_id
- Required for execution. Supply string as text; the guide includes the full tool schema.
- level
- Required for execution. Supply string as text; the guide includes the full tool schema.
- grain
- Supply string as text; the guide includes the full tool schema.
- state
- One postal code/FIPS for explicit county/precinct enumeration; may be inferred from a saved state race.
- offset
- Supply integer as text; the guide includes the full tool schema.
- limit
- Supply integer as text; the guide includes the full tool schema.
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-compare_simulations — Use compare simulations
AI guidance for compare_simulations: Compare two simulations. Without grain, returns the existing chamber/feature comparison. With grain:county|precinct and one state, compares exact saved canonical vote rows: margin(B)-margin(A), winners, flips, ballots…
- simulation_id_a
- Required for execution. Supply string as text; the guide includes the full tool schema.
- simulation_id_b
- Required for execution. Supply string as text; the guide includes the full tool schema.
- campaign_id_a
- Optional campaign custody for A when the model belongs to multiple readable campaigns. Does not grant access.
- campaign_id_b
- Optional campaign custody for B when the model belongs to multiple readable campaigns. Does not grant access.
- version_a
- Difference comparison: exact saved version of A. Omit only when its latest version matches the live model.
- version_b
- Difference comparison: exact saved version of B. Omit only when its latest version matches the live model.
- expected_hash_a
- Optional expected immutable version hash for A; mismatches refuse.
- expected_hash_b
- Optional expected immutable version hash for B; mismatches refuse.
- state
- Required for county/precinct comparison: one state postal code or FIPS.
- grain
- Return canonical local outcomes instead of a chamber tally. county|precinct for president/statewide races;…
- format
- Local comparison table format; CSV/GeoJSON add a private complete-file download URL.
- limit
- Supply integer as text; the guide includes the full tool schema.
- offset
- Supply integer as text; the guide includes the full tool schema.
- level
- Required for execution. Supply string as text; the guide includes the full tool schema.
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-share_simulation — Use share simulation
AI guidance for share_simulation: Mint a public, read-only link to the exact canonical scenario/version. Authenticate for durable workspace ownership; revoke_share disables the link.
- simulation_id
- Required for execution. Supply string as text; the guide includes the full tool schema.
- campaign_id
- Optional campaign that contains this simulation. The share is authorized against that campaign and its frozen…
- ttl_days
- Supply integer as text; the guide includes the full tool schema.
- include_impact
- Include national impact only for an unscoped national model. Ignored for a single-race or primary scope.
- include_deltas
- Include modeled margin/share deltas from the canonical baseline for this exact race.
- sections
- Optional public-share section allowlist. Single-race shares remain race-scoped even when impact is requested.
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-roll_up_race — Use roll up race
AI guidance for roll_up_race: Roll up precincts to a race outcome under the current simulation. Sums baseline votes for all precincts inside the district boundary, applying overrides in precedence order: a per-precinct override wins, else…
- simulation_id
- Required for execution. Supply string as text; the guide includes the full tool schema.
- level
- Supply string as text; the guide includes the full tool schema.
- district_id
- District external id (for level=president/senate/governor, the state). EM-056: accepts a resolve_geography handle in…
- region_group
- Optional saved county-grain workspace map region-group slug. Returns one modeled race rollup per named region.
- region
- Optional — with region_group, scope to exactly ONE region in the group (its slug), rolling up only that region's…
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-apply_swing_to_query — Use apply swing to query
AI guidance for apply_swing_to_query: Apply a uniform swing or an explicit per-precinct weights vector to a filtered cohort in one atomic call. Weights select only their named IDs, support canonical statewide mechanisms, and optionally rescale a persuasion…
- simulation_id
- Required for execution. Supply string as text; the guide includes the full tool schema.
- state
- Required for execution. Postal, FIPS, or resolve_geography slug ("us-pa") — required, scopes the query (EM-056: all formats accepted; also…
- filter
- Required for execution. Precinct property → condition map within the requested geography. Properties: external_id, GEOID, name, state, county,…
- swing_pp
- Percentage-point swing toward the target candidate. mode:"turnout": the percent of each precinct's ballots added for…
- target_margin_pp
- Alternative to swing_pp: desired margin of the target party over the other major party, as a percentage of all modeled…
- weights
- Alternative to swing_pp: exact precinct external_id -> signed swing percentage points. Only these IDs change; all must…
- toward_candidate_id
- The candidate id receiving the swing (e.g. "D", "R", or a custom id). Inferred to the level's first candidate of…
- max_precincts
- Safety cap on how many precincts get mutated.
- level
- The office these swung precincts model — folds them into that race's state rollup (same tag as set_precinct_pcts).…
- mode
- HOW the swing happens (EM-008). persuasion = conversion (×2 margin, ballots hold); turnout = one-sided ballots (×1…
- mix
- mode:"mixed" only — the fraction of swing_pp delivered via persuasion (the rest via turnout).
- source
- mode calls that move ballots: stored on the lever's audit entry.
- assumption
- mode calls that move ballots: stored on the lever's audit entry.
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-get_campaign_onboarding — Use get campaign onboarding
AI guidance for get_campaign_onboarding: CAMPAIGN ONBOARDING — guide a campaign manager or joining staff member through setup in their connected AI. Read one step or the complete guide: connection, campaign identity, team access, optional data imports, first…
- section
- The next conversational step. Read connection first; all returns the complete guide when campaign tools are available.
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-help — Use help
AI guidance for help: Orient an AI client to campaign onboarding through get_campaign_onboarding, user-controlled election modeling, candidate and presidential-primary workflows, supported geography, scenario versions, contextual War Room…
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-get_catalog — Use get catalog
AI guidance for get_catalog: DISCOVERY — browse workflow/category groups, search tool names and descriptions, or fetch one complete schema and AI guide with tool. No arguments returns a compact counted index of the authorized inventory. Core…
- query
- Text search over this session's retained tool names and descriptions. Ranked: exact name, name substring, then…
- limit
- Maximum tool entries per discovery page, subject to the response byte budget. Repeat the same filters with next_cursor…
- cursor
- Opaque next_cursor from the previous discovery page. Keep the same query, category and workflow; restart if the…
- expected_catalog_version
- Optional catalog_version from a previous tools/list or get_catalog response. Returns catalog_changed so clients can…
- workflow
- Opt into a workflow from the compact index. Filters browsing or search within the authorized inventory; never grants…
- tool
- Exact retained tool name — returns the complete inputSchema and versioned AI guidance matching its use-<tool> MCP…
- category
- Browse one category (e.g. "Scenario") in bounded pages. The category count is the full matching inventory, not this…
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-list_primary_calendar — Use list primary calendar
AI guidance for list_primary_calendar: Read the 2028 primary calendar with source dates, schedule certainty, modeled delegate coverage, missing jurisdictions, and threshold basis. New calendars include the six DNC-approved early dates; other unverified…
- party
- Required for execution. Supply string as text; the guide includes the full tool schema.
- simulation_id
- Optional. If given (and party=D), returns the sim's user-defined Dem calendar when one is set.
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-set_primary_shares — Use set primary shares
AI guidance for set_primary_shares: Set a party's presidential-primary vote shares — one state, or MANY states in a single call. SINGLE STATE: pass `state` + `shares` (unchanged behavior; echoes the full running roll_up). BATCH: pass `states` = { "SC":…
- simulation_id
- Required for execution. Supply string as text; the guide includes the full tool schema.
- party
- Required for execution. Supply string as text; the guide includes the full tool schema.
- state
- SINGLE-STATE mode: State FIPS ("19") or 2-letter abbr ("IA"). Provide `state`+`shares` OR `states`, not both.
- shares
- SINGLE-STATE mode: Map of candidate_id → percentage (0-100), e.g. {"vance": 42, "desantis": 30}. Must reference…
- states
- BATCH mode: Map of state (FIPS or 2-letter abbr) → its {candidate_id: pct} shares, e.g.…
- include_rollup
- BATCH mode only: also return the full delegate roll_up alongside the default trimmed `delta` summary. Ignored in…
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-roll_up_primary — Use roll up primary
AI guidance for roll_up_primary: The running delegate count — OR, for a race-scoped downballot sim, that race's own share rollup. DOWNBALLOT (tk_2110d54c1d0871): when the scenario is race-scoped to a non-presidential office (set_race_scope…
- simulation_id
- Required for execution. Supply string as text; the guide includes the full tool schema.
- party
- Required for execution. Supply string as text; the guide includes the full tool schema.
- asof
- Optional. Contests counted; omit/null = full calendar.
- state
- Optional. Scope the read to ONE contest (postal/FIPS/name): returns a `state` block with that contest's calendar…
- include_states
- Optional. Also return by_state[]: per voted contest — delegates each candidate won, plus eff_shares (the effective…
- by_district
- Optional (Democratic only). Also return district_allocation: the SAME authoritative count broken out by DNC Rule 14…
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-primary_batch_edit — Use primary batch edit
AI guidance for primary_batch_edit: ATOMIC batch-edit transaction for a PRIMARY scenario — validate, preview, apply, and roll back a whole SET of candidate / share / calendar edits as ONE transaction. Pass edits:[{op, ...}, …] where each entry carries…
- setup_evidence
- For automatic public-profile initialization: {kind:"primary_profile_start",model:"geographic-context-v1",profile_versio…
- expected_version_hash
- Copy expected_version_hash from the setup dry run to refuse overwriting an intervening edit. Exact already-applied…
- simulation_id
- Required for execution. The scenario/simulation to edit (sim_…).
- edits
- Required for execution. Ordered heterogeneous list of primary edits, each an object {op, …opArgs}. op is one of set_primary_shares,…
- party
- Default party (d/r) for edits that omit their own party. Defaults to the sim's primary party.
- dry_run
- DEFAULT true — preview only: returns before/after/delta/warnings/errors/viability_flags and writes NOTHING. Pass false…
- force
- Apply despite soft WARNINGS (just-over-100 totals, viability flags, mode/geo/calendar notes). Still BLOCKS on hard…
- checkpoint_label
- Optional label for the pre-batch rollback checkpoint version created on apply.
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-set_race_scope — Use set race scope
AI guidance for set_race_scope: Bind the canonical scenario to one race/campaign so its map, tally, candidates, War Room context, operations, outputs, and MCP actions share the same race identity.
- simulation_id
- Required for execution. Supply string as text; the guide includes the full tool schema.
- office
- The office (seat) this race is for. This is the canonical parameter name; the older `level` is still accepted as an…
- level
- DEPRECATED alias for `office` (kept for back-compat). Prefer `office`.
- geography_id
- Accepts the canonical resolve_geography slug at every office — president "us" / "US"; senate & governor "us-pa", "PA",…
- candidate
- A candidate/officeholder name ("Lauren Boebert") — resolved via resolve_candidate to their office + geography + cycle,…
- cycle
- Supply integer as text; the guide includes the full tool schema.
- stage
- Supply string as text; the guide includes the full tool schema.
- candidates
- Optional array of real candidates running this race: [{id, name, party, color, incumbent?}]. Overwrites the office's…
- rebind
- Deliberately re-district a campaign already bound to a DIFFERENT geography. Without it, re-scoping a bound sim is…
- workspace_scope
- Optional workspace for THIS call: use an exact personal/team ID from list_workspaces. Repeat on each call; it does not…
use-call_tool — Use call tool
AI guidance for call_tool: Run any other tool you are authorized for that is not in this list. Find it and its exact input schema with get_catalog (search, a workflow, or {tool: name}), then call call_tool({ name, arguments }). The named tool…
- name
- Required for execution. The exact tool name, as get_catalog returns it.
- arguments
- That tool's arguments, exactly as its get_catalog schema describes.
Resources
Not advertised
30-day availability
Aggregated from read-only remote checks; this is not a tool-execution or security guarantee.
- Successful checks
- 1 of 1 (100%)
- Average latency
- 799 ms
- 95th percentile latency
- 799 ms
Maintenance history
Public check and source-refresh events. Editorial and ownership records remain private.
- · probe · passed · 799 ms · metadata changed · 48 tool(s), 55 prompt(s)
Connect from your client
Each snippet registers the same endpoint; pick the client you use.
Claude Code
Claude Code configuration
claude mcp add --transport sse electionsmcp https://www.electionsmcp.com/sseCline
Cline configuration
{
"mcpServers": {
"electionsmcp": {
"type": "sse",
"url": "https://www.electionsmcp.com/sse",
"disabled": false
}
}
}Gemini CLI
Gemini CLI configuration
gemini mcp add --transport sse electionsmcp https://www.electionsmcp.com/sseLet your agent find its tools
Find servers like ElectionsMCP from your agent. Add Koskamo once to search the index for endpoints, access requirements, and client setup. Public discovery needs no key.
Other data and analytics servers
Do you run ElectionsMCP?
Prove ownership with a DNS record, a well-known file, or your Official MCP Registry entry, and your edits publish immediately. Proofs are re-checked weekly; admins can still hide or remove a listing.