Moddable Games Tools

chess_generate_puzzle

Get a random chess puzzle. Filter by variant, difficulty or theme. Not every variant puzzle carries themes; use chess_list_puzzle_types to see what the pool holds.

Input Schema

TableJSON Schema

Name	Required	Description
`theme`	No	Puzzle theme (fork, pin, skewer, mateIn2, etc). Not every variant puzzle carries themes.
`variant`	No	Chess variant play slug (e.g. almost-chess, benedict, fischer-random, king-of-the-hill, standard); a manifest key such as chess960 is also accepted. Returns only puzzles for this variant.
`difficulty`	No	Puzzle difficulty by rating: easy under 1200, medium 1200-1799, hard 1800 and above

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 29, 2026

changedInput schema / properties / variant / description

Previous value: -"Chess variant slug, camelCase or kebab-case (e.g. almost-chess, capablanca, king-of-the-hill, standard). Returns only puzzles for this variant."New value: +"Chess variant play slug (e.g. almost-chess, benedict, fischer-random, king-of-the-hill, standard); a manifest key such as chess960 is also accepted. Returns only puzzles for this variant."

Changed3 schema fields changedSep 28, 2026

changedInput schema / properties / difficulty / description

Previous value: -"Puzzle difficulty (variant puzzles max at 1400, so hard returns nothing for variants)"New value: +"Puzzle difficulty by rating: easy under 1200, medium 1200-1799, hard 1800 and above"

changedInput schema / properties / theme / description

Previous value: -"Puzzle theme (fork, pin, skewer, mateIn2, etc). Only standard puzzles carry themes."New value: +"Puzzle theme (fork, pin, skewer, mateIn2, etc). Not every variant puzzle carries themes."

changedInput schema / properties / variant / description

Previous value: -"Chess variant slug, camelCase or kebab-case (e.g. antichess, almost-chess, atomic, chess960, standard). Returns only puzzles for this variant."New value: +"Chess variant slug, camelCase or kebab-case (e.g. almost-chess, capablanca, king-of-the-hill, standard). Returns only puzzles for this variant."

Changed3 schema fields changedAug 17, 2026

changedInput schema / properties / difficulty / description

Previous value: -"Puzzle difficulty"New value: +"Puzzle difficulty (variant puzzles max at 1400, so hard returns nothing for variants)"

changedInput schema / properties / theme / description

Previous value: -"Puzzle theme (fork, pin, skewer, mate-in-2, etc)"New value: +"Puzzle theme (fork, pin, skewer, mateIn2, etc). Only standard puzzles carry themes."

addedInput schema / properties / variant

Added value: +{
+  "description": "Chess variant slug, camelCase or kebab-case (e.g. antichess, almost-chess, atomic, chess960, standard). Returns only puzzles for this variant.",
+  "type": "string"
+}

Changed7 schema fields changedAug 7, 2026

addedInput schema / properties / difficulty

Added value: +{
+  "description": "Puzzle difficulty",
+  "enum": [
+    "easy",
+    "medium",
+    "hard"
+  ],
+  "type": "string"
+}

removedInput schema / properties / include_svg

Removed value: -{
-  "description": "Include an SVG board render of the puzzle position. Defaults to true.",
-  "type": "boolean"
-}

removedInput schema / properties / rating_max

Removed value: -{
-  "description": "Maximum puzzle rating filter. Omit for no maximum.",
-  "type": "number"
-}

removedInput schema / properties / rating_min

Removed value: -{
-  "description": "Minimum puzzle rating filter (Lichess rating scale). Omit for no minimum.",
-  "type": "number"
-}

changedInput schema / properties / theme / description

Previous value: -"Filter by puzzle theme (e.g. \"backRankMate\", \"sacrifice\", \"endgame\"). Only applies to Lichess-sourced puzzles."New value: +"Puzzle theme (fork, pin, skewer, mate-in-2, etc)"

removedInput schema / properties / type

Removed value: -{
-  "description": "Puzzle type (e.g. \"mate-in-1\", \"detonate-in-1\", \"sacrifice-your-king\"). Defaults to the first available type for the variant. Use chess_list_puzzle_types to see all types.",
-  "type": "string"
-}

removedInput schema / properties / variant

Removed value: -{
-  "description": "Variant key (e.g. \"standard\", \"atomic\", \"racingKings\") or \"random\" for a surprise variant. Defaults to \"standard\". Use chess_list_puzzle_types to see all available variants.",
-  "type": "string"
-}

Changed7 schema fields changedJul 27, 2026

removedInput schema / properties / difficulty

Removed value: -{
-  "description": "Puzzle difficulty",
-  "enum": [
-    "easy",
-    "medium",
-    "hard"
-  ],
-  "type": "string"
-}

addedInput schema / properties / include_svg

Added value: +{
+  "description": "Include an SVG board render of the puzzle position. Defaults to true.",
+  "type": "boolean"
+}

addedInput schema / properties / rating_max

Added value: +{
+  "description": "Maximum puzzle rating filter. Omit for no maximum.",
+  "type": "number"
+}

addedInput schema / properties / rating_min

Added value: +{
+  "description": "Minimum puzzle rating filter (Lichess rating scale). Omit for no minimum.",
+  "type": "number"
+}

changedInput schema / properties / theme / description

Previous value: -"Puzzle theme (fork, pin, skewer, mate-in-2, etc)"New value: +"Filter by puzzle theme (e.g. \"backRankMate\", \"sacrifice\", \"endgame\"). Only applies to Lichess-sourced puzzles."

addedInput schema / properties / type

Added value: +{
+  "description": "Puzzle type (e.g. \"mate-in-1\", \"detonate-in-1\", \"sacrifice-your-king\"). Defaults to the first available type for the variant. Use chess_list_puzzle_types to see all types.",
+  "type": "string"
+}

changedInput schema / properties / variant / description

Previous value: -"Variant slug (default: standard)"New value: +"Variant key (e.g. \"standard\", \"atomic\", \"racingKings\") or \"random\" for a surprise variant. Defaults to \"standard\". Use chess_list_puzzle_types to see all available variants."

Changed7 schema fields changedJul 26, 2026

addedInput schema / properties / difficulty

Added value: +{
+  "description": "Puzzle difficulty",
+  "enum": [
+    "easy",
+    "medium",
+    "hard"
+  ],
+  "type": "string"
+}

removedInput schema / properties / include_svg

Removed value: -{
-  "description": "Include an SVG board render of the puzzle position. Defaults to true.",
-  "type": "boolean"
-}

removedInput schema / properties / rating_max

Removed value: -{
-  "description": "Maximum puzzle rating filter. Omit for no maximum.",
-  "type": "number"
-}

removedInput schema / properties / rating_min

Removed value: -{
-  "description": "Minimum puzzle rating filter (Lichess rating scale). Omit for no minimum.",
-  "type": "number"
-}

changedInput schema / properties / theme / description

Previous value: -"Filter by puzzle theme (e.g. \"backRankMate\", \"sacrifice\", \"endgame\"). Only applies to Lichess-sourced puzzles."New value: +"Puzzle theme (fork, pin, skewer, mate-in-2, etc)"

removedInput schema / properties / type

Removed value: -{
-  "description": "Puzzle type (e.g. \"mate-in-1\", \"detonate-in-1\", \"sacrifice-your-king\"). Defaults to the first available type for the variant. Use chess_list_puzzle_types to see all types.",
-  "type": "string"
-}

changedInput schema / properties / variant / description

Previous value: -"Variant key (e.g. \"standard\", \"atomic\", \"racingKings\") or \"random\" for a surprise variant. Defaults to \"standard\". Use chess_list_puzzle_types to see all available variants."New value: +"Variant slug (default: standard)"

Changed7 schema fields changedJun 21, 2026

addedInput schema / properties / include_svg

Added value: +{
+  "description": "Include an SVG board render of the puzzle position. Defaults to true.",
+  "type": "boolean"
+}

addedInput schema / properties / rating_max

Added value: +{
+  "description": "Maximum puzzle rating filter. Omit for no maximum.",
+  "type": "number"
+}

addedInput schema / properties / rating_min

Added value: +{
+  "description": "Minimum puzzle rating filter (Lichess rating scale). Omit for no minimum.",
+  "type": "number"
+}

addedInput schema / properties / theme

Added value: +{
+  "description": "Filter by puzzle theme (e.g. \"backRankMate\", \"sacrifice\", \"endgame\"). Only applies to Lichess-sourced puzzles.",
+  "type": "string"
+}

changedInput schema / properties / type / description

Previous value: -"Puzzle type. Defaults to \"mate-in-1\"."New value: +"Puzzle type (e.g. \"mate-in-1\", \"detonate-in-1\", \"sacrifice-your-king\"). Defaults to the first available type for the variant. Use chess_list_puzzle_types to see all types."

removedInput schema / properties / type / enum

Removed value: -[
-  "mate-in-1",
-  "mate-in-2",
-  "tactics"
-]

changedInput schema / properties / variant / description

Previous value: -"Variant key. Defaults to \"standard\"."New value: +"Variant key (e.g. \"standard\", \"atomic\", \"racingKings\") or \"random\" for a surprise variant. Defaults to \"standard\". Use chess_list_puzzle_types to see all available variants."

First observedJun 10, 2026

TDQS

A3.6/5.0

Behavior3/5

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that not every variant puzzle carries themes (so a theme filter may return nothing), but says nothing about what happens when filters match no puzzles, whether the draw is from all variants by default, or what the response contains.

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

Conciseness4/5

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

Three short sentences, front-loaded with the purpose before filters and caveat. The last two sentences both circle the theme caveat, which is mild redundancy, but there is no filler and nothing is buried.

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?

All three parameters are optional and documented in the schema, so the description needs mostly to frame the draw and its filter semantics, which it does. It could say more about the no-filter default and the shape of a returned puzzle, but for a simple random-draw tool it is close to complete.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all three parameters including the difficulty rating bands and variant slug format. The description's only added nuance is the theme caveat, which the schema's own theme description repeats almost verbatim, so it adds essentially nothing beyond structured data.

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 ('Get a random chess puzzle') plus the filterable dimensions, so an agent immediately knows this is a random-draw tool rather than a lookup. It references chess_list_puzzle_types, which implicitly routes it apart from the listing tool, though it doesn't explicitly contrast with other random-draw siblings like rules_random.

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

Usage Guidelines4/5

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

'Filter by variant, difficulty or theme' tells the agent how to narrow the draw, and 'use chess_list_puzzle_types to see what the pool holds' names a concrete alternative for discovery. It never states when NOT to use this tool (e.g. when the caller already has a specific puzzle id), so it stops short of a full when/when-not pair.

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

All Moddable Games Tools tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

chess_generate_puzzle

Input Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources