# MCP tools and prompts

**For:** anyone connecting an AI assistant, and self-hosters who want to know what it can reach. **At the end:** you know every tool the server lists, what each answers, its arguments, and the prompts.

<!-- Generated by tools/manual/generate.py from the MCP server's own registry (what `/mcp` lists). Edit the source, then run `uv run python tools/manual/generate.py`. tests/test_manual.py fails while this is stale. -->

Your assistant reads this list from the server by itself, with every argument described. You don't need to name tools: ask in plain words. This page is for when you want to know what's there. Every tool takes `char` (`Name-Surname`); without it, the character the server opens on.

"Reads" tools change nothing. "Writes" tools keep something for the character (a plan, an analysis step); the ones marked "can replace what's kept" may overwrite an earlier one.

## Levels and pace

Time, XP and gold per level, against the route.

| Tool | What it answers | Arguments | Kind |
|---|---|---|---|
| `character_summary` | Where the character stands now: level, XP, zone, gold, time in this level, recent pace (XP/hour over the last 3 levels), ETA to the next level, totals (kills, quests, deaths), and the other characters on record. | none | reads |
| `levels` | Time, XP, quests and kills per level from Polestar's XP splits, with median, fastest and slowest. The current level is marked partial. | `from_level`: First level to include.; `to_level`: Last level to include. | reads |
| `route_reference` | Polestar's planned route clock: expected time per level (for the character's race and class), per guide and per guide step. Guide ids as the recorder writes them, e.g. forever/alliance/05-duskwood; steps count from 1. A planner's model of a quick player, not /played. | `level`: A level: the route's expected time for it.; `guide`: A guide id, or part of one.; `step`: A step of that guide (from 1).; `faction`: Look up this faction's route instead of the character's.; `race`: Look up this race's route instead of the character's.; `class`: Look up this class's route instead of the character's. | reads |

## Sessions and zones

Each session, and time, XP and deaths per zone.

| Tool | What it answers | Arguments | Kind |
|---|---|---|---|
| `sessions` | Play sessions, newest first (20 minutes without events ends one): duration, levels, XP, quests, kills, deaths, main zones, guide steps, flights, dungeons and who the player grouped with. | `since`: Start of the range: 7d, 36h, 2w, or an ISO date (UTC).; `until`: End of the range, same forms as since. Default: now.; `limit`: Max rows (default 10). | reads |
| `zones` | Time spent per zone with XP, XP/hour, kills, quests and deaths there, longest first. | `since`: Start of the range: 7d, 36h, 2w, or an ISO date (UTC).; `until`: End of the range, same forms as since. Default: now.; `limit`: Max rows (default 15). | reads |

## Guide steps

Time per step, skipped steps.

| Tool | What it answers | Arguments | Kind |
|---|---|---|---|
| `guide_steps` | Polestar guide progress: per guide steps done, time and skips; the slowest steps; skipped or jumped steps; the median step time. With a route reference, each guide's expected time. | `guide`: Part of a guide name to filter on.; `since`: Start of the range: 7d, 36h, 2w, or an ISO date (UTC).; `until`: End of the range, same forms as since. Default: now.; `limit`: Max rows (default 12). | reads |

## Deaths

Where, at what level, what killed you.

| Tool | What it answers | Arguments | Kind |
|---|---|---|---|
| `deaths` | Deaths: the latest ones with zone and level, and counts per zone and per level. | `since`: Start of the range: 7d, 36h, 2w, or an ISO date (UTC).; `until`: End of the range, same forms as since. Default: now.; `limit`: Max rows (default 15). | reads |

## Dungeons

Your runs, and which ones are worth it now.

| Tool | What it answers | Arguments | Kind |
|---|---|---|---|
| `dungeons` | Dungeon runs: name, level, duration, XP and XP/hour, newest first. | `since`: Start of the range: 7d, 36h, 2w, or an ISO date (UTC).; `until`: End of the range, same forms as since. Default: now.; `limit`: Max rows (default 20). | reads |
| `dungeon_options` | Dungeons in range now or soon, ranked: one more run at the character's level now (time, XP, share of the level, XP/h against its questing, quests to pick up; the Overview's line), expected gear per clear with the top items (boss, drop chance); for the ones it did, one more run and looping it (gold per hour, runs for the mount). | none | reads |

## Gear

What you wear and every way to an upgrade.

| Tool | What it answers | Arguments | Kind |
|---|---|---|---|
| `gear` | Gear advice from Polestar's own scoring: per slot what is worn, the best item the character can get at its level and the next one within 3 levels, with the gain in percent and where to get it (quest and zone, dungeon and boss, craft and profession); then the upgrades in order of gain, those in the current zone flagged. Scored for the spec Polestar uses unless `spec` names another. | `spec`: A spec of the class, e.g. shadow, holy.; `limit`: Max rows (default 10). | reads |
| `gear_options` | Per slot, every way to an upgrade with its cost: quest (on the route or not), dungeon drop (trip time at the drop chance), world drop (luck, plus the player's own AH price), craft, and any other source kind the gear data names. | `limit`: Max rows (default 8). | reads |

## Gold

Your auction prices, and the next riding tier.

| Tool | What it answers | Arguments | Kind |
|---|---|---|---|
| `prices` | Prices from the player's own Auctionator scans: latest, min and max over the range, change since the first scan. | `item`: Part of an item name, or an item id.; `since`: Start of the range: 7d, 36h, 2w, or an ISO date (UTC).; `until`: End of the range, same forms as since. Default: now.; `limit`: Max rows (default 20). | reads |
| `mount_goal` | Each riding tier from the knowledge base: gold needed, gold now, net gold per hour, ETA in played hours and in levels, whether the character is behind, and priced gold options. | none | reads |

## Plans

Session plans at your pace, and how they went.

| Tool | What it answers | Arguments | Kind |
|---|---|---|---|
| `plan_session` | A time-boxed plan for the next N hours (default 3): blocks (start, length, what, why), checkpoints, the expected level, XP and gold at the end, a town stop, where to log out, what to skip, a dungeon branch, the mount. Numbers from the character's own measured pace only. Constraints in plain words ('no dungeons', 'only 2h', 'level tailoring'). Kept for how_did_my_plan_go. | `hours`: How long to plan for, in hours.; `constraints`: Limits in plain words: 'no dungeons', 'only 2h', 'level tailoring'.; `context`: What the session is for. Default: levelling until the route's last level, then max-level PvE. Only levelling is planned so far. | writes, can replace what's kept |
| `check_plan` | Checks a write-up of the latest plan: lists every number in the text that none of the plan's facts holds, and every sentence that breaks the player's own constraints from plan_session (an activity they ruled out, such as 'no dungeons', or more time than they gave), naming the constraint. Call it before showing a plan you wrote. | `text` (required): Your write-up of the latest plan. | reads |
| `how_did_my_plan_go` | The latest plan against what happened: each checkpoint's planned and actual online time, the end level, and the calibration it feeds into the next plans. | none | reads |
| `next_step` | The first 45 minutes of a plan: the block(s), why, a town stop if it falls there, the two quests most worth dropping. | none | reads |
| `next_moves` | Answers 'besides following Polestar, what should I do now?': upgrades in reach (with gains in Polestar's points and where to get them), dungeons at the character's level that drop upgrades, profession trainer visits due, rested XP, time to the next level, plus pace against the route. Each point names the data it came from; also lists the checks the data can't support yet. | none | reads |

## Analysis

Findings about how you play, re-checked before they're kept.

| Tool | What it answers | Arguments | Kind |
|---|---|---|---|
| `analyse` | Start or continue the play analysis of a character: you (the model) run it pass by pass with the tools below, the server judges every finding. Returns the procedure and where the run stands. The same as the `analyse` prompt, for clients without prompts. | `goals`: The player's own words for what they want from the game; kept for the next runs. | reads |
| `play_analysis` | The kept analysis of how the player plays: findings (each with its SQL, re-run on the latest data every night, and the knowledge base documents it used), nudges, and time per level. Read it before advising; the analyse tool runs a new analysis. | none | reads |
| `whats_new` | The play analysis' findings new in the last days, those confirmed again, those dropped, and the nudges. | `days`: How many days back. | reads |
| `sanity_check` | Answers 'is there anything stupid I'm doing?': death clusters by zone, creature and level gap (the likely killer, from Polestar_Recorder), guide steps far over plan, steps passed over, upgrades not picked up, a capped profession, unspent talent points, slow levels. Each finding names its data; also lists the checks the data can't support yet. | none | reads |
| `analysis_brief` | The play analysis' brief, in sections sized for small contexts: start (procedure, goals, finding rules, where the run stands), schema, profile and kb (paged), survey, lane, followups, coverage, synthesis. The first call opens a run; `restart` starts a new one. | `section`: Which part of the brief: start, then the schema, profile and kb pages, then the instructions for the pass the run is on.; `page`: Which page of that section (12,000 characters a page).; `goals`: The player's own words for what they want from the game; kept for the next runs.; `restart`: Drop the open run and start a new one. | writes, can replace what's kept |
| `play_sql` | One read-only SQLite SELECT (WITH allowed) on the character's analysis database (analysis_brief section schema describes it). Paged: page_size rows (default 40, at most 60) as tab-separated text, `more` when there are further pages; long cells and pages are cut. | `query` (required): One read-only SQLite SELECT (WITH allowed); analysis_brief describes the tables.; `page`: Which page of the result.; `page_size`: Rows per page (default 40). | writes |
| `propose_finding` | Hand one finding to the judge: it re-runs the SQL, checks every number (placeholders, expect, holds), the action and the knowledge base ids, then stores it in the character's analysis or says why not. A finding with `action: null` is kept as an observation, shown apart. | `finding` (required): key, title, claim, sql, expect, relevance, action ({do, where, blocked_by, next_step} or null), and optionally holds, effect, sample, kb; `sql`: The SQL behind the finding, re-run by the judge. | writes, can replace what's kept |
| `analysis_submit` | Hand in what a pass produced: pass survey ({questions}), lane ({lane, answers, ask_next}), pick ({picks}) or synthesis ({keep, findings, nudges, patterns, clashes, driver}; add early: true to finish before the lanes are done). The server checks it and answers with the next step. | `pass` (required): The pass this answer is for (analysis_progress says which is next).; `answer` (required): The pass's answer, in the shape analysis_brief gives. | writes, can replace what's kept |
| `analysis_progress` | Where the character's analysis run stands (pass, lanes open and done, queries, tables touched and untouched, findings proposed, verified, refused with why), the next step, the last finished run and the last nightly recheck. Call it first to continue in a new chat. | none | reads |

## People

Players your game showed you.

| Tool | What it answers | Arguments | Kind |
|---|---|---|---|
| `players` | Other players the character keeps running into: days seen, times grouped, contexts, level, class, zones. | `name`: Part of a player name to filter on.; `since`: Start of the range: 7d, 36h, 2w, or an ISO date (UTC).; `until`: End of the range, same forms as since. Default: now.; `limit`: Max rows (default 20). | reads |
| `people` | Other players seen (Polestar's sightings: name, days, last seen, zones; regulars first) and dungeon runs with group size, bosses, wipes and deaths. No addon saves who was in a group: says so. | `limit`: Max rows (default 20). | reads |

## Game rules

Game facts: quests, items, NPCs, zones, rules, and how to level your class.

| Tool | What it answers | Arguments | Kind |
|---|---|---|---|
| `kb_search` | Full-text search of the knowledge base (Forever client tables, Polestar's data and guides, the research catalogue, static rules). Every result has its source: url, source_type, date, confidence and scope (forever or classic_fallback). | `query` (required): Words to search for.; `kind`: One kind of document (spell, item, quest, npc, zone, talent, note...).; `scope`: Only Forever's own sources, or only the Classic ones used where Forever has none.; `limit`: Max rows (default 8). | writes |
| `kb_get` | Full knowledge base documents by id (kind:id, e.g. npc:1234, quest:56, note:xp-sources), up to 10, each with its source. | `ids` (required): Up to 10 kind:id strings, e.g. npc:1234, quest:56. | writes |
| `kb_lookup` | Names for up to 100 ids at once (kind:id: spell, item, quest, npc, zone...); null when the knowledge base doesn't have it. | `ids` (required): Up to 100 kind:id strings, e.g. npc:1234, quest:56. | writes |
| `kb_rule` | One static rule the code uses (e.g. riding.apprentice, rested.accrual), with its value, source and last_verified; `conflicts` holds any other lane's differing version. Lists the known names when the name is unknown. | `name`: The rule's name, e.g. riding.apprentice. Unknown: the answer lists the names. | reads |
| `kb_topics` | The research catalogue by lane (game rules, dungeons, levelling, economy and professions, PvP, raids): statements, rules, contradictions and open questions, each lane as of the day it was checked. With a lane: its documents, its contradictions with their sources, its open questions. | `lane`: A research lane's name (without it: the list of lanes), e.g. dungeons.; `limit`: Max rows (default 40). | reads |
| `class_guide` | How to level the character's class at its level on Forever: spec and talent picks for this bracket and the next, trainer spells to buy now and next and where, stats, solo play, dungeon role, class quests, mistakes, the respec moment. Each statement sourced (date, confidence, scope); contradictions listed. `class` and `level` ask about another. | `class`: A class to ask about instead of the character's, e.g. mage.; `level`: The level to ask about. Default: the character's. | reads |

## Battle.net market data (off by default)

`market` is listed only to a person who turned on "Battle.net data to my AI" in their own Settings, on a shared install. Blizzard's terms keep API data 30 days at most, and a chat keeps what a tool returned, so it's that person's call. A one-person install never serves it.

| Tool | What it answers | Arguments | Kind |
|---|---|---|---|
| `market` | From Blizzard's API (30-day store): the Retail WoW Token price and its change over 7 days, and whether each Forever ruleset is up. No auction house prices here: `prices` has the player's own Auctionator scans. | none | reads |

## Prompts

Ready-made requests. In claude.ai they're in the `+` menu; in Claude Code they're slash commands.

| Prompt | What it does | Arguments |
|---|---|---|
| `coach` | Compare recent levels with the route reference and with your own history, then plan the next session: where, what, what to skip, when to train, hearth or fly. | `char`: Character as Name-Realm (default: the one seen last); `focus`: Anything to focus on, e.g. 'only one hour tonight' or 'dungeons' |
| `plan` | A time-boxed plan for the next hours (default 3). | `hours`: How many hours (default 3) |
| `now` | The next 30 to 45 minutes, in three lines. | none |
| `recap` | The last session against the plan. | none |
| `gear` | Upgrades now, at the next level and from professions, with where to get them. | none |
| `dungeon` | Dungeons that fit, whole-trip cost from your runs, and their gear. | none |
| `check` | Mistakes in the recorded play, with the analysis' verified findings. | none |
| `week` | New or changed verified findings since last week. | none |
| `analyse` | Run the play analysis yourself, pass by pass; the server judges each finding. Continues an open run. | `char`: Character as Name-Realm (default: the one seen last); `goals`: What you want from the game, in your words |
| `mount` | Mount progress: gold needed against gold and gold per hour, with an ETA. | none |
