Moddable Games Tools

chess_generate_puzzle

Get a random chess puzzle. Filter by variant or difficulty. Variant puzzles have no themes and max rating 1400 — theme and hard difficulty filters only apply to standard puzzles.

Input Schema

TableJSON Schema

Name	Required	Description
`theme`	No	Puzzle theme (fork, pin, skewer, mateIn2, etc). Only standard puzzles carry themes.
`variant`	No	Chess variant slug, camelCase or kebab-case (e.g. antichess, almost-chess, atomic, chess960, standard). Returns only puzzles for this variant.
`difficulty`	No	Puzzle difficulty (variant puzzles max at 1400, so hard returns nothing for variants)

Schema Changelog

Changes observed during successful MCP inspections.

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

A4.2/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 disclosure burden. It discloses a key limitation (variant puzzles have no themes, max rating 1400, hard difficulty only applies to standard) but does not mention return format, error behavior, or state effects.

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?

Two crisp sentences. The first states the main action and filters; the second explains an important edge case. Every word contributes, and key information is front-loaded.

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 simple random-getter tool with three optional params and no output schema, the description covers the essential filtering constraints and variant limitations. It lacks explicit return-value or no-match behavior details, but is otherwise reasonably complete.

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 baseline is 3. The description adds valuable cross-parameter semantics: it clarifies how variant interacts with theme and difficulty, which the individual schema descriptions do not fully convey.

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

Purpose5/5

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

The description uses a specific verb 'Get' with a clear resource ('random chess puzzle') and immediately names the filtering dimensions (variant, difficulty). This distinguishes it from siblings like chess_list_puzzle_types and chess_analyze_position, which serve different purposes.

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?

It provides clear usage context by stating how to filter and what to expect for variant puzzles. It does not explicitly name alternative tools or when-not-to-use conditions, but the context is strong enough for an agent to know when this tool is appropriate.

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