course_map
ChatGPTUse this when someone wants to learn or improve at chess with lessons, asks what to study next, or wants their course progress. Lists the Goat Pass curriculum (levels 400–1400+, each lesson about 10 minutes: idea, guided examples, a drill, then a checkpoint on a later day), which lessons are free, the member's level per lesson when connected with Goat Pass, and the next lesson to take.
favorite_openings
ChatGPTUse this when someone asks which openings a chess.com player plays most, or which openings score best or worst for them. Returns the most-played opening families by colour with games played, share of games, and score.
game_history
ChatGPTUse this when someone asks about a chess.com player's recent games, results, streaks against a rival, or wants to review specific games. Returns live games (bullet, blitz, rapid) newest first with result, how it ended, ratings, opening, move count, chess.com accuracy when available, and a link to each game.
goat_card
ChatGPTUse this when someone asks what kind of chess player they (or any chess.com player) are, wants their habits, tilt, clock or time-of-day patterns, or asks how to stop losing rating. Builds the free Goat Card from public chess.com games: an archetype, three standout habits with numbers, one stop-loss rule, and frequent rivals. Live games only.
lesson
ChatGPTUse this to teach a course lesson in chat. Returns the lesson's idea steps (positions, lines, arrows, questions), guided "find the move" examples with answers, hints and explanations, and the rule to keep. Free lessons need no sign-in; the rest need a connected Goat Pass. Teach one beat per message, on interactive boards. Steps: show_position with lesson + step (a step with a question is played on the board; otherwise explain it in a sentence or two). Guided examples: show_position with lesson + example; the board checks the move, gives the hints and refutations, and posts the result as a ♟ message; wait for it, then add the explanation in your own words. Never reveal an answer before the learner tries. Finish with the rule, then lesson_puzzles set=drill (each puzzle: show_position puzzle_id + puzzle_theme), then record_lesson part=learn with ok = solved first try from the ♟ messages.
lesson_puzzles
ChatGPTUse this for a lesson's practice. set=drill: 7 puzzles for Part 1, right after the guided examples (the first 3 practise the lesson's idea, the rest are mixed). set=check: 6 new positions for Part 2, the checkpoint, on a later day (members: only once it is due). Show each puzzle with show_position puzzle_id + puzzle_theme (check=true for a checkpoint): the learner plays the whole line on the board, which posts "solved first try" (ok for record_lesson) or a miss as a ♟ message. Keep the solutions hidden. In a checkpoint give no hints and hold feedback until the end.
lessons_for_my_games
ChatGPTUse this when a user wants lessons or a study plan based on how they actually play, asks what to work on, or before starting a lesson for a known chess.com player. Reads their most recent public chess.com games, finds the habits that cost them (with numbers), and maps each to the course lessons that fix it, with links to the recent games that show it. Uses their connected Goat Report too when there is one. Skips lessons a connected member has already made solid.
my_report
ChatGPTUse this when a user has bought or connected a Goat Report, asks about their report, wants coaching based on their paid analysis, a training session, or puzzles from their own games. Reads the report linked to their authenticated connection, including its date. Use overview first, then mistakes, plan, puzzles or trends as needed. Reuse this in future chats; do not ask the user to buy the same report again. If they are not connected, use the host OAuth connection prompt, where they sign in with the email they bought with and their reports are found automatically; never ask for a report link in chat. With several reports, pass report (username). This reads saved analysis and does not analyze new games.
record_lesson
ChatGPTUse this when the learner finishes a part of a lesson, so their Goat Pass progress (shared with trychessgoat.com) counts it. part=learn after the steps, guided examples and drill: pass each drill puzzle id with ok (first try, no hint) and each guided example index with ok. part=check after all checkpoint puzzles: pass each id with ok; 2 of 3 passes, the rule is earned and the lesson comes back for review later. Requires a connected Goat Pass. Only send ids returned by lesson_puzzles for this lesson; never guess results.
show_position
ChatGPTUse this whenever a position should be seen or played: every lesson step, guided example, drill or checkpoint puzzle, or a moment from a game. For lesson beats pass lesson + step or example (index from lesson; -1 = pretest); for puzzles pass puzzle_id + puzzle_theme from lesson_puzzles (check=true in a checkpoint). Those boards are interactive: the learner moves the pieces, the board checks the move, gives the hints, plays the replies and then posts the result in the chat as a message starting with ♟; wait for it, then continue from that result. Never put the answer in the caption.
