Lichess Coach MCP

Overview Schema Source Related Servers Discussions Admin

Lichess puzzle by id

get_puzzle

Read-onlyIdempotent

Fetch a Lichess puzzle by 5-character ID to return FEN, side to move, rating, themes, and source game; reveal the solution only when reveal_solution is true.

Instructions

Fetch a Lichess puzzle by id: position (FEN), side to move, rating, themes and source game. The solution stays hidden unless reveal_solution=true.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`id`	Yes	Lichess puzzle id (5 characters, e.g. "uFTip"), as in lichess.org/training/uFTip.
`reveal_solution`	No	Include the solution moves. Leave false to coach: let the player try first, then call again with true.

Output Schema

TableJSON Schema

Name	Required	Description
`id`	Yes
`fen`	Yes	The position the solver faces (after the opponent's last move).
`url`	Yes
`hint`	No	A small nudge (which piece moves first) for when the player is stuck. Present only while the solution is hidden.
`plays`	Yes
`rating`	Yes
`themes`	Yes	Lichess theme tags, e.g. "fork", "mateIn2", "endgame".
`message`	Yes
`solution`	No	Full forced line, solver and opponent moves alternating. Only present when reveal_solution is true.
`last_move`	No	The opponent's move that set up the puzzle.
`source_game`	Yes
`solver_color`	Yes
`solver_moves`	Yes	How many moves the solver must find.
`solution_revealed`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 15, 2026

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly=true, idempotent=true, non-destructive and open-world, so safety is covered. The description adds genuinely useful non-obvious context: the solution payload is withheld unless reveal_solution=true, which tells the agent why a call may return no solution.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One compact sentence plus a conditional clause; the verb and identifier are front-loaded and the return contents are delivered as a tight list. No filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter lookup with a full schema and an output schema, the description covers the essentials. It omits where an agent obtains a puzzle id and any error behavior for invalid ids, but nothing critical to correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description goes slightly beyond the schema by explaining the conditional effect of reveal_solution on the returned payload (solution remains hidden), which is the kind of effect detail that helps decide whether to set it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Fetch a Lichess puzzle by id') and enumerates what comes back (FEN, side to move, rating, themes, source game). It does not, however, name or contrast itself with the close sibling puzzle_of_the_day, which also returns a puzzle, so an agent must infer the distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'By id' weakly implies you must already hold a puzzle id, which is an implied prerequisite rather than stated guidance. There is no explicit when-to-use statement and no routing to alternatives such as puzzle_of_the_day for a random/daily puzzle.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server