VoteMapper

View saved version →

---
name: history
description: Use when the user asks about a past US presidential election — how one went, what changed between two, how a single state has voted over time, or a what-if about a past result. Covers 1788 through 2024 with historical_map, compare_elections and analyze_state_history, and what this data does and does not hold.
---

# Presidential history, 1788–2024

Three tools, and the question decides which one:

| The user is asking about | Tool |
|---|---|
| One election — "show me 1984", "what happened in 1824" | `historical_map` |
| Two or more elections — "which states flipped in 2016", "compare the Obama and Trump maps" | `compare_elections` |
| One state over time — "has Georgia always been Republican", "is Virginia a swing state" | `analyze_state_history` |

Reach for the tool rather than answering from memory. The map is the point: a rendered
election is worth more than a paragraph reciting the same facts, and the reader can see
regional patterns you would have to spell out.

## The boundary, first

**This data holds electoral votes, not popular votes.** No year carries a margin, a vote
total or turnout. The tool can say Florida changed hands in 2000; it cannot say by how
much, and neither can you on the strength of it. If the user asks for a margin, say plainly
that the connector does not hold that and answer the part it does cover.

There is **no county-level data at all**. "Which counties shifted" is not a question these
tools can answer.

Electoral votes are counted **as appointed**, which includes electors whose votes were not
counted and faithless electors. That is why some tallies will not match a source that
counts only votes as cast.

## One election

`historical_map` takes a `year`. Presidential elections run every four years from 1788, so
1984 and 2020 are valid and 1985 and 2026 are not — 2026 is a midterm, and belongs to
`build_scenario`, not here.

**Report every candidate who took electors.** 1860 had four and 1912 had three; flattening
either into two parties loses the whole story. The tool returns them all, so quote them all.

For a what-if, pass `reassignments` — an array of `{ state, party }`, where `party` is a
code from the registry the tool returns (`D`, `R`, `W`, and so on). "What if Florida had
gone to Gore in 2000" is one reassignment, and the tool recomputes the tally against the
majority that year actually required. Say clearly that the result is a counterfactual.

## Two or more elections

`compare_elections` takes `years`, an array. It returns which states changed hands, which
were held throughout, and how many electors moved between parties.

Lead with what changed. "Six states flipped" is the answer; the list of the forty-four that
did not is context, not news. And note that a state changing hands is a fact about who
carried it, never about how close it was — see the boundary above.

## One state over time

`analyze_state_history` takes a two-letter `state` (DC is included), and optional `fromYear`
and `toYear` to window it. It returns every election the state took part in, who carried it,
its current run, and when each party last won it.

Two things worth getting right in the phrasing:

- **A streak is a streak, not a prediction.** "Republican in the last twelve" describes the
  record; it does not forecast the thirteenth.
- **States join the union.** A state's first election is when it first took part, not 1788.
  Do not describe a state as having "never" done something without saying since when.

## Staying even-handed

Both parties get the same treatment, in the same words. Parties also changed meaning
enormously across two centuries — the Democratic-Republicans of 1800 and the Democrats of
2020 are not the same thing, and a streak that crosses a realignment is a fact about a
label. Say so when it matters rather than implying continuity the data cannot support.

View saved version →

---
name: map
description: Use when the user describes a hypothetical outcome for the 2026 US Senate or House and wants to know what it does to control of the chamber — "what if Republicans sweep the toss-ups", "if Democrats hold Georgia and flip Texas, who has the Senate", "show me the House map if the leans all break one way". Translates the scenario into build_scenario parameters and reports the tally the tool returns, with an interactive chamber map.
---

# Build a scenario map

Turn the scenario the user described into a `build_scenario` call, then report what the
tool returns. **Do not do the seat arithmetic yourself, and do not guess at ratings you have
not read.** The same sentence produces different numbers as the ratings move — a race that
was a toss-up last month may be Lean D today, in which case "they lose it" changes nothing.

## Choosing the chamber

- The scenario names states → Senate. It names districts ("TX-18", "Texas 18th") → House.
- Genuinely ambiguous → ask which chamber rather than assume.
- The user asks for "the map" with no scenario → the Senate on the consensus baseline.

## Translating the scenario

| The user says | Parameter |
|---|---|
| "sweeps the toss-ups", "runs the table", "everything breaks their way" | `tossups: "democrat"` or `"republican"` |
| names individual races | `assignments`, e.g. `{ "race": "ME", "party": "democrat" }` |
| "from scratch", "a blank map" | `baseline: "empty"` (otherwise leave the consensus default) |
| wants a race left open | `{ "race": "...", "party": "none" }` |

Named races are applied last and win over the blanket toss-up rule.

> "Republicans hold every toss-up but lose North Carolina and Maine"

```json
{
  "chamber": "senate",
  "tossups": "republican",
  "assignments": [
    { "race": "NC", "party": "democrat" },
    { "race": "ME", "party": "democrat" }
  ]
}
```

## Reporting the result

- The tally, whether anyone reaches the number needed for control (51 in the Senate, 218
  in the House), and how many seats are still uncalled.
- The date the ratings were published.
- Everything in `unresolved`, said out loud. A tally for a scenario the user did not
  describe is worse than no tally.
- Independents are their own party. Never fold them into a majority, and never say a party
  holds the chamber unless it reaches the threshold on its own.

VoteMapper is a simulator. Ratings are forecasters' opinions about an election that has not
happened, so never describe a scenario's outcome as a result.

View saved version →

---
name: tossups
description: Use when the user asks which 2026 US Senate or House races are competitive, close, in play, battlegrounds, or toss-ups. Lists them with list_races_by_rating and reports the true total, not just the races the tool happened to name.
---

# List the races in play

Call `list_races_by_rating` with `rating: "competitive"`, which spans Lean D, Toss-up and
Lean R together. That is what "in play", "close" and "competitive" mean; `tossup` alone is
narrower than the question almost anyone is asking.

- If the user specifically asks for toss-ups only, call it with `rating: "tossup"` and say
  which of the two you are showing.
- If the user does not say which chamber, use the Senate and say that you did. Offer the
  House if it seems wanted.

## Reporting the result

- The **true total** the tool returns, not the number of races it named. The list can be
  capped; the total never is.
- The date the ratings were published.

A rating is a forecaster's opinion about a race that has not happened. Never phrase it as
though something has occurred in that state or district.

View saved version →

---
name: votemapper
description: Use when answering questions about US elections on a map — 2026 midterm race ratings, which races are competitive, what has changed in the forecast, what a described scenario does to control of a chamber, checking and scoring a sealed VoteMapper forecast, or any presidential election from 1788 to 2024. Covers the ratings taxonomy, the seat arithmetic, and what this data is and is not.
---

# VoteMapper

VoteMapper answers questions about US elections from published, dated datasets, and
answers them on a map.

**The 2026 midterms**: the consensus competitiveness rating for any Senate race or House
district, which races are genuinely in play, what forecasters have changed their minds
about, and what a described scenario does to control of a chamber.

**Presidential history, 1788–2024**: how any past election went, what changed between two
of them, and how a single state has voted over time. That half has its own skill — see
[history](../history/SKILL.md) for which of the three tools answers which question, and for
the boundary that matters most there: the historical data holds electoral votes, never
popular-vote totals, margins, turnout or anything at county level.

Which half a question belongs to is usually obvious from the year. 2026 is congressional
and belongs to `build_scenario`, `lookup_race` and `list_races_by_rating`; a presidential
year is historical. Nothing here covers 2028 — there is no forecast for an election with no
ratings published, and saying so is the right answer.

## The boundary, first

**VoteMapper is a simulator. It never reports live vote counts, returns, or called races.**

A rating is a forecaster's opinion about a race that has not happened. A rating moving from
Lean R to Toss-up is Cook and Sabato revising their view — it is not a result, and saying
"North Carolina moved to Toss-up" must never be phrased as though something happened in
North Carolina.

The one exception is `score_forecast`, which reads race calls published from the Associated
Press in order to score a sealed forecast. Even there, the tool reports whether a forecast's
picks were right; it does not report vote totals and calls nothing itself. For live results,
use a results source.

## The ratings taxonomy

Seven ratings, one scale, safest Democratic to safest Republican:

`safeD` · `likelyD` · `leanD` · `tossup` · `leanR` · `likelyR` · `safeR`

- **Competitive** means `leanD`, `tossup` and `leanR` together. When someone asks which
  races "matter", "are in play" or "are close", that is the filter they want — not `tossup`
  alone, which is narrower than the question.
- **A toss-up has no favourite.** It is not a half-seat for each party and it is not a lean.
  Under a consensus baseline it stays uncalled.
- Ratings are a **consensus of Cook Political Report and Sabato's Crystal Ball**, and every
  answer carries the date they were published. Quote that date; a rating without one invites
  the reader to assume it is current when it may not be.

## The seat arithmetic

This is the part worth deferring to the tools rather than doing in your head.

**The Senate has 100 seats and only 35 are on the 2026 ballot.** The other 65 are held over
and already counted — 32 Democratic, 31 Republican and 2 independent as of the current data.
A Senate tally built from the contested races alone is wrong by 65 seats. Control needs 51.

**The House is all 435 districts**, every one on the ballot, and control needs 218. Most
districts are not individually rated: an unrated district is treated as safe for whoever
holds it, which is why the House map is nearly full before anyone calls anything.

**Independents are their own party.** Two sitting senators are independents. Do not fold
them into a party's total, and do not describe a party as holding the chamber unless it
reaches the threshold on its own.

## Turning a sentence into a scenario

`build_scenario` exists because models read scenarios well and count them badly. Your job is
the translation; let the tool do the arithmetic and quote what it returns.

> "Republicans hold every toss-up but lose North Carolina and Maine"

```json
{
  "chamber": "senate",
  "tossups": "republican",
  "assignments": [
    { "race": "NC", "party": "democrat" },
    { "race": "ME", "party": "democrat" }
  ]
}
```

The pieces:

- `baseline` — `consensus` (default) starts every race at its forecaster favourite and
  leaves toss-ups uncalled. `empty` starts from an uncalled map.
- `tossups` — hands every toss-up to one party. Use it for "sweeps the toss-ups", "runs the
  table", "everything breaks their way".
- `assignments` — individual races, applied last, beating the blanket rule. `"none"` returns
  a race to uncalled.

**Do not compute the result yourself.** The same sentence produces different arithmetic as
ratings move: a race that was a toss-up last month may be Lean D today, in which case
"they lose it" changes nothing. The tool resolves against the ratings in effect; you do not
know them.

Races are addressed by id or name: `GA` and `TX-18`, or `Georgia Senate` and `Texas 18th`.
Anything the tool could not apply comes back in `unresolved` — say so rather than reporting
a tally for a scenario the user did not describe.

## Sealed forecasts

A user can declare a forecast in the VoteMapper app, which seals it with a SHA-256
fingerprint. `verify_forecast` says whether a fingerprint is on the record and what it was
sealed over; `score_forecast` scores it against published calls.

**Accuracy is counted over called races only.** An uncalled race is not a miss. Before
election night there is nothing to score, and the honest answer is that — never a zero.

**Sealing happens in the app.** These tools read the registry; they cannot create or seal a
forecast, and you should not imply otherwise.

## Staying even-handed

Both parties are treated symmetrically by the data and should be by you. Use both directions
in examples, attach no adjectives to either party's position, and let the numbers carry the
answer. Every rating is sourced and dated; say where it came from.

View saved version →

---
name: whatchanged
description: Use when the user asks what has changed, moved, or shifted in the 2026 US midterm race ratings or forecast — "what's new in the forecast", "which races moved", "any rating changes lately". Compares published revisions of the data with ratings_changed.
---

# Show what moved in the forecast

Call `ratings_changed`. With no arguments it compares the two most recent published
revisions. If the user names revisions, pass them as `fromRevision` and `toRevision`.

## Reporting the result

- Lead with the biggest moves. A Safe seat becoming a Toss-up is the news; a one-notch
  drift is not. The tool already returns them in that order.
- If nothing moved, say so plainly. That is a real answer, and a common one between
  revisions.

Say exactly what a change is: **a forecaster revised their view of a race that has not
happened.** Never write it as though something happened in that state or district.