PlyMove

Use when the user asks "what if I had played X?" at a specific move in a game already loaded (PGN or prior storyboard analysis_id). Validates the exact alternative SAN, builds a Stockfish continuation, compares to the played move, and estimates Maia naturalness at target_elo. Never substitutes a different move — illegal alternatives return an explicit error. Requires alternative_move_san, target_elo, and (pgn or analysis_id) plus (anchor_ply or move_label).

analyze_what_if

Use when the user provides a PGN and wants an Elo-aware game storyboard: opening context, story arc, ranked critical chapters with causal sequences, what-if branches, and a main lesson. Requires pgn and target_elo. If Elo is missing, ask for it. Prefer this over piecemeal teaching-moment tools for whole-game requests.

build_game_storyboard

Use when the user wants a pedagogical comparison of two or more candidate moves in a position for a learner at a specific Elo. Frame suitability and teaching value, not only engine evaluation. Requires FEN, moves (SAN array), and target_elo.

compare_moves

Legacy alias for whole-game analysis. Prefer build_game_storyboard. Returns an Elo-aware game storyboard (opening, arc, ranked chapters, main lesson). Requires pgn and target_elo.

explain_game

Use when the user wants a learner-specific explanation of a chess position, including which concepts, moves, tactics or strategic ideas are most worth teaching at a specified Elo. Requires a FEN and target_elo. If Elo is missing, ask: "What rating should I explain this for?" Do not invent a rating.

explain_position