@chessceo/mcp 0.49.11 → 0.50.0

package/dist/index.js

@@ -22,10 +22,11 @@ import { TOOLS } from "./tools.js";
 import { PROMPTS } from "./prompts.js";
 import { commentAntiPatterns, longLineWarning, noDescribeWarning, noStatsCheckWarning, positionalNagOnIntermediateWarning, positionsDescribed, positionsStatsChecked, } from "./warnings.js";
 import { authContext, authedRequest, deleteGame, fetchGame, get, makeFileId, restoreGame, } from "./http.js";
-import { analysisToStoredEval, capPvsInResponse, convertCloudSnapshotResponse, fetchCompactEval, } from "./analysis/response.js";
+import { fetchCompactEval, } from "./analysis/response.js";
+import { cloudAnalyse, ensureEngines } from "./analysis/cloud.js";
 import { autoEvaluate, autoEvaluateCancel, autoEvaluateStatus, } from "./analysis/auto.js";
 import { deepAnalyseCancel, deepAnalyseStart, deepAnalyseStatus, } from "./analysis/deep.js";
-import { analyseRouting, getNodeByPath, resolveFromNodeOrFen, storeEvalOnNode, } from "./analysis/file_handle.js";
+import { getNodeByPath, resolveFromNodeOrFen, } from "./analysis/file_handle.js";
 import { findPositionInCourses, readCourseAtPosition, runSfEval } from "./courses.js";
 import { applyBatchMutations, applyMutation, argNodeId, } from "./prep/mutations.js";
 import { listNodes, listTranspositions, readPrepFile, } from "./prep/read.js";
@@ -41,6 +42,8 @@ const AUTHED_TOOLS = new Set([
     "list_cloud_engines",
     "stop_cloud_engine",
     "cloud_analyse",
+    "ensure_engines",
+    "list_cloud_machine_options",
     "list_collections",
     "create_collection",
     "rename_collection",
@@ -125,11 +128,22 @@ const ENGINE_GUIDE = {
     stockfish: "Objective calculation, the default cloud engine at about 100 million nodes per second. A few seconds gives a very strong view of the position. Use it on every position, including when steering by lc0 or human. Its score is the objective value with best defense: 0.00 means objectively a draw with best play, not that nothing is happening or that neither side has chances. Many positions that are very hard to play for a human score 0.00. Scores drift toward 0.00 as the search deepens, especially in drawn positions. Use it to check whether a tactic is real, whether a defense holds, and whether a move loses material or the game.",
     lc0: "Neural-net engine trained on self-play games, not human games. It is better than Stockfish at long-term ideas and at judging which side is practically on top. Never gives 0.00: it always says which side prefers the position, at least a little. Use it when Stockfish gives 0.00 to see who still has the practical edge, and to find where the long-term ideas are. Contempt changes how it values a draw and which side it plays for: contempt at -20 makes Black play for a win, which is useful for finding ideas, including in openings. It is much weaker tactically than Stockfish, so confirm any concrete line with Stockfish.",
     human: "Neural net trained only on human games, about 11 million rated games. Its moves and evaluations are practical, not objective: the moves it suggests are the ones a human would find and play. It punishes dubious moves less than Stockfish, because human games contain many imperfect moves that still work in practice, so a move with a sound idea behind it can score well here. Use it to predict how a person will respond to an idea, to find ideas (it may like a move that only fails to a refutation no human would find; Stockfish shows whether that refutation exists), and to see how a human would evaluate a position, especially positional or unclear ones. Like lc0 it is weaker in very unusual positions, and its evaluations there can be trusted much less. Stockfish remains the check on tactics and on whether a practical idea is objectively sound.",
-    combo: "Runs Stockfish and Lc0 together — use when you want both the objective read and the practical/human-feel read on the same position.",
 };
 // Modern engines give equality very often, so small numbers are not "equal".
 // Rough guide, not exact thresholds. Shown alongside ENGINE_GUIDE above.
 const ENGINE_EVAL_SCALE = "Small numbers are not equality. ±0.00 to ±0.10 is equal in practice (+0.10 is '=' or '+=' at most). +0.20 to +0.40 is real pressure, not 'a bit better'. +0.50 and up is a clear advantage. Stockfish 0.00 with a plus from Lc0 is a practical edge, not equality. Check both engines before calling a position equal.";
+// How to run analysis end to end. Authed response only, with ENGINE_GUIDE.
+const ENGINE_WORKFLOW = [
+    "1. Plan: ensure_engines({engines, positions}) shows what is running, what to start, the price and an estimate. It starts nothing.",
+    "2. Ask: show the user the price of anything you would start and get a yes. Rentals bill per minute until stopped.",
+    "3. Start: start_cloud_engine({machine_type}) per missing engine. Each SKU runs one engine; the engine comes from the SKU. Wait until list_cloud_engines shows it running (static engines are instant, others ~1-5 min).",
+    "4. Analyse: cloud_analyse({fens | lines | file_id+node_ids, engines}) for up to 10 positions, each engine on its own rental, in parallel. auto_evaluate({id, engines}) for a whole file or subtree: fills only the engines each node is missing and saves as it goes. deep_analyse({engine, ...}) for one long think.",
+    "5. Read back: quote_engine_eval gives the stored sf (cp/mate), lc0 and human (win/draw/loss %) per node.",
+    "6. Stop: stop_cloud_engine when the work is done, unless the user wants it kept running.",
+].join("\n");
+// Eval symbols are the writer's call, not the engine's. Recommendation
+// only; nothing in the MCP sets a symbol automatically.
+const EVAL_SYMBOL_GUIDE = "The eval symbol (=, +=, ±, +-) is your call, written for a human reader. The engines inform it; no tool sets it for you. Stockfish 0.00 can still be += when Lc0 or the human engine clearly prefer one side, because the symbol describes the practical picture, not only the objective one. Look at all engines you ran before choosing, and don't put a symbol on a position nobody analysed.";
 // v0.48: consolidated the five `read_*_guide` / `read_example_prep_files`
 // tools into ONE `read_docs`. LLM lists what it wants; we return them
 // in a single response. Also cleaner: enumerating available docs in one
@@ -390,68 +404,26 @@ async function callToolInner(name, args) {
                 ...(resp && typeof resp === "object" ? resp : { options: [] }),
                 engine_guide: ENGINE_GUIDE,
                 eval_scale: ENGINE_EVAL_SCALE,
+                eval_symbols: EVAL_SYMBOL_GUIDE,
+                workflow: ENGINE_WORKFLOW,
             };
         }
+        case "ensure_engines":
+            return {
+                ...await ensureEngines(args),
+                engine_guide: ENGINE_GUIDE,
+                workflow: ENGINE_WORKFLOW,
+            };
         case "start_cloud_engine":
             return authedRequest("POST", "/api/agent/cloud-engines", {
                 machineType: String(args.machine_type),
-                ...(typeof args.engine_type === "string" ? { engineType: args.engine_type } : {}),
             });
         case "list_cloud_engines":
             return authedRequest("GET", "/api/agent/cloud-engines");
         case "stop_cloud_engine":
             return authedRequest("DELETE", `/api/agent/cloud-engines/${encodeURIComponent(String(args.contract_id))}`);
-        case "cloud_analyse": {
-            const resolved = await resolveFromNodeOrFen(args);
-            const fen = resolved.fen;
-            const body = { fen };
-            if (typeof args.movetime_ms === "number")
-                body.movetime_ms = args.movetime_ms;
-            if (typeof args.stockfish_multipv === "number")
-                body.stockfish_multipv = args.stockfish_multipv;
-            if (typeof args.lc0_multipv === "number")
-                body.lc0_multipv = args.lc0_multipv;
-            if (typeof args.contempt === "number")
-                body.contempt = args.contempt;
-            Object.assign(body, analyseRouting(args));
-            const raw = await authedRequest("POST", "/api/agent/cloud-engines/analyse", body);
-            const converted = convertCloudSnapshotResponse(raw, fen);
-            // PV cap: engine PVs beyond ~6 plies are speculative (the tail is
-            // where the search's confidence collapses — SF at depth 24 has
-            // seen the first few plies solidly and hedged everything after).
-            // More importantly, LLMs paste long PVs into `add_line` as if
-            // they were prepared repertoire. A 15-move PV pasted as a
-            // variation is one line of engine output through positions
-            // where both sides had real choices — not a repertoire. Cap the
-            // affordance: return only what's load-bearing (3 full moves for
-            // understanding the point), let the caller re-analyse the
-            // resulting position if they want to see further. Override via
-            // `pv_max_plies` for the rare case (deep tactics verification).
-            const pvMaxPlies = typeof args.pv_max_plies === "number" && args.pv_max_plies > 0
-                ? Math.min(args.pv_max_plies, 40)
-                : 6;
-            capPvsInResponse(converted, pvMaxPlies);
-            // Node-addressed calls: persist the result on the node's ceoEval
-            // so a later quote_engine_eval can cite this measurement. This is
-            // the anti-hallucination hinge — prose that says "engines say X
-            // on node Y" can only trace back to a call actually made against
-            // node_id=Y, because the store only fires when file_id+node_id
-            // was supplied and the eval survives via the [%ceo-eval] escape.
-            if (resolved.file) {
-                const ev = analysisToStoredEval(converted);
-                if (ev) {
-                    const stamped = await storeEvalOnNode(resolved.file, ev);
-                    if (stamped.length > 1) {
-                        // Surface the propagation so the LLM sees exactly which
-                        // other nodes now carry this eval (and can skip them for
-                        // re-analysis).
-                        converted.also_stored_on = stamped.slice(1);
-                    }
-                }
-            }
-            converted.eval_scale = ENGINE_EVAL_SCALE;
-            return converted;
-        }
+        case "cloud_analyse":
+            return cloudAnalyse(args, ENGINE_EVAL_SCALE);
         case "deep_analyse":
             return deepAnalyseStart(args);
         case "deep_analyse_status":
@@ -562,7 +534,7 @@ async function callToolInner(name, args) {
         case "apply_mutations":
             return applyBatchMutations(args);
         case "auto_evaluate":
-            return autoEvaluate(args, applyBatchMutations);
+            return autoEvaluate(args);
         case "auto_evaluate_status":
             return autoEvaluateStatus(args);
         case "auto_evaluate_cancel":

package/dist/pgn/exporter.js

@@ -1,7 +1,7 @@
 // PrepFile → PGN text. Deterministic — same tree always exports to the
 // same PGN modulo whitespace, so paths stay stable across
 // export→reparse cycles.
-import { codeFromColor } from "./types.js";
+import { codeFromColor, STORED_EVAL_KEYS } from "./types.js";
 // Standard PGN "seven tag roster" order. We emit these first (in the
 // order they appear in tags), then any extra tags in insertion order.
 const STR_ORDER = ["Event", "Site", "Date", "Round", "White", "Black", "Result"];
@@ -142,22 +142,24 @@ function renderNodeAnnotation(node) {
     }
     return bits.join(" ");
 }
-// Serialise a stored eval as `[%ceo-eval sf=+0.20/38 lc0=+0.35/24 nag=$14]`.
-// Compact: no PVs (regenerable via cloud_analyse), decimal cp for
-// readability, mate as `MN`/`-MN`, depth as `/N`.
+// Serialise a stored eval as `[%ceo-eval sf=+0.20/38 lc0=W38D45L17/24
+// human=W30D50L20/20]`. Compact: no PVs (regenerable), decimal cp for
+// readability, mate as `MN`/`-MN`, WDL as `W<w>D<d>L<l>`, depth as `/N`.
 function renderCeoEval(ev) {
     const bits = [];
-    if (ev.sf)
-        bits.push(`sf=${formatEngineEval(ev.sf)}`);
-    if (ev.lc0)
-        bits.push(`lc0=${formatEngineEval(ev.lc0)}`);
-    if (ev.nag)
-        bits.push(`nag=${ev.nag}`);
+    for (const k of STORED_EVAL_KEYS) {
+        const e = ev[k];
+        if (e)
+            bits.push(`${k}=${formatEngineEval(e)}`);
+    }
     return bits.length > 0 ? `[%ceo-eval ${bits.join(" ")}]` : "";
 }
 function formatEngineEval(e) {
     let body;
-    if (typeof e.mate === "number") {
+    if (typeof e.w === "number" && typeof e.d === "number" && typeof e.l === "number") {
+        body = `W${e.w}D${e.d}L${e.l}`;
+    }
+    else if (typeof e.mate === "number") {
         body = e.mate >= 0 ? `+M${e.mate}` : `M${e.mate}`; // "+M5" / "M-5"
     }
     else if (typeof e.cp === "number") {

package/dist/pgn/mutations.js

@@ -12,6 +12,7 @@ import { Chess } from "chessops/chess";
 import { parseSan } from "chessops/san";
 import { makeFen } from "chessops/fen";
 import { cloneOnPath, deriveNodeId, getNode, PathError } from "./paths.js";
+import { STORED_EVAL_KEYS } from "./types.js";
 export class MutationError extends Error {
 }
 // Add a SAN move as a new child under `parentPath`. **Idempotent on
@@ -162,14 +163,26 @@ export function promoteVariation(file, path) {
     parent.children = [promoted, ...rest];
     return { file: { tags: file.tags, root: newRoot }, id: promoted.id };
 }
-// Replace the stored ceoEval on the node at `path`. Passing null clears.
-// This is what auto_evaluate / cloud_analyse(node_id) calls per-node.
+// Merge engine evals into the stored ceoEval on the node at `path`: only
+// the engines present in `ev` are replaced, the others are kept, so a
+// Stockfish deep think never wipes a stored human or Lc0 read. Passing null
+// clears every engine.
 export function setCeoEval(file, path, ev) {
     const { root: newRoot, target } = cloneOnPath(file.root, path);
-    if (ev === null || (!ev.sf && !ev.lc0 && !ev.nag))
+    if (ev === null) {
         delete target.ceoEval;
-    else
-        target.ceoEval = ev;
+    }
+    else {
+        const merged = { ...(target.ceoEval ?? {}) };
+        for (const k of STORED_EVAL_KEYS) {
+            if (ev[k])
+                merged[k] = ev[k];
+        }
+        if (merged.sf || merged.lc0 || merged.human)
+            target.ceoEval = merged;
+        else
+            delete target.ceoEval;
+    }
     return { file: { tags: file.tags, root: newRoot }, id: target.id };
 }
 // Set the same ceoEval on every path in `paths`. One clone-and-return

package/dist/pgn/parser.js

@@ -24,10 +24,17 @@ const CEO_EVAL_RE = /\[%ceo-eval\s+([^\]]+)\]/g;
 // `{[%eval] [%wdl]}` comment on an imported Lichess PGN got stripped
 // on a set_tag save cycle).
 const KNOWN_CMD_RE = /\[%(?:cal|csl|ceo-eval)\s+[^\]]+\]/g;
-// Parse a `sf=+0.20/38` or `lc0=M-5/22` fragment into its numeric parts.
-// Returns null if the value doesn't parse; the parser tolerates missing
-// depth and mate notation.
+// Parse a `sf=+0.20/38`, `sf=M-5/22` or `lc0=W38D45L17/24` fragment into
+// its numeric parts. Returns null if the value doesn't parse; depth is
+// optional.
 function parseEngineEvalFragment(raw) {
+    const wdl = raw.match(/^W(\d+)D(\d+)L(\d+)(?:\/(\d+))?$/i);
+    if (wdl) {
+        const out = { w: parseInt(wdl[1], 10), d: parseInt(wdl[2], 10), l: parseInt(wdl[3], 10) };
+        if (wdl[4] !== undefined)
+            out.depth = parseInt(wdl[4], 10);
+        return out;
+    }
     const m = raw.match(/^([+-]?)(?:M(-?\d+)|(\d+(?:\.\d+)?))(?:\/(\d+))?$/i);
     if (!m)
         return null;
@@ -75,22 +82,14 @@ export function parseCommentAnnotations(comment) {
                 continue;
             const k = entry.slice(0, eq).toLowerCase();
             const v = entry.slice(eq + 1);
-            if (k === "sf") {
+            if (k === "sf" || k === "lc0" || k === "human") {
                 const parsed = parseEngineEvalFragment(v);
                 if (parsed)
-                    ev.sf = parsed;
-            }
-            else if (k === "lc0") {
-                const parsed = parseEngineEvalFragment(v);
-                if (parsed)
-                    ev.lc0 = parsed;
-            }
-            else if (k === "nag") {
-                if (/^\$\d+$/.test(v))
-                    ev.nag = v;
+                    ev[k] = parsed;
             }
+            // Anything else (incl. the pre-0.50 `nag=`) is dropped.
         }
-        if (ev.sf || ev.lc0 || ev.nag)
+        if (ev.sf || ev.lc0 || ev.human)
             ceoEval = ev;
     }
     const text = comment.replace(KNOWN_CMD_RE, "").replace(/\s+/g, " ").trim();

package/dist/pgn/types.js

@@ -19,6 +19,8 @@
 // width, buildIdIndex keeps the first occurrence and logs to stderr
 // rather than throwing — the file stays readable, only mutations
 // against the collided id are ambiguous.
+// Keys of StoredEval in canonical order.
+export const STORED_EVAL_KEYS = ["sf", "lc0", "human"];
 // Named colours as they appear in the parsed tree. The wire format uses
 // single-letter codes (G, R, Y, C, B, O); the tree uses these longer
 // names to match how the frontend represents them.

package/dist/tools.js

@@ -118,7 +118,7 @@ export const TOOLS = [
             "- `gm-classical` — GM classical games (both players ≥2500, real thinking-time). BEST for opening prep — every move is signal, avgElo ~2600 across all listed moves.\n" +
             "- `main` — the whole 11.7M-game DB. Widest coverage but noisiest (includes 1000-Elo blunder-fests in the move stats). Use as fallback when gm-classical's totalCount is too small to be informative.\n\n" +
             "Game movetext is trimmed to the moves AFTER the queried position (using each game's plyNumber). Saves ~70% of the bytes vs full movetext.\n\n" +
-            "AUTO-EVAL: if a cloud engine instance is running, the response includes `.eval` with a compact read from the engine(s) it provides and the corresponding NAG. Do NOT fire cloud_analyse separately for the same FEN. When called with `file_id`+`node_id`, the eval is also auto-stored on that node's `ceoEval` — later readable via quote_engine_eval.",
+            "AUTO-EVAL: if a Stockfish rental is running, the response includes `.eval` with a short Stockfish read (cp/mate White's point of view, best move, PV). Not stored on any node; for a stored eval or other engines use cloud_analyse.",
         inputSchema: {
             type: "object",
             properties: {
@@ -256,27 +256,34 @@ export const TOOLS = [
             required: ["fide_id"],
         },
     },
+    {
+        name: "ensure_engines",
+        description: "Plan cloud-engine work before running it. For each engine you need (`stockfish`, `lc0`, `human`), says whether a rental providing it is already running (with its contract_id), or the cheapest SKU to start and its price. Pass `positions` (how many positions you will analyse) for a time and cost estimate. Starts nothing.\n\n" +
+            "CALL FIRST whenever a task needs cloud engines. Then show the user the price of anything to start, get a yes, and start it with start_cloud_engine. The response also carries `engine_guide` (what each engine is for) and `workflow` (the full plan → start → analyse → stop sequence).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                engines: { type: "array", items: { type: "string", enum: ["stockfish", "lc0", "human"] }, description: "Engines the task needs. Default [\"stockfish\"]." },
+                positions: { type: "integer", minimum: 1, description: "Optional: how many positions you plan to analyse, for the estimate." },
+                movetime_ms: { type: "integer", minimum: 100, maximum: 300000, description: "Optional: think time per position for the estimate (default 2000)." },
+            },
+        },
+    },
     {
         name: "list_cloud_machine_options",
-        description: "Returns the catalog of cloud-engine machine types the user can start — every engine shape (stockfish-only, lc0-only, and combo) they're entitled to, same visibility rules as the chess.ceo app (SKU, which engine(s) it runs, human display name, cost per hour, availability), plus an `engine_guide` explaining what each engine type is actually good/bad for so you can pick the right one for the task, not just the cheapest. ALWAYS call this before start_cloud_engine — SKU strings like 'rtx-5090-64' do not match the display names ('Stockfish 32 CPUs + Lc0 1× RTX 5090') and are NOT guessable, and a given SKU only supports the engine(s) shown in its `engine` field (a stockfish-only SKU cannot be started as lc0 or combo). Present the user the display names + prices; pass the SKU to start_cloud_engine.",
+        description: "Returns the catalog of cloud-engine SKUs the user can start, same visibility as the chess.ceo app: SKU (`machineType`), the one engine it runs (`engine`: stockfish, lc0 or human), display name, cost per hour, availability. Also returns `engine_guide`, `eval_scale`, `eval_symbols` and `workflow`. ensure_engines already picks the cheapest SKU per engine; use this when the user wants to choose hardware. SKU strings are NOT guessable from display names; pass them verbatim to start_cloud_engine.",
         inputSchema: { type: "object", properties: {} },
     },
     {
         name: "start_cloud_engine",
-        description: "Rent a GPU/CPU instance on the user's chess.ceo account — stockfish-only, lc0-only, or combo (both in one container), whichever the chosen SKU provides. Real money — billed per second while running.\n\n" +
-            "CRITICAL: `machine_type` must be an exact SKU from `list_cloud_machine_options` (e.g. 'rtx-5090-64', NOT 'rtx-5090'). Guessing SKUs will fail. Call list_cloud_machine_options first, show the user the display names + prices, get their confirmation, then pass the SKU here. `engine_type` must match what that SKU actually provides (its `engine` field from the catalog) — omit it to default to whatever the SKU is (a combo SKU defaults to \"combo\").\n\n" +
-            "Use list_cloud_engines first to check if the user already has one running; don't start a second instance unless the user asked for it. Requires an MCP token with agent access.",
+        description: "Rent one cloud engine on the user's chess.ceo account. Each SKU runs exactly one engine (stockfish, lc0 or human), taken from the SKU. Real money: billed per minute from start until stop_cloud_engine.\n\n" +
+            "`machine_type` must be an exact SKU from ensure_engines or list_cloud_machine_options. Show the user the price and get their confirmation first. For several engines, start one rental per engine; cloud_analyse uses them together. Don't start an engine that is already running (ensure_engines / list_cloud_engines show what is).",
         inputSchema: {
             type: "object",
             properties: {
                 machine_type: {
                     type: "string",
-                    description: "SKU from list_cloud_machine_options (e.g. 'rtx-5090-64', 'rtx-5090', 'epyc-256'). MUST be the exact SKU, not the display name and not a guess.",
-                },
-                engine_type: {
-                    type: "string",
-                    enum: ["stockfish", "lc0", "combo"],
-                    description: "Which engine(s) to run. Must match the SKU's own `engine` field from list_cloud_machine_options — e.g. a stockfish-only SKU can only be started as \"stockfish\". Optional; defaults to \"combo\".",
+                    description: "Exact SKU from ensure_engines or list_cloud_machine_options. Not a display name, not a guess.",
                 },
             },
             required: ["machine_type"],
@@ -284,12 +291,12 @@ export const TOOLS = [
     },
     {
         name: "list_cloud_engines",
-        description: "List the user's currently running cloud engines. Use before starting a new one, or to find the contract_id for stop_cloud_engine. `cloud_analyse` uses the only running rental that can serve the request unless you pass `contract_id`, so listing is only necessary when there are several.",
+        description: "List the user's running cloud engines, each with its `contractId` and `engines` (what it provides). A row with empty `engines` is still starting. Use the contractId for stop_cloud_engine, or in `rentals` when two running rentals provide the same engine.",
         inputSchema: { type: "object", properties: {} },
     },
     {
         name: "stop_cloud_engine",
-        description: "Destroy a running cloud engine. Billing stops immediately. Use the contract_id from `list_cloud_engines` — don't guess.",
+        description: "Destroy a running cloud engine. Billing stops immediately. Use the contract_id from `list_cloud_engines`, don't guess. Stop rentals when the analysis is done unless the user wants them kept.",
         inputSchema: {
             type: "object",
             properties: {
@@ -303,65 +310,38 @@ export const TOOLS = [
     },
     {
         name: "cloud_analyse",
-        description: "Runs a synchronous ~2s analysis on one of the user's running engine instances and returns the requested engines' final read for the FEN — depth, top-N candidate moves with scores (**scoreCp is White-POV centipawns**: +20 = White is +0.20 pawns better regardless of whose turn it is; matches the sign convention used everywhere else in this MCP, including the stored ceoEval). Mate is White-POV plies-to-mate (+5 = White mates in 5). Also returns each engine's principal variation.\n\n" +
-            "GROUNDING: every claim you make about a position must trace back to actual engine output from a call in THIS session. Don't invent evaluations, don't name 'best moves' you haven't seen the engine list, don't fabricate variations that 'look plausible.' Compute is cheap — call this 5-10 times while walking a tree rather than pattern-matching from your training data. When you don't have data for the position, either run the tool or say so; don't fill the gap with chess prose the user can't distinguish from measured output.\n\n" +
-            "Runs on any of the caller's running rentals — combo, stockfish-only, or lc0-only. Pass `contract_id` to choose one; without it the only rental that can serve the requested engines is used, and the error lists the candidates if there are several.\n\n" +
-            "How to read the response:\n" +
-            "• Stockfish is objective truth — trust it for 'does this line hold?' 'is there a tactic?' 'is this endgame drawn?' A Stockfish 0.00 means 'objectively equal', NOT 'trivial draw' — one side can still be much harder to play in practice.\n" +
-            "• Lc0 is practical eval — trust it for 'which side is easier?' 'which candidate is best when Stockfish shows several as equal?' Lc0 sees long-term positional factors Stockfish's fixed search can miss.\n" +
-            "• When they agree → high confidence. When they disagree → look at both scores and reason WHY (Stockfish sharply higher = tactic Lc0 missed; Lc0 higher = long-term positional edge past Stockfish's horizon). Never dismiss either — the disagreement is the signal.\n\n" +
-            "Contempt (`contempt`) skews Lc0 (only Lc0 — Stockfish always stays objective) toward White (positive) or Black (negative). Signed 0-100 strength — same scale as the web UI's ContemptStrength slider (the server multiplies by 8 to produce Lc0's internal cp bias). Typical values: ±15 for a light nudge, ±30-60 for real fighting play, ±80-100 for maximum steer. Use it to find non-objective 'practical' ideas or when the user needs to lean toward fighting/solid lines with a specific colour. Do NOT quote a contempt-biased eval as objective — cross-check with Stockfish.\n\n" +
-            "Also useful: pass `moves` on top of `fen` to explore a variation without computing FENs yourself (e.g. fen='<tabiya>', moves='b4 a5 c3'). And the flip-side-to-move threat check documented in the guide is a great free trick.\n\n" +
-            "**PVs are capped at 6 plies by default (3 full moves), and lines that got truncated are marked with `pv_truncated: true`.** This is deliberate: the tail of a PV is where the engine's confidence collapses, AND pasting a long PV into `add_line` as if it were prepared repertoire is the #1 documented anti-pattern of this MCP — a 15-move PV is one line of engine output through positions where both sides had real choices, not a repertoire. To see further, don't raise `pv_max_plies`; instead, walk the tree one branch at a time with a fresh `cloud_analyse` at each position where the opponent has real alternatives — that's what makes it prep instead of pasted output. Only raise the cap when you're verifying a forcing sequence (a mate, a forced tactical resolution), not to build lines.\n\n" +
-            "For the full guide including worked examples, call the `read_engine_usage_guide` tool.\n\n" +
-            "Not for casual questions — this costs real money per second. Use `get_position_stats` for anything that doesn't require deep prep.\n\n" +
-            "**When called with `file_id`+`node_id` (preferred inside a prep file), the resulting eval is auto-stored on that node's `ceoEval` — you can then quote it with quote_engine_eval on any later call.** This is what makes engine attribution trustworthy: prose that says 'engines say X on node Y' can only be true if a call was actually made against node_id=Y.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                file_id: { type: "string", description: "Prep file id. **Prefer file_id+node_id over fen** when inside a prep file — the FEN comes from the tree AND the result is stored on the node." },
-                node_id: { type: "string", description: "Node id inside `file_id`. Root is 'r'. When set, overrides `fen`/`moves`." },
-                fen: { type: "string", description: "Starting position as FEN. Only used if `node_id` is not set." },
-                moves: {
-                    type: "string",
-                    description: "Optional SAN moves to apply on top of `fen` (or startpos). Only used if `node_id` is not set.",
-                },
-                movetime_ms: {
-                    type: "integer",
-                    minimum: 100,
-                    maximum: 10000,
-                    description: "Think time in milliseconds (default 2000).",
-                },
-                stockfish_multipv: {
-                    type: "integer",
-                    minimum: 1,
-                    maximum: 10,
-                    description: "Stockfish candidate lines (default 2). Kept tight because each extra PV steals search bandwidth from the top choice — SF is the 'what's objectively best' leg, use a low multipv to keep it strong. Raise only when you specifically need SF's take on a wide range of candidates.",
-                },
-                lc0_multipv: {
-                    type: "integer",
-                    minimum: 1,
-                    maximum: 10,
-                    description: "Lc0 candidate lines (default 8). Kept wide because multipv doesn't degrade Lc0's strength the way it does Stockfish's — Lc0 is the 'find inspiration / explore practical tries' leg, use a high multipv to get a full slate of ideas.",
-                },
-                contempt: {
-                    type: "integer",
-                    minimum: -100,
-                    maximum: 100,
-                    description: "Lc0 contempt bias. Signed 0-100 strength (same scale as the web UI's ContemptStrength slider — server multiplies by 8 to get the internal cp bias). 0 = objective (default). Positive favours White, negative favours Black. Typical: ±15 light nudge, ±30-60 real fighting play, ±80-100 maximum steer. Not applied to Stockfish. See engine_usage_primer for when to use.",
-                },
-                contract_id: { type: "string", description: "Which of your running rentals to use, from list_cloud_engines. Any engine shape works (combo, stockfish-only, lc0-only). Omit it when only one rental can serve the request; if several can, the error lists their contract ids." },
-                engines: {
-                    type: "array",
-                    items: { type: "string", enum: ["stockfish", "lc0"] },
-                    description: "Which engines to run. Default = both. Use `[\"lc0\"]` to skip Stockfish (e.g. while a deep_analyse job is holding the SF slot on the same rental). Use `[\"stockfish\"]` when only the objective read matters. The skipped engine's field is omitted from the response.",
+        description: "Analyse up to 10 positions on the engines you choose (`stockfish`, `lc0`, `human`), each engine on whichever running rental provides it. Engines run in parallel per position. Returns, per position, each engine's depth, candidate lines and best move.\n\n" +
+            "Positions: `fens` (list), `lines` (list of SAN move sequences from `fen` or the start), `file_id` + `node_ids` (list), or a single `fen` / `moves` / `file_id`+`node_id`. Examples: analyse three FENs with Stockfish → `{fens: [a, b, c], engines: [\"stockfish\"]}`; with the human engine and Stockfish → `engines: [\"stockfish\", \"human\"]`. For a whole file or subtree use auto_evaluate instead.\n\n" +
+            "Scores: `scoreCp` and `mate` are White's point of view (+20 = White +0.20; mate +5 = White mates in 5). lc0 and human lines carry `wdl`: win/draw/loss percent, White's point of view. Read the response's `eval_scale` before calling a position equal.\n\n" +
+            "GROUNDING: every claim about a position must trace back to engine output from this session. Don't invent evaluations, best moves or variations. When you have no data for a position, run it or say so.\n\n" +
+            "Storing: with `file_id`, each result is merged into the `ceoEval` of every node that reaches that position (`stored_on` in the response), keeping other engines' stored reads. quote_engine_eval cites them later.\n\n" +
+            "Contempt (`contempt`, lc0 only): signed -100..100, positive favours White. Use it to find ideas (e.g. -20 makes Black play for a win). Never quote a contempt eval as objective.\n\n" +
+            "PVs are capped at 6 plies (`pv_truncated: true` when cut). To see further, analyse the position at the end of the line; raise `pv_max_plies` only to verify a forcing line. Don't paste PVs into add_line as prep.\n\n" +
+            "Needs running rentals for the engines you ask for (see ensure_engines). Costs money while rentals run; use get_position_stats for casual questions.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                engines: { type: "array", items: { type: "string", enum: ["stockfish", "lc0", "human"] }, description: "Engines to run. Default [\"stockfish\"]. Each needs a running rental that provides it." },
+                fens: { type: "array", items: { type: "string" }, description: "Positions as FENs (up to 10 in total with the other inputs)." },
+                lines: { type: "array", items: { type: "string" }, description: "SAN move sequences, each applied from `fen` (or the start position), e.g. [\"e4 c5 Nf3\", \"e4 e5 Nf3\"]." },
+                file_id: { type: "string", description: "Prep file id. With node_ids/node_id the FEN comes from the tree; with any input, results are stored on matching nodes." },
+                node_ids: { type: "array", items: { type: "string" }, description: "Node ids inside `file_id`." },
+                node_id: { type: "string", description: "One node id inside `file_id`. Root is 'r'." },
+                fen: { type: "string", description: "One position, or the start position for `moves` / `lines`." },
+                moves: { type: "string", description: "SAN moves applied on top of `fen` (or the start position) for a single position." },
+                movetime_ms: { type: "integer", minimum: 100, maximum: 15000, description: "Think time per position in ms (default 2000)." },
+                multipv: {
+                    type: "object",
+                    properties: { stockfish: { type: "integer", minimum: 1, maximum: 10 }, lc0: { type: "integer", minimum: 1, maximum: 10 }, human: { type: "integer", minimum: 1, maximum: 10 } },
+                    description: "Candidate lines per engine. Defaults: stockfish 2 (extra lines cost it strength), lc0 and human 8 (wide slate of ideas, no strength cost).",
                 },
-                pv_max_plies: {
-                    type: "integer",
-                    minimum: 1,
-                    maximum: 40,
-                    description: "Cap each returned PV to this many plies (default 6 = 3 full moves). PVs beyond ~6 plies are speculative and are the anti-pattern behind pasted-engine-line 'prep' — don't raise unless you're specifically checking a forcing tactic or verifying a mate. When a line was truncated, the response marks it with `pv_truncated: true`.",
+                contempt: { type: "integer", minimum: -100, maximum: 100, description: "lc0 only. Positive favours White, negative Black. 0 = objective (default)." },
+                rentals: {
+                    type: "object",
+                    properties: { stockfish: { type: "string" }, lc0: { type: "string" }, human: { type: "string" } },
+                    description: "Only when two running rentals provide the same engine: engine → contract_id from list_cloud_engines.",
                 },
+                pv_max_plies: { type: "integer", minimum: 1, maximum: 40, description: "Cap each PV (default 6 plies). Raise only to verify a forcing line." },
             },
         },
     },
@@ -722,25 +702,27 @@ export const TOOLS = [
     },
     {
         name: "auto_evaluate",
-        description: "Walk the tree from `node_id` (default `'r'` = whole file) and populate the persistent `ceoEval` on every descendant via cloud_analyse. Requires a running cloud engine instance (any shape; pass contract_id to choose).\n\n" +
-            "**Async job — returns immediately.** Response: `{ job_id, target_count, status: 'running', estimated_seconds }`. Then poll `auto_evaluate_status(job_id)` until `done: true`. Cancel a run with `auto_evaluate_cancel(job_id)` — partial progress is preserved. Do useful other work between polls (write more of the tree, walk the opponent's repertoire) — the engine runs in the background.\n\n" +
-            "Progress is checkpointed to the prep file every 8 successfully-evaluated nodes, so a cancel / crash / MCP restart mid-run leaves the tree partially populated rather than losing everything. On MCP restart the job record disappears; re-run auto_evaluate and `only_missing=true` naturally skips what was already saved.\n\n" +
-            "**Does NOT set visible NAGs.** NAG placement is your call, not the engine's — an opening tree full of 0.00 positions doesn't need a `$10` (=) glyph on every move. Use quote_engine_eval on individual nodes before writing prose that references engine numbers.\n\n" +
-            "Costs real money — one cloud_analyse per node. A 200-node walk at default movetime is ~5 min of engine time (calls serialise on the per-engine semaphore in the backend).",
+        description: "Analyse a whole prep file, or the subtree under `node_id`, on the engines you choose and store the evals on every node. Example: \"analyse the whole tree with Stockfish and the human engine and save the evals\" → `{id, engines: [\"stockfish\", \"human\"]}`.\n\n" +
+            "Each node gets only the requested engines it is missing (`only_missing`, default true), so adding an engine later runs just that engine. Transpositions are analysed once and stamped on every node that reaches the position. Stored evals merge per engine; other engines' stored reads are kept. Results are saved after every batch of up to 10 positions.\n\n" +
+            "**Async job, returns immediately:** `{ job_id, target_count, already_complete, estimated_seconds }`. Poll auto_evaluate_status(job_id); cancel with auto_evaluate_cancel. Do other work between polls.\n\n" +
+            "Needs running rentals for every engine you ask for (ensure_engines). Wall time ≈ target_count × movetime (engines run in parallel per position). Does not set visible NAGs: the eval symbol is your call.",
         inputSchema: {
             type: "object",
-            properties: { contract_id: { type: "string", description: "Which of your running rentals to use, from list_cloud_engines. Any engine shape works (combo, stockfish-only, lc0-only). Omit it when only one rental can serve the request; if several can, the error lists their contract ids." },
-                id: { type: "string" },
+            properties: {
+                id: { type: "string", description: "Prep file id." },
+                engines: { type: "array", items: { type: "string", enum: ["stockfish", "lc0", "human"] }, description: "Engines to run. Default [\"stockfish\"]." },
                 node_id: { type: "string", description: "Subtree root (default 'r' = whole file)." },
-                only_missing: { type: "boolean", description: "Skip nodes that already carry a stored ceoEval (default true)." },
-                movetime_ms: { type: "integer", minimum: 500, maximum: 5000, description: "Per-node cloud_analyse think time (default 1500)." },
+                only_missing: { type: "boolean", description: "Run only the engines a node has no stored eval for (default true). false re-analyses everything." },
+                movetime_ms: { type: "integer", minimum: 500, maximum: 15000, description: "Think time per position in ms (default 2000)." },
+                contempt: { type: "integer", minimum: -100, maximum: 100, description: "lc0 only. Stored evals then carry the bias; use for idea finding, not for the stored record." },
+                rentals: { type: "object", properties: { stockfish: { type: "string" }, lc0: { type: "string" }, human: { type: "string" } }, description: "Only when two running rentals provide the same engine: engine → contract_id." },
             },
             required: ["id"],
         },
     },
     {
         name: "auto_evaluate_status",
-        description: "Poll the status of an auto_evaluate job. Response: `{ status: 'running' | 'done' | 'cancelled' | 'error' | 'not_found', target_count, evaluated, errored, remaining, done, error?, version? }`. When `status: 'not_found'` the job either expired (kept ~15 min after completion), never existed, or the MCP restarted since it was created — re-run auto_evaluate.\n\n" +
+        description: "Poll the status of an auto_evaluate job. Response: `{ status: 'running' | 'done' | 'cancelled' | 'error' | 'not_found', engines, target_count, processed, remaining, evaluated: {engine: n}, failed: {engine: n}, failed_node_ids: {engine: [ids]}, last_error?, aborted_reason?, done }`. Retry failures with cloud_analyse({file_id, node_ids}) or a new auto_evaluate. When `status: 'not_found'` the job either expired (kept ~15 min after completion), never existed, or the MCP restarted since it was created — re-run auto_evaluate.\n\n" +
             "Typical poll cadence: every 3-5 s for small walks, every 10-30 s for large ones. Don't hammer — status is a pure in-memory read but polling doesn't speed the engine up.",
         inputSchema: {
             type: "object",
@@ -752,7 +734,7 @@ export const TOOLS = [
     },
     {
         name: "auto_evaluate_cancel",
-        description: "Ask a running auto_evaluate job to stop as soon as its current node finishes. Whatever progress was completed before cancellation is durably saved (checkpoint on cancel). Idempotent — cancelling an already-finished job is a no-op with a clear note in the response.",
+        description: "Ask a running auto_evaluate job to stop after the batch in flight. Every batch already analysed is saved in the file. Idempotent — cancelling an already-finished job is a no-op with a clear note in the response.",
         inputSchema: {
             type: "object",
             properties: {
@@ -763,34 +745,27 @@ export const TOOLS = [
     },
     {
         name: "deep_analyse",
-        description: "Start a long Stockfish think on a single position (up to 5 min movetime). Returns a `job_id` immediately; poll `deep_analyse_status(job_id)` for the result, cancel with `deep_analyse_cancel(job_id)`. Runs SF only — Lc0 doesn't benefit from long thinks past a handful of seconds — and **holds only the SF engine slot on the rental, so `cloud_analyse(..., engines: [\"lc0\"])` stays available for other work in parallel**.\n\n" +
-            "Use this when a specific critical position deserves depth — a novelty candidate, a hairy tactical shot, a difficult endgame — and you want Stockfish at depth 35+ rather than the ~depth 22 you get from a 2s cloud_analyse. Movetime is in ms; typical: 30_000-60_000 for 'careful check', 120_000-300_000 for 'find the truth'.\n\n" +
-            "Result shape when done matches cloud_analyse's Stockfish leg (depth, top-N candidates with scoreCp/mate, best move, PV). Auto-stores the eval on `file_id`+`node_id` when both are supplied, same as cloud_analyse.",
+        description: "Start one long think (up to 5 min) on one position, on one engine (`engine`, default stockfish). Returns a `job_id` immediately; poll deep_analyse_status, cancel with deep_analyse_cancel. It holds only that engine, so cloud_analyse on the other engines keeps working meanwhile.\n\n" +
+            "Use it when a critical position deserves depth: a novelty candidate, a sharp tactic, a hard endgame. Typical movetime: 30_000-60_000 for a careful check, 120_000-300_000 to find the truth.\n\n" +
+            "With `file_id`+`node_id`, the result is merged into that node's ceoEval (other engines' stored reads are kept) and stamped on its transpositions.",
         inputSchema: {
             type: "object",
-            properties: { contract_id: { type: "string", description: "Which of your running rentals to use, from list_cloud_engines. Any engine shape works (combo, stockfish-only, lc0-only). Omit it when only one rental can serve the request; if several can, the error lists their contract ids." },
-                file_id: { type: "string", description: "Prep file id. Combine with `node_id` to derive FEN from the tree AND persist the result on the node's ceoEval." },
+            properties: {
+                engine: { type: "string", enum: ["stockfish", "lc0", "human"], description: "Default stockfish." },
+                file_id: { type: "string", description: "Prep file id. With `node_id`, the FEN comes from the tree and the result is stored on the node." },
                 node_id: { type: "string", description: "Node id inside `file_id`. Root is 'r'. When set, overrides `fen`/`moves`." },
                 fen: { type: "string", description: "Position as FEN. Only used if `node_id` is not set." },
                 moves: { type: "string", description: "Optional SAN moves on top of `fen`. Only used if `node_id` is not set." },
-                movetime_ms: {
-                    type: "integer",
-                    minimum: 5_000,
-                    maximum: 300_000,
-                    description: "Think time in ms. Default 60_000 (1 min). Max 300_000 (5 min).",
-                },
-                multipv: {
-                    type: "integer",
-                    minimum: 1,
-                    maximum: 10,
-                    description: "Number of candidate lines (default 2). Stockfish gets weaker as multipv grows — each extra PV steals search bandwidth from the top choice — so keep this low unless you specifically want to see several candidates ranked deep.",
-                },
+                movetime_ms: { type: "integer", minimum: 5_000, maximum: 300_000, description: "Think time in ms. Default 60_000 (1 min). Max 300_000 (5 min)." },
+                multipv: { type: "integer", minimum: 1, maximum: 10, description: "Candidate lines. Default 2 for stockfish (extra lines cost it strength), 8 for lc0/human." },
+                contempt: { type: "integer", minimum: -100, maximum: 100, description: "lc0 only." },
+                rental: { type: "string", description: "Only when two running rentals provide this engine: the contract_id to use." },
             },
         },
     },
     {
         name: "deep_analyse_status",
-        description: "Poll a deep_analyse job. Response: `{ status: 'running' | 'done' | 'cancelled' | 'error' | 'not_found', elapsed_ms, movetime_ms, result?, error? }`. `result` shape when done: `{ engine, depth, timeMs, bestMove, lines: [{rank, depth, scoreCp?, mate?, pv, nodes?}] }` — the SF leg of a cloud_analyse response.\n\n" +
+        description: "Poll a deep_analyse job. Response: `{ status: 'running' | 'done' | 'cancelled' | 'error' | 'not_found', elapsed_ms, movetime_ms, result?, error? }`. `result` when done: that engine's block from a cloud_analyse response (`{ depth, bestMove, lines: [{rank, depth, scoreCp?, mate?, wdl?, pv}] }`, PVs in SAN, wdl in percent); `stored_on` lists the nodes it was saved to.\n\n" +
             "Poll cadence: every ~15-30s for long thinks; there's no penalty for polling more often but the engine progresses at its own pace.",
         inputSchema: {
             type: "object",
@@ -863,7 +838,7 @@ export const TOOLS = [
     {
         name: "quote_engine_eval",
         description: "Return the stored engine eval for a node, or null if that node was never analysed. **Call this before writing prose or NAGs that quote engine numbers** — if it returns null, you have no measurement to cite. Do NOT infer an eval for the node from siblings or children; either analyse it (cloud_analyse with node_id) or omit the number from your prose.\n\n" +
-            "Response: `{ ceoEval: { sf: {cp, depth}, lc0: {cp, depth}, nag } | null }`. `cp` is White-POV centipawns as an integer (+20 = +0.20). `nag` is the threshold-derived glyph as a SUGGESTION — promote to a visible NAG via set_nags only when a glyph on that move carries editorial signal.",
+            "Response: `{ ceoEval: { sf?: {cp | mate, depth}, lc0?: {w, d, l, depth}, human?: {w, d, l, depth} } | null }`. `cp` is White-POV centipawns (+20 = +0.20); `mate` White-POV moves to mate; `w/d/l` win/draw/loss percent from White's point of view. An engine missing from the object was never run on this position. Files analysed before 0.50 may hold an lc0 `cp` instead of w/d/l.",
         inputSchema: {
             type: "object",
             properties: {