Riddle

riddle_builder_create

Builds a new Riddle of any of the nine types from a build configuration: "type" says which kind (see that argument for what each one is and what it needs at a minimum), "build" carries the content. Everything a type accepts is described on the "build" fields themselves, marked with the types it belongs to; the exhaustive per-type shapes are in riddle://reference/riddle-builder/riddle-types, the block types in riddle://reference/riddle-builder/block-types, and the human help pages at https://www.riddle.com/help/api/build-riddles/riddle-types-and-other-blocks/. To change an existing Riddle instead, use riddle_builder_update (a merge, not a rebuild); to check a configuration without creating anything, riddle_builder_validate. Returns the compact build-configuration envelope of riddle_get (riddle://reference/response-format), with 'queued': true added when queue is set. The new Riddle's view URL comes back in it - "context.viewUrl" once published, "context.viewUrlUnavailable.url" (already final, not live yet) before that.

Input Schema

TableJSON Schema

Name	Required	Description
`omit`	No	Sections of the returned envelope to leave out; omit the parameter for the whole envelope. "uuid"/"type"/"modifiedAt" are always returned, and whatever you leave out is echoed back under "omittedFields", so a missing key never means the Riddle has none of it. Details: riddle://reference/concepts/warnings.
`type`	Yes	Which kind of Riddle to build - this decides which "build" fields and which block types exist. Quiz: questions with right and wrong answers, scored, one result page per score range (title + blocks). Poll: opinion questions, nothing right or wrong, one shared result page (title + blocks). Personality: answers score towards personalities, the winner is the result (title + blocks + personalities). Form: lead-collecting fields only, no questions (title + blocks). Predictor: predictions of real-world outcomes, scored once the actual result is entered (title + blocks). Minigame: SlotMachine, WheelSpinner, Sudoku, Minesweeper or Crosswords (title + blocks). Story: linear content pages, no answers of any kind (title + blocks). Leaderboard: a standalone ranking other published Riddles connect to, no blocks (title). Placeholder: no content of its own, routes to another Riddle by prioritized, time-windowed rules (title). Per-type shapes: riddle://reference/riddle-builder/riddle-types.
`build`	Yes	The build configuration of the Riddle type named in "type".This is the raw build configuration in the engine's own key names - the exact same shape riddle_get returns under "build", riddle_builder_update takes, and riddle_builder_validate dry-runs, so a read-back can be fed straight back in - riddle_get's "build" KEY, never the outer envelope around it, whose "uuid" and siblings are rejected as unsupported properties. Unknown keys are rejected rather than ignored. WHICH fields exist is decided by "type": each one below opens with the types it belongs to, and a field the chosen type does not have is rejected. Only "title" exists on all nine.
`queue`	No	Whether to queue the creation asynchronously.
`project`	No	The project ID; pass NULL for personal project; omit to use the currently selected project.
`publish`	No	Whether to publish the Riddle right after creation; default false (draft). Distinct from the "publish" field INSIDE the build config, which is the stored publish configuration.
`templateId`	No	Only when this build config came from a template you adapted (riddle_template_get): that template's id. Always pass it when you have one - the new Riddle then starts out on the template's whole DESIGN, including what no build config can express, with your build config applied on top. The content is yours either way. Details: riddle://reference/concepts/unknown-properties.

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

AddedSep 2, 2026

TDQS

A4.3/5.0

Behavior4/5

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

The annotations are sparse (no readOnly/destructive hints, idempotent false, openWorld false), and the description adds meaningful creation behavior: it returns the compact riddle_get envelope, adds 'queued': true when queueing is set, and explains how the view URL appears before and after publication. It doesn't fully describe async queue behavior or failure modes, but it goes beyond annotations and schema.

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

Conciseness3/5

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

The description is dense and information-rich but not actually concise: the first paragraph is a long semicolon-heavy run-on sentence mixing type semantics, references, sibling alternatives, and return behavior. It front-loads the core action and alternatives, but it is harder to scan than it could be given how much detail the input schema already carries.

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

Completeness5/5

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

For a complex creation tool with nested objects, seven parameters, and no output schema, the description is remarkably complete: it explains the return envelope, the queued flag, the view URL semantics, the build-configuration model, and points to authoritative references for per-type shapes, block types, preset, publish, and response format. An agent has enough to select and call the tool correctly and to know what it will get back.

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 baseline is 3 per the rubric. The tool description mostly defers to schema fields ("see that argument", "described on the build fields themselves") rather than adding new parameter semantics; the real value is the conditional per-type docs and references, not new elucidation of the parameters themselves.

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 opens with a specific verb and resource, "Builds a new Riddle," and explains the build/type configuration model. It also names the sibling distinctions (riddle_builder_update for edits, riddle_builder_validate for dry-run checks), so an agent can immediately tell this tool apart from adjacent operations.

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

Usage Guidelines5/5

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

The description explicitly says when not to use this tool: "To change an existing Riddle instead, use riddle_builder_update... to check a configuration without creating anything, riddle_builder_validate." This is concrete routing guidance, not just an implication.

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

All Riddle tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.4/5.0

Disambiguation5/5

Each tool is scoped to a distinct resource/action area: media, palettes, projects, question banks, Riddles, templates, tags, stats, and support. Potentially close pairs like riddle_tag/riddle_tag_delete and question_bank_delete/question_bank_manage are cleanly separated by their descriptions, so an agent can reliably select the right one.

Naming Consistency4/5

The naming is mostly consistent snake_case with strong resource prefixes like riddle_, question_bank_, and template_, followed by clear verbs. Minor deviations such as question_bank_item, riddle_tag, and stats_fetch break the strict verb-noun pattern but remain predictable once the convention is understood.

Tool Count3/5

At 38 tools this is a heavy surface, though the breadth is justified by the many subdomains the server covers: media, palettes, projects, question banks, Riddles, templates, tags, and stats. Most tools earn their place, but the count sits above the range where an agent can quickly survey all options.

Completeness4/5

The set covers the full lifecycle for Riddles, question banks, templates, and tags, including publish/unpublish, move, stats, and media upload/delete. Minor gaps like no media library listing and read-only project settings are workable because media IDs come from upload responses and project permissions are exposed.

Resources

Need Help?