Chess Goat

Use 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.

favorite_openings

Use 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.

goat_card

Use 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.

lesson_puzzles

Use 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.

lessons_for_my_games

Use 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. [object Object]

lesson

Use 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 (a report bought with another email is added there by its private link); never ask for a report link in chat. A connected chess.com username alone does not open a report. With several reports, pass report (username). This reads saved analysis and does not analyze new games.

my_report

Use 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.

game_history

Use 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.

record_lesson

Use 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.

show_position

Use 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.

course_map