chessup-gamma.vercel.app

{
  "name": "read_coach_instructions",
  "kind": "answer",
  "impl": "imperative",
  "description": "Read this first. Explains how to coach on this board: the human plays the built-in bot, you review from `events`, run puzzle drills with set_puzzle_queue, keep a lesson plan and reward progress. Sparring (playing against the human) is optional. Cheap and read-only.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "get_game_state",
  "kind": "answer",
  "impl": "imperative",
  "description": "Read the board: FEN, turn, status, material, engine evaluation, recent moves, active puzzle and drill progress, the human's recent mistakes (heuristics and Stockfish centipawn loss), `events` since your last call and `next`. Call it every time the human talks to you.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "get_legal_moves",
  "kind": "answer",
  "impl": "imperative",
  "description": "List legal moves in SAN (optionally only for one square, then with from/to details), plus the best capture and any mate in one. Use it to check a move before make_move or to build hints.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "square": {
        "type": "string",
        "description": "Optional square like 'e2' to list only moves of the piece on that square."
      }
    },
    "additionalProperties": false
  }
}

{
  "name": "undo_move",
  "kind": "act",
  "impl": "imperative",
  "description": "Take back the last N half-moves (default 1) so the human can retry; also reactivates a failed puzzle.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "count": {
        "type": "integer",
        "minimum": 1,
        "maximum": 200,
        "description": "Number of half-moves to undo. Default 1."
      }
    },
    "additionalProperties": false
  }
}

{
  "name": "analyze_position",
  "kind": "act",
  "impl": "imperative",
  "description": "Run the built-in Stockfish engine on the current position (or a given FEN): evaluation from White's perspective, best move and line, and up to 3 alternatives with their evaluations. Use it to verify a claim before teaching it, to find the best move for a review, or to check a puzzle idea. Depth 8-20 (default 14).",
  "inputSchema": {
    "type": "object",
    "properties": {
      "fen": {
        "type": "string",
        "description": "Position to analyse. Defaults to the board."
      },
      "depth": {
        "type": "integer",
        "minimum": 8,
        "maximum": 20,
        "description": "Search depth. Default 14."
      },
      "multipv": {
        "type": "integer",
        "minimum": 1,
        "maximum": 3,
        "description": "How many best lines to return. Default 1."
      }
    },
    "additionalProperties": false
  }
}

{
  "name": "highlight_squares",
  "kind": "act",
  "impl": "imperative",
  "description": "Colour squares to draw attention: green good/safe, red danger, yellow key square, blue plan, orange warning. Replaces highlights unless append=true. Cleared automatically on the next move.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "squares": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Squares like ['e4','d5']."
      },
      "color": {
        "type": "string",
        "enum": [
          "green",
          "red",
          "yellow",
          "blue",
          "orange"
        ],
        "description": "Highlight colour. Default green."
      },
      "append": {
        "type": "boolean",
        "description": "Keep existing highlights and add these. Default false."
      }
    },
    "required": [
      "squares"
    ],
    "additionalProperties": false
  }
}

{
  "name": "draw_arrows",
  "kind": "act",
  "impl": "imperative",
  "description": "Draw arrows for plans, threats or candidate moves. Replaces arrows unless append=true. Cleared automatically on the next move.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "arrows": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "from": {
              "type": "string",
              "description": "Start square, e.g. 'g1'."
            },
            "to": {
              "type": "string",
              "description": "End square, e.g. 'f3'."
            },
            "color": {
              "type": "string",
              "enum": [
                "green",
                "red",
                "yellow",
                "blue",
                "orange"
              ],
              "description": "Arrow colour. Default green."
            }
          },
          "required": [
            "from",
            "to"
          ]
        }
      },
      "append": {
        "type": "boolean",
        "description": "Keep existing arrows and add these. Default false."
      }
    },
    "required": [
      "arrows"
    ],
    "additionalProperties": false
  }
}

{
  "name": "clear_annotations",
  "kind": "act",
  "impl": "imperative",
  "description": "Remove all highlights and arrows from the board.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "coach_note",
  "kind": "act",
  "impl": "imperative",
  "description": "Show a one-sentence caption under the board (tip, praise, warning, question or info) tied to what is on the board right now. Put explanations in the chat, not here.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "text": {
        "type": "string",
        "description": "The note text."
      },
      "kind": {
        "type": "string",
        "enum": [
          "tip",
          "praise",
          "warning",
          "question",
          "info"
        ],
        "description": "Visual style of the note. Default 'tip'."
      }
    },
    "required": [
      "text"
    ],
    "additionalProperties": false
  }
}

{
  "name": "set_lesson_plan",
  "kind": "act",
  "impl": "imperative",
  "description": "Replace the lesson plan in the side panel: a title and 3-6 steps with status todo/active/done/skipped. The page seeds a simple plan (play, review, drill) from the profile; replace it with a better one once you know the student, and keep it current with update_lesson_step.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "description": "Plan title, e.g. 'Today: stop hanging pieces'."
      },
      "steps": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "title": {
              "type": "string"
            },
            "description": {
              "type": "string"
            },
            "status": {
              "type": "string",
              "enum": [
                "todo",
                "active",
                "done",
                "skipped"
              ]
            }
          },
          "required": [
            "title"
          ]
        }
      }
    },
    "required": [
      "steps"
    ],
    "additionalProperties": false
  }
}

{
  "name": "update_lesson_step",
  "kind": "act",
  "impl": "imperative",
  "description": "Update one lesson step by zero-based index: status (todo/active/done/skipped), title or description. Mark steps active when started and done when completed.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "index": {
        "type": "integer",
        "minimum": 0,
        "description": "Zero-based index of the step."
      },
      "status": {
        "type": "string",
        "enum": [
          "todo",
          "active",
          "done",
          "skipped"
        ]
      },
      "title": {
        "type": "string"
      },
      "description": {
        "type": "string"
      }
    },
    "required": [
      "index"
    ],
    "additionalProperties": false
  }
}

{
  "name": "award_badge",
  "kind": "act",
  "impl": "imperative",
  "description": "Give a uniquely named badge with an emoji for a real milestone (first puzzle solved, a clean game, a new pattern learned). Badges are permanent in the profile.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "description": "Badge name, e.g. 'Fork Master'."
      },
      "description": {
        "type": "string",
        "description": "Why it was earned."
      },
      "emoji": {
        "type": "string",
        "description": "A single emoji, e.g. '🍴'."
      }
    },
    "required": [
      "name",
      "description"
    ],
    "additionalProperties": false
  }
}

{
  "name": "add_xp",
  "kind": "act",
  "impl": "imperative",
  "description": "Add XP with a reason (negative allowed). Scale: 5-10 for a good move or answer, 20-40 for a puzzle, 50+ for a won game or a finished lesson step. Returns total, level and leveledUp.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "amount": {
        "type": "integer",
        "description": "XP to add (can be negative)."
      },
      "reason": {
        "type": "string",
        "description": "Short reason shown to the student."
      }
    },
    "required": [
      "amount",
      "reason"
    ],
    "additionalProperties": false
  }
}

{
  "name": "record_mistake",
  "kind": "act",
  "impl": "imperative",
  "description": "Log a mistake the app cannot detect itself (opening, king safety, positional, endgame) into the human's long-term profile with severity, FEN before the move, movePlayed and betterMove. Simple tactical errors are auto-recorded.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "category": {
        "type": "string",
        "enum": [
          "hanging_piece",
          "missed_mate",
          "allowed_mate",
          "missed_capture",
          "opening",
          "endgame",
          "tactics",
          "positional",
          "king_safety",
          "other"
        ]
      },
      "severity": {
        "type": "string",
        "enum": [
          "inaccuracy",
          "mistake",
          "blunder"
        ],
        "description": "Default 'mistake'."
      },
      "description": {
        "type": "string",
        "description": "One sentence the student will read later."
      },
      "fen": {
        "type": "string",
        "description": "Position before the mistake. Defaults to the position before the last move."
      },
      "movePlayed": {
        "type": "string",
        "description": "The move the student played (SAN)."
      },
      "betterMove": {
        "type": "string",
        "description": "What should have been played (SAN)."
      }
    },
    "required": [
      "category",
      "description"
    ],
    "additionalProperties": false
  }
}

{
  "name": "get_player_profile",
  "kind": "answer",
  "impl": "imperative",
  "description": "Read the persistent profile: XP, level, badges, game and puzzle stats by theme, mistakes by category, weakestAreas, recent drills, the lesson plan, and candidatePuzzles: validated puzzles built from the human's own mistakes, ready to pass to set_puzzle_queue. Call it at session start and before every drill.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "make_move",
  "kind": "act",
  "impl": "imperative",
  "description": "Play a move for the side to move. Use it in sparring mode (opponent 'agent') or to demonstrate a line. SAN ('Nf3', 'O-O', 'e8=Q') or from/to. Illegal moves are rejected with the legal list. Refused during the human's turn in an active puzzle. In sparring, follow with wait_for_player_move.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "san": {
        "type": "string",
        "description": "Move in Standard Algebraic Notation, e.g. 'Nf3'."
      },
      "from": {
        "type": "string",
        "description": "Origin square, e.g. 'e2' (use together with `to`)."
      },
      "to": {
        "type": "string",
        "description": "Target square, e.g. 'e4'."
      },
      "promotion": {
        "type": "string",
        "enum": [
          "q",
          "r",
          "b",
          "n"
        ],
        "description": "Promotion piece when a pawn reaches the last rank. Defaults to queen."
      },
      "comment": {
        "type": "string",
        "description": "Optional short explanation shown to the human next to the move."
      }
    },
    "additionalProperties": false
  }
}

{
  "name": "new_game",
  "kind": "act",
  "impl": "imperative",
  "description": "Reset to the starting position. Choose the human's colour and the opponent: 'bot' (default, built-in engine level 1-3, instant), 'agent' (sparring: you play via make_move + wait_for_player_move) or 'human' (they play both sides). Clears any puzzle or drill.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "playerColor": {
        "type": "string",
        "enum": [
          "white",
          "black"
        ],
        "description": "Colour the human plays. Default white."
      },
      "opponent": {
        "type": "string",
        "enum": [
          "bot",
          "agent",
          "human"
        ],
        "description": "Who plays the other side. Default 'bot'; 'agent' = sparring with you."
      },
      "botLevel": {
        "type": "integer",
        "enum": [
          1,
          2,
          3
        ],
        "description": "Strength of the built-in bot when opponent is 'bot'."
      },
      "cancelDrill": {
        "type": "boolean",
        "description": "Set true to abandon an active drill on purpose."
      }
    },
    "additionalProperties": false
  }
}

{
  "name": "set_position",
  "kind": "act",
  "impl": "imperative",
  "description": "Put a FEN on the board, or a single puzzle when you add title, goal, hint, theme and a SAN `solution` (human's move first, alternating sides). The app validates the line, auto-plays replies and grades the human. For several puzzles use set_puzzle_queue. Without title/goal/solution it only sets the position.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "fen": {
        "type": "string",
        "description": "Full FEN string, e.g. 'r1bqkb1r/pppp1ppp/2n2n2/4p2Q/2B1P3/8/PPPP1PPP/RNB1K1NR w KQkq - 4 4'."
      },
      "title": {
        "type": "string",
        "description": "Short puzzle title, e.g. 'Back-rank mate'."
      },
      "goal": {
        "type": "string",
        "description": "What the student must achieve, e.g. 'White to play and win a piece'."
      },
      "hint": {
        "type": "string",
        "description": "Optional hint the student can reveal."
      },
      "theme": {
        "type": "string",
        "description": "Tactical/strategic theme tag for tracking, e.g. 'fork', 'pin', 'mate_in_1'."
      },
      "solution": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Solution line in SAN, student's move first, alternating sides. e.g. ['Qxf7#'] or ['Nxe5','Nxe5','Qh5+','g6','Qxe5']."
      },
      "playerColor": {
        "type": "string",
        "enum": [
          "white",
          "black"
        ],
        "description": "Which colour the student plays. Defaults to the side to move in the FEN."
      },
      "cancelDrill": {
        "type": "boolean",
        "description": "Set true to abandon an active drill on purpose."
      }
    },
    "required": [
      "fen"
    ],
    "additionalProperties": false
  }
}

{
  "name": "set_puzzle_queue",
  "kind": "act",
  "impl": "imperative",
  "description": "Start a drill: 3-5 puzzles the app serves one by one, grades against the solution, auto-plays replies, awards XP and records results per theme. Each puzzle: fen, title, goal, optional hint, theme, and a SAN `solution` (human's move first, alternating). Every line is checked for legality and by Stockfish (the human's moves must be best); rejected puzzles come back with the reason. After calling it, END YOUR TURN; the human tells you when done.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "description": "Drill title, e.g. 'Hanging pieces, round 1'."
      },
      "puzzles": {
        "type": "array",
        "minItems": 1,
        "maxItems": 8,
        "items": {
          "type": "object",
          "properties": {
            "fen": {
              "type": "string",
              "description": "Full FEN of the puzzle position."
            },
            "title": {
              "type": "string",
              "description": "Short title."
            },
            "goal": {
              "type": "string",
              "description": "What to achieve, e.g. 'White to play and win a piece'."
            },
            "hint": {
              "type": "string",
              "description": "Optional hint the human can reveal."
            },
            "theme": {
              "type": "string",
              "description": "Theme tag, e.g. 'fork', 'back_rank', 'hanging_piece'."
            },
            "solution": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "SAN line, human's move first."
            }
          },
          "required": [
            "fen",
            "title",
            "goal",
            "solution"
          ]
        }
      },
      "cancelDrill": {
        "type": "boolean",
        "description": "Set true to replace an active drill on purpose."
      }
    },
    "required": [
      "puzzles"
    ],
    "additionalProperties": false
  }
}