Model and map any 2028 U.S. race down to the precinct: scenarios, swing, turnout, and roll-ups.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Optional API key. Without a key you get a free read/simulate sandbox; with a key, simulations save to your durable tier. Get one by signing in at https://www.electionsmcp.com.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
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…
The comment text (supports @mentions by email/handle).
Free-point anchor latitude (use with lng).
Free-point anchor longitude (use with lat).
Feature anchor level (county|precinct|state|house|state_senate|state_assembly). Defaults to the sim level.
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.
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.
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 }.
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.
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.
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.
Reply to this comment id (creates a thread; inherits the parent's anchor).
Anchor to this feature (5-digit county FIPS / precinct external_id / 2-digit state FIPS / district GEOID).
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 that owns this War Room message. The simulation must be tagged into it. Omit only for scenario-global discussion.
What grain the regions[] ids are (precinct|county|state|district). Defaults to the anchor level.
Optional structured data for a field pin: { label, status, support_score, contacted_at, … } — anything your campaign tracks per pin.
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.
Who can read this discussion or assignment. Replies and work originating in a discussion inherit its audience.
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.
Optional retry key. Replays return the same post and immutable context instead of duplicating the message.
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.
The server marks this tool as destructive. Running it may delete or overwrite data on the server or in any account you connected with your headers.
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…
| Argument | Type | Description |
|---|---|---|
| lat | number | Free-point anchor latitude (use with lng). |
| lng | number | Free-point anchor longitude (use with lat). |
| body* | string | The comment text (supports @mentions by email/handle). |
| level | string | Feature anchor level (county|precinct|state|house|state_senate|state_assembly). Defaults to the sim level. |
| title | string | 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 | object | 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. |
| payload | object | 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 | array | 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 | string | 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 | string | 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 | string | Reply to this comment id (creates a thread; inherits the parent's anchor). |
| feature_id | string | Anchor to this feature (5-digit county FIPS / precinct external_id / 2-digit state FIPS / district GEOID). |
| attachments | array | 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 | string | Campaign that owns this War Room message. The simulation must be tagged into it. Omit only for scenario-global discussion. |
| region_kind | string | What grain the regions[] ids are (precinct|county|state|district). Defaults to the anchor level. |
| canvass_data | object | Optional structured data for a field pin: { label, status, support_score, contacted_at, … } — anything your campaign tracks per pin. |
| canvass_kind | string | 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* | string | |
| audience_scope | object | Who can read this discussion or assignment. Replies and work originating in a discussion inherit its audience. |
| report_context | object | 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. |
| idempotency_key | string | Optional retry key. Replays return the same post and immutable context instead of duplicating the message. |
| workspace_scope | string | 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. |
{
"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
}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…
| Argument | Type | Description |
|---|---|---|
| mix | number | mode:"mixed" only — the fraction of swing_pp delivered via persuasion (the rest via turnout). |
| mode | string | 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 | string | 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* | string | Postal, FIPS, or resolve_geography slug ("us-pa") — required, scopes the query (EM-056: all formats accepted; also fills from geo_id). |
| filter* | object | 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. |
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…
| Argument | Type | Description |
|---|---|---|
| as_of | string | 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* | string | |
| swing_pp* | number | |
| simulation_id* | string | |
| decay_halflife | number | 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). |
| workspace_scope | string | 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. |
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,…
| Argument | Type | Description |
|---|---|---|
| workspace_scope | string | 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. |
{
"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
}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…
| Argument | Type | Description |
|---|---|---|
| name* | string | The exact tool name, as get_catalog returns it. |
| arguments | object | That tool's arguments, exactly as its get_catalog schema describes. |
{
"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
}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`…
| Argument | Type | Description |
|---|---|---|
| title | string | 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 | string | Human-readable note on what changed, e.g. "Flipped Orange County to D+40". |
| insight_ids | array | Optional — insight ids (ins_…) this version explains. Validated against the sim's insights; unknown ids are reported in `unlinked` and dropped. |
| scenario_id* | string | |
| include_diff | boolean | 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 | array | 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 |
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…
| Argument | Type | Description |
|---|---|---|
| grain | string | Return canonical local outcomes instead of a chamber tally. county|precinct for president/statewide races; district|precinct for House and state-legislative races. |
| level* | string | |
| limit | integer | |
| state | string | Required for county/precinct comparison: one state postal code or FIPS. |
| format | string | Local comparison table format; CSV/GeoJSON add a private complete-file download URL. |
| offset | integer | |
| version_a | string | Difference comparison: exact saved version of A. Omit only when its latest version matches the live model. |
| version_b | string | Difference comparison: exact saved version of B. Omit only when its latest version matches the live model. |
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…
| Argument | Type | Description |
|---|---|---|
| workspace_scope | string | 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. |
{
"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
}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…
| Argument | Type | Description |
|---|---|---|
| name* | string | |
| tags | array | |
| race_id | string | Optional; the Race this scenario belongs to. |
| contest_id | string | Optional; sets the scenario's race_scope from a canonical contest_id. |
| baseline_id | string | 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 | string | Custom campaign to model inside its exact attached city boundary. |
| import_from | string | Optional; copy overrides+candidates from an existing scenario_id. |
| idempotency_key | string | 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. |
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…
| Argument | Type | Description |
|---|---|---|
| limit | integer | Maximum changed precinct cells in this page. Summary counts cover the full version pair. |
| offset | integer | Use precinct_page.next_offset to continue in stable precinct-id order. |
| version_a* | string | |
| version_b* | string | |
| scenario_id* | string | |
| workspace_scope | string | 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. |
{
"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
}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…
| Argument | Type | Description |
|---|---|---|
| cycle | integer | Defaults to the next election year from today. |
| state | string | Postal abbreviation ("PA") for the per-state 4-year horizon; omit for the national summary. |
| workspace_scope | string | 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. |
{
"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
}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…
| Argument | Type | Description |
|---|---|---|
| section | string | The next conversational step. Read connection first; all returns the complete guide when campaign tools are available. |
| workspace_scope | string | 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. |
{
"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
}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…
| Argument | Type | Description |
|---|---|---|
| tool | string | 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 | integer | Maximum tool entries per discovery page, subject to the response byte budget. Repeat the same filters with next_cursor as cursor until null. |
| query | string | Text search over this session's retained tool names and descriptions. Ranked: exact name, name substring, then description matches. |
| cursor | string | Opaque next_cursor from the previous discovery page. Keep the same query, category and workflow; restart if the authorized catalog changed. |
| category | string | Browse one category (e.g. "Scenario") in bounded pages. The category count is the full matching inventory, not this page length. |
| workflow | string | Opt into a workflow from the compact index. Filters browsing or search within the authorized inventory; never grants access or changes the connection 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,…
| Argument | Type | Description |
|---|---|---|
| fips | string | 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 | string | Sort field when ranking counties in a state (default avg_annual_wage_usd). |
| limit | integer | Maximum counties to return when ranking a state (default 50, max 200). |
| state | string | Optional two-letter state code (e.g. "CA", "TX", "NY") to rank counties across a state. |
| offset | integer | Pagination offset (default 0). |
| workspace_scope | string | 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. |
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.
| Argument | Type | Description |
|---|---|---|
| q | string | Optional name or title search query. |
| fips | string | Optional 5-digit county FIPS code (e.g. "48201" for Harris County TX, "17031" for Cook County IL). |
| limit | integer | Maximum officials to return (default 100, max 200). |
| party | string | Optional party filter. |
| state | string | Optional two-letter state code (e.g. "TX", "IL", "CA"). |
| offset | integer | Pagination offset (default 0). |
| office_level | string | Optional office level filter. |
| workspace_scope | string | 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. |
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 all…
| Argument | Type | Description |
|---|---|---|
| sort | string | Sort order (default ballots_cast_2024). |
| tier | string | Optional competitiveness tier filter. |
| limit | integer | Maximum counties to return (default 100, max 500). |
| state | string | Optional two-letter state code (e.g. "PA", "GA", "NC", "MI", "WI", "AZ", "NV", "TX"). |
| offset | integer | Pagination offset (default 0). |
| county_fips | string | Optional 5-digit county FIPS code (e.g. "37183" for Wake NC, "04013" for Maricopa AZ). |
| workspace_scope | string | 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. |
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…
| Argument | Type | Description |
|---|---|---|
| state* | string | Two-letter state postal code (e.g. "TX", "NC", "GA", "FL", "PA", "MI", "AZ"). |
| office | string | Optional office substring filter (e.g. "U.S. Senate", "Governor"). |
| district | string | Optional district code filter for legislative or congressional races (e.g. "10", "11"). |
| source_id | string | Optional 64-character SHA-256 source identifier for a specific county/state return file. |
| county_fips | string | Optional 5-digit county FIPS code (e.g. "48081", "37021") to scope returns and turnout to one county. |
| office_level | string | Optional canonical office level filter. |
| election_date | string | 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. |
Read live 2026-11-03 General Election pre-election mail ballot requests, mail ballots returned, early in-person ballots, and partisan ballot composition (DEM vs. REP vs. UNA/Other) compared against each county’s 2024…
| Argument | Type | Description |
|---|---|---|
| limit | integer | Maximum county rows to return (default 100, max 500). |
| state | string | Optional two-letter state code (e.g. "NC", "VA", "GA", "PA"). |
| offset | integer | Pagination offset (default 0). |
| county_fips | string | Optional 5-digit county FIPS code (e.g. "37183"). |
| election_date | string | Election date in YYYY-MM-DD format (default "2026-11-03"). |
| workspace_scope | string | 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. |
{
"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."
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| year | integer | Optional election year (e.g. 2024, 2022, 2026). |
| limit | integer | Maximum rows to return (default 100, max 500). |
| party | string | Optional party filter. |
| state | string | Two-letter state postal code (e.g. "TX", "NC", "GA", "PA"). |
| office | string | Optional office name filter. |
| offset | integer | Pagination offset (default 0). |
| district | string | Optional legislative or congressional district code. |
| contest_id | integer | Optional RoutPoint contest identifier for single-contest precinct returns. |
| county_fips | string |
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…
| Argument | Type | Description |
|---|---|---|
| version_id | string | Optional; defaults to the latest version. When set, the response includes the full per-precinct `state` for that version. |
| scenario_id* | string | |
| include_state | boolean | Include the full per-precinct `state` even for the latest version (for redrawing the map). |
| workspace_scope | string | 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 | string | Optional exact content hash from list_scenario_versions. Requires version_id; a mismatch is refused rather than returning a different saved model. |
{
"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
}Read the canonical simulation/scenario state, including candidates, race scope, geography overrides, active version identity, provenance, and optional summary or selected dot-path fields.
| Argument | Type | Description |
|---|---|---|
| fields | any | 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* | string | |
| workspace_scope | string | 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. |
{
"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
}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…
| Argument | Type | Description |
|---|---|---|
| year | integer | Optional election year filter (1976 through 2026). |
| limit | integer | Maximum rows to return (default 100, max 500). |
| state | string | Optional two-letter state code (e.g. "PA", "GA", "MI", "WI", "CA", "TX"). |
| offset | integer | Pagination offset (default 0). |
| workspace_scope | string | 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. |
{
"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
}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…
| Argument | Type | Description |
|---|---|---|
| cycle | integer | Election cycle for chamber control (level:"senate", chamber:true); default 2028. Ignored otherwise. |
| level* | string | |
| chamber | boolean | 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* | string | |
| workspace_scope | string | 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. |
{
"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
}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…
| Argument | Type | Description |
|---|---|---|
| view | string | 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 | integer | |
| grain | string | 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 | string | 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 | string | 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). |
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…
| Argument | Type | Description |
|---|---|---|
| workspace_scope | string | 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. |
{
"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
}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…
| Argument | Type | Description |
|---|---|---|
| cycle | integer | Defaults to the next election year from today. |
| stage | string | primary selects the dem_primary and rep_primary variants; general excludes them; all returns both. |
| geo_id* | string | "us" (national), a state as "us-pa" / postal "PA" / FIPS "42", or a district id — all accepted. |
| workspace_scope | string | 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. |
{
"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 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…
| Argument | Type | Description |
|---|---|---|
| grain | string | |
| level* | string | |
| limit | integer | |
| state | string | One postal code/FIPS for explicit county/precinct enumeration; may be inferred from a saved state race. |
| offset | integer | |
| simulation_id* | string | |
| workspace_scope | string | 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. |
{
"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 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…
| Argument | Type | Description |
|---|---|---|
| campaign_id | string | Exact campaign War Room to read. The simulation must be filed under it. |
| comment_ids | array | 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* | string | |
| workspace_scope | string | 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 | boolean | Include resolved comments (default true). |
{
"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
}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…
| Argument | Type | Description |
|---|---|---|
| party* | string | |
| simulation_id | string | Optional. If given (and party=D), returns the sim's user-defined Dem calendar when one is set. |
| workspace_scope | string | 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. |
{
"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
}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…
| Argument | Type | Description |
|---|---|---|
| tags | array | Return only scenarios carrying any of these tags. |
| limit | integer | |
| offset | integer | 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 | string | 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. |
{
"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 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…
| Argument | Type | Description |
|---|---|---|
| q | string | Case-insensitive substring match on the simulation name. |
| mode | string | Filter by president modeling mode: general | dem_primary_2028 | rep_primary_2028. |
| cycle | integer | Filter by election cycle year (e.g. 2028). |
| level | string | Filter by office/level (e.g. president, senate, house, governor). |
| limit | integer | Max rows to return (pagination page size). |
| owner | string | 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 | integer | Rows to skip before returning (pagination cursor). |
| race_id | string | Filter to sims bound to this race_id. |
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.…
| Argument | Type | Description |
|---|---|---|
| address* | string | 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 | string | 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 | boolean | Attach the sitting officeholder for each resolved seat (from the committed legislator file). |
{
"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
}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…
| Argument | Type | Description |
|---|---|---|
| edits* | array | 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 | boolean | 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 | string | Default party (d/r) for edits that omit their own party. Defaults to the sim's primary party. |
| dry_run | boolean | DEFAULT true — preview only: returns before/after/delta/warnings/errors/viability_flags and writes NOTHING. Pass false to actually apply. |
| simulation_id* | string | The scenario/simulation to edit (sim_…). |
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,…
| Argument | Type | Description |
|---|---|---|
| asof | integer | null | 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* | string | 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 | integer | Election cycle for seat_hemicycle / decisive_seats (defaults to the sim's cycle, else 2026) — drives the Senate class + governor calendar. |
| level | string |
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…
| Argument | Type | Description |
|---|---|---|
| asof | integer | null | 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 | string | "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 | string | 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. |
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…
| Argument | Type | Description |
|---|---|---|
| name* | string | 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 | integer | Optional — keep only matches whose next_race is in this cycle (e.g. 2026). |
| limit | integer | Max people to return when a name is ambiguous (default 8). |
| party | string | Optional — keep only matches of this party (D/R/I), normalized by leading letter. For a stage/party-scoped picker. |
| office | string | 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 | string | 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. |
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…
| Argument | Type | Description |
|---|---|---|
| year | integer | Disambiguates post-redistricting boundaries; defaults to current cycle. |
| query* | string | "CA-03", "El Dorado County CA", "the 4th state senate district in California", "Pennsylvania" |
| workspace_scope | string | 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. |
{
"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
}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…
| Argument | Type | Description |
|---|---|---|
| asof | integer | null | Optional. Contests counted; omit/null = full calendar. |
| party* | string | |
| state | string | 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 | boolean | 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* | string | |
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…
| Argument | Type | Description |
|---|---|---|
| level | string | |
| region | string | Optional — with region_group, scope to exactly ONE region in the group (its slug), rolling up only that region's member counties. |
| district_id | string | 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 | string | Optional saved county-grain workspace map region-group slug. Returns one modeled race rollup per named region. |
| simulation_id* | string | |
| workspace_scope | string | 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. |
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:…
| Argument | Type | Description |
|---|---|---|
| q | string | Optional — case-insensitive substring on the candidate name or any alias (typeahead). |
| limit | integer | Max results (default 50). `total` reports the full match count; `truncated:true` when the list was trimmed. |
| party | string | Optional — only this party (D/R/I/L/G), normalized by leading letter. |
| office | string | 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 | string | 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. |
{
"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
}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…
| Argument | Type | Description |
|---|---|---|
| level* | string | |
| candidates* | array | |
| simulation_id* | string | |
| workspace_scope | string | 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 | string | The last-read updated_at token; custom model writes refuse stale edits. |
{
"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 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…
| Argument | Type | Description |
|---|---|---|
| level | string | 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* | string | |
| margin | number | Shorthand for two-candidate D−R margin in points; sets D/R shares around 50. |
| shares* | object | candidate_id → share. Accepts 0–1 or 0–100. |
| turnout | number | 0–1 expected turnout (stored as metadata on precinct overrides). |
| rebalance | string |
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":…
| Argument | Type | Description |
|---|---|---|
| party* | string | |
| state | string | SINGLE-STATE mode: State FIPS ("19") or 2-letter abbr ("IA"). Provide `state`+`shares` OR `states`, not both. |
| shares | object | 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 | object | 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* | string | |
| include_rollup | boolean | 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 |
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.
| Argument | Type | Description |
|---|---|---|
| cycle | integer | |
| level | string | DEPRECATED alias for `office` (kept for back-compat). Prefer `office`. |
| stage | string | |
| office | string | The office (seat) this race is for. This is the canonical parameter name; the older `level` is still accepted as an alias. |
| rebind | boolean | 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 | string | 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 | array | Optional array of real candidates running this race: [{id, name, party, color, incumbent?}]. Overwrites the office's candidate list. If omitted, keeps existing candidates. |
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%…
| Argument | Type | Description |
|---|---|---|
| clear | boolean | 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 | number | |
| level | string | president (default) = the classic ACS-threshold dials below. Any other level = the race-scoped ballots lever (turnout_change_pct + cohort). |
| source | string | Where this user-authored assumption came from (user statement, field report, or source citation) — stored on the lever's audit entry. |
| college | number | |
| geo_ids | array | 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. |
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…
| Argument | Type | Description |
|---|---|---|
| asof | integer | null | 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 | string | Which right-rail panel the viewer should have open. |
| zoom | number | Optional camera zoom; omit to fit the geo's bounds. |
| cycle | integer | |
| level | string | The map/level the view should show. |
| stage | string | 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 | string | Postal code or 2-digit FIPS to scope to (pass empty string to clear to the national view). |
| layers |
Mint a public, read-only link to the exact canonical scenario/version. Authenticate for durable workspace ownership; revoke_share disables the link.
| Argument | Type | Description |
|---|---|---|
| sections | array | Optional public-share section allowlist. Single-race shares remain race-scoped even when impact is requested. |
| ttl_days | integer | |
| campaign_id | string | Optional campaign that contains this simulation. The share is authorized against that campaign and its frozen context/manifest retain the campaign id. |
| simulation_id* | string | |
| include_deltas | boolean | Include modeled margin/share deltas from the canonical baseline for this exact race. |
| include_impact | boolean | Include national impact only for an unscoped national model. Ignored for a single-race or primary scope. |
| workspace_scope | string | 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. |
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…
| Argument | Type | Description |
|---|---|---|
| limit | integer | |
| filter | object | 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 | string | 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. |
| source | string | mode calls that move ballots: stored on the lever's audit entry. |
| weights | object | 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. |
| swing_pp | number | Percentage-point swing toward the target candidate. mode:"turnout": the percent of each precinct's ballots added for the target side. |
| assumption | string | mode calls that move ballots: stored on the lever's audit entry. |
| max_precincts | integer | Safety cap on how many precincts get mutated. |
| simulation_id* | string |
| workspace_scope | string | 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 | number | 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 | string | 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. |
{
"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
}| decay_start_date |
| string |
| YYYY-MM-DD the shift lands / peaks (decay measured forward from here). Default: today. Only used when decay_halflife is set. |
| toward_candidate_id | string |
{
"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
}| string |
| 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. |
{
"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
}| campaign_id_a | string | Optional campaign custody for A when the model belongs to multiple readable campaigns. Does not grant access. |
| campaign_id_b | string | Optional campaign custody for B when the model belongs to multiple readable campaigns. Does not grant access. |
| expected_hash_a | string | Optional expected immutable version hash for A; mismatches refuse. |
| expected_hash_b | string | Optional expected immutable version hash for B; mismatches refuse. |
| simulation_id_a* | string |
| simulation_id_b* | string |
| workspace_scope | string | 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. |
{
"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
}| workspace_scope | string | 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 | string |
| expected_campaign_revision | integer |
{
"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
}| workspace_scope |
| string |
| 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 | string | 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. |
{
"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
}{
"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
}{
"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
}{
"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
}| election_type |
| string |
| Optional election stage filter. |
| workspace_scope | string | 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 | boolean | When true, include per-precinct early voting, mail, election-day, and turnout breakdowns inside each race. |
{
"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
}| Optional 5-digit county FIPS code. |
| election_id | integer | Optional RoutPoint election identifier. |
| office_level | string | Optional canonical office level. |
| election_date | string | Optional election date in YYYY-MM-DD format. |
| election_type | string | Optional election stage (default general). |
| workspace_scope | string | 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 | string | Optional MapsMCP precinct UUID filter. |
{
"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
}| version_a | string | Difference comparison: exact saved version of A. Omit only when its latest version matches the live model. |
| version_b | string | Difference comparison: exact saved version of B. Omit only when its latest version matches the live model. |
| version_id | string | Exact saved version for a custom city model. |
| campaign_id_a | string | Optional campaign custody for A when the model belongs to multiple readable campaigns. Does not grant access. |
| campaign_id_b | string | Optional campaign custody for B when the model belongs to multiple readable campaigns. Does not grant access. |
| simulation_id* | string |
| expected_hash_a | string | Optional expected immutable version hash for A; mismatches refuse. |
| expected_hash_b | string | Optional expected immutable version hash for B; mismatches refuse. |
| workspace_scope | string | 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 | number | 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. |
| compare_simulation_id | string | 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 | string |
{
"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
}| contest_id |
| string |
| Filter to sims bound to this contest_id. |
| updated_since | string | Only sims modified at or after this ISO timestamp/date. |
| workspace_scope | string | 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. |
{
"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
}| setup_evidence |
| object |
| 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 | string | 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 | string | Optional label for the pre-batch rollback checkpoint version created on apply. |
| expected_version_hash | string | Copy expected_version_hash from the setup dry run to refuse overwriting an intervening edit. Exact already-applied replay returns the existing version. |
{
"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
}| share_comparison only: statewide office; defaults to the saved scope. Both versions must match office, state, cycle and general-election stage. |
| party | string | For the primary charts — which party's race (defaults to the sim's primary mode). |
| share | boolean | 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 | string | State postal or FIPS. Required for share_comparison and state-leg seat_hemicycle/decisive_seats. |
| style | object | Optional brand overrides for the supported themed charts. Does not remove attribution or change candidate colors or model data. |
| theme | string | Chart audience palette, using the map-theme registry. Supported by primary charts, swing_bars and chamber_control. Default control. |
| title | string | Optional eyebrow/title for the chart. |
| clinch | boolean | 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 | string | Image format. Default svg (png needs the resvg renderer; degrades to svg if absent). |
| office | string | For seat_hemicycle / decisive_seats — which chamber (default house). state_senate/state_assembly also need state. |
| version_a | string | Difference comparison: exact saved version of A. Omit only when its latest version matches the live model. |
| version_b | string | Difference comparison: exact saved version of B. Omit only when its latest version matches the live model. |
| overlay_race | object | 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. |
| campaign_id_a | string | Optional campaign custody for A when the model belongs to multiple readable campaigns. Does not grant access. |
| campaign_id_b | string | Optional campaign custody for B when the model belongs to multiple readable campaigns. Does not grant access. |
| simulation_id | string | Scenario to render; for share_comparison this is A, or the single model with version_a/version_b. |
| highlight_race | object | 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. |
| share_ttl_days | number | Days the shared URL stays live (default 90, max 365). Only with share:true. |
| expected_hash_a | string | Optional expected immutable version hash for A; mismatches refuse. |
| expected_hash_b | string | Optional expected immutable version hash for B; mismatches refuse. |
| simulation_id_a | string | share_comparison only: A model, alternative to simulation_id. Conflicting aliases refuse. |
| simulation_id_b | string | share_comparison only: B model in the same contest. Omit for two explicit versions of A. |
| workspace_scope | string | 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 | string | share_comparison only: alias for simulation_id_b. |
| context_simulation_id | string | 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 | string | 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). |
{
"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
}| level | string | 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 | boolean | 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 | string | 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 | string | 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 | string | CUSTOM MAP: a title for the card (e.g. "Rust Belt swing"). Defaults to the state list (or the region group / region name). |
| format | string | Image format. Default svg (png needs the resvg renderer on the host; degrades to svg if absent). |
| geo_id | string | Optional — a geo slug like "us-nc" to scope to that state. |
| layers | object | 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. |
| region | string | CUSTOM MAP — with region_group, render exactly ONE region in the group (its slug). |
| states | array | 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 | array | 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 | string | Difference comparison: exact saved version of A. Omit only when its latest version matches the live model. |
| version_b | string | Difference comparison: exact saved version of B. Omit only when its latest version matches the live model. |
| feature_id | string | Optional — a state fips (37) or county/precinct id (37xxx) to scope to its state. |
| region_group | string | 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 | string | Optional campaign custody for A when the model belongs to multiple readable campaigns. Does not grant access. |
| campaign_id_b | string | Optional campaign custody for B when the model belongs to multiple readable campaigns. Does not grant access. |
| simulation_id* | string |
| share_ttl_days | number | Days the shared URL stays live (default 90, max 365). Only with share:true. |
| expected_hash_a | string | Optional expected immutable version hash for A; mismatches refuse. |
| expected_hash_b | string | Optional expected immutable version hash for B; mismatches refuse. |
| workspace_scope | string | 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 | string | 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 | number | 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. |
| compare_simulation_id | string | 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. |
{
"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
}{
"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
}| include_states |
| boolean |
| 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 | string | 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. |
{
"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
}{
"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
}| scenario_id* | string | The simulation_id (scenario_id alias until the scenario model lands). |
| total_votes | integer | 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 | string |
| workspace_scope | string | 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 | string | 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. |
{
"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
}| string |
| 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. |
{
"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
}| geography_id | string | 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* | string |
| workspace_scope | string | 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. |
{
"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
}| hiUnemp | number |
| lowHome | number |
| counties | array | Alias of geo_ids for county cohorts. |
| highHome | number |
| criterion | object | 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. |
| assumption | string | The modeling assumption in plain words (e.g. "youth demobilization scenario") — stored on the lever's audit entry. |
| state_fips | string | 2-digit state FIPS to scope a criterion cohort to one state (e.g. "23" = Maine). |
| simulation_id* | string |
| workspace_scope | string | 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 | number | 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 | string |
{
"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
}| object |
| View toggles such as precincts/highlights plus the canonical "actuals:pres_2024" baseline layer. |
| source | string | 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 | string | 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 | string | The Map View grain toggle: states | counties | precincts (singular accepted, stored plural). |
| map_theme | string | 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 | object | 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. |
| camera_geo_id | string | Optional geo to frame the camera on (defaults to the scoped state). 2-digit state / 5-digit county / district GEOID / precinct id. |
| contest_index | integer | Playhead targeting by 1-based calendar ordinal (list_primary_calendar order). |
| simulation_id* | string |
| workspace_scope | string | 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. |
{
"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
}{
"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
}| margin | number | plurality: win by at least this many votes. |
| offset | integer | Page start; pass next.offset from the prior result with the same scope and filters. |
| context | string | Free-text constraints, echoed back (e.g. "field ops in Orange and Durham only"). |
| goal_mode | string | plurality = beat the leading opponent (default); majority = 50.01% share; share = explicit target_pct. |
| target_pct | number |
| scenario_id* | string | The scenario/simulation handle (EM-056: simulation_id is accepted as an alias). |
| candidate_id | string |
| rolloff_rate | number | Explicit roll-off rate (see compute_vote_goal). |
| workspace_scope | string | 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. |
{
"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
}