Riddle

riddle_builder_update

Edits an existing Riddle of any type with the same build configuration the riddle_builder_ tools take - but as a merge, not a rebuild: only what you send is changed. Blocks are addressed by their ID and can be added with "$create": true, removed with "$delete": true (see the "blocks" field) or reordered with "$blocksOrder" - and so are the entries of a block's "items"/"fields" and, for a Personality Test, its "personalities" (which cannot be reordered, see that field); a Placeholder's "conditions" is replaced as a whole though (see that field). Read the Riddle with riddle_get first to get its block IDs and current build configuration - what it returns under "build" is exactly the shape this takes, so it can be fed straight back in. Only Riddles that were created via the Riddle Builder tools (riddle_builder_*) or generated by the Riddle AI can be edited here - a Riddle the user built manually in the Creator can hold content this build config cannot express (riddle_get reports it as "warnings"), so editing it from here would mean editing around content you never saw, and it is rejected. Check context.origin.apiManageable on riddle_get (or "origin" on riddle_list/riddle_account_list) beforehand instead of finding out from the error; reading such a Riddle keeps working. Returns the edited Riddle in the same compact build-configuration envelope riddle_get returns ({uuid, type, modifiedAt, build, nextBlockId, warnings, published, context}). To replace a Riddle wholesale instead, build a new one with the riddle_builder_ tool of its type.

Input Schema

TableJSON Schema

Name	Required	Description
`UUID`	Yes	The UUID of the Riddle to edit (as returned by riddle_list / riddle_get)
`omit`	No	Leaves parts of the returned envelope out. Values: "build", "warnings", "nextBlockId", "published", "context" (whole sections) and "build.omittedDefaults" (the per-block maps of properties left at their default, inside every build config in the response). Omit for the whole envelope. "uuid"/"type"/"modifiedAt" are always returned. Reach for omit: ["build.omittedDefaults"] on almost every build - it drops ~85-90% of the read-back and loses nothing, since riddle://reference/block-defaults/<block type> states the same defaults; what you must not do either way is resend those values. When you leave anything out the response names it under "omittedFields", so a missing key never means the Riddle has none of it. Same parameter as riddle_get's.
`build`	Yes	The changes to apply, as a partial build configuration in the engine's own key names - the same shape riddle_get returns under "build" and the riddle_builder_<type> tools take. Only the fields you send are touched; send at least one. A field only exists for the Riddle types that have it, and unknown keys are rejected rather than ignored.
`publish`	No	Whether to publish the Riddle after the edit; default is false, which leaves the changes in the draft. It rides along with an edit, it is not one: this tool with publish: true and an empty "build" is rejected with "Nothing to edit: send at least one of ...". To publish what is already in the draft, call riddle_publish.

TDQS

A4.9/5.0

Behavior5/5

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

With annotations limited to idempotentHint:false, the description carries the full burden of behavior disclosure and does so thoroughly. It describes merge semantics, ID-addressed block edits, '$create'/'$delete' rules, reordering via arrays, collections that are wholly replaced (like 'conditions'), and the reversible cautions such as deleted personalities taking their scores. It even discloses the subtle permanent-deletion hazard of resending lossy readback data. This exceeds the minimal behavioral expectations.

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?

The description is front-loaded, with the core merge-vs-rebuild distinction stated in the first sentence. Although dense, it never wastes words: each clause adds an actionable constraint or workflow detail, and it flags deeper subtleties with 'see that field' pointers rather than restating the schema. For a tool this complex, the size is appropriate and every sentence earns its place.

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?

Since there is no output schema, the description covers what the tool returns, including the full response envelope: '{uuid, type, modifiedAt, build, nextBlockId, warnings, published, context}'. It also establishes the relationships to `riddle_get`, the builder tools, and API-manageable state, which a caller needs to know before invoking the edit. Paired with the rich input schema, the definition supplies all critical information for accurate invocation.

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?

The schema has 100% parameter description coverage, so the baseline is 3. The description still contributes beyond the schema by explaining merge-edit semantics (only touched fields change), showing the $create/$delete/$blocksOrder shapes, and linking the `build` parameter to riddle_get's output as a feed-in shape. While it doesn't restate every parameter, it clarifies which collections merge by ID and which are wholesale replacements, which is additional semantic value above strong schema coverage.

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 first sentence states the exact action: 'Edits an existing Riddle of any type' using the build configuration of the riddle_builder_<type> tools, and immediately distinguishes its behavior with 'merge, not a rebuild: only what you send is changed.' It also names the alternative for full replacement: 'build a new one with the riddle_builder_<type> tool of its type.' This leaves no ambiguity about what the tool does or how it differs from siblings.

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 gives an explicit workflow: 'Read the Riddle with riddle_get first to get its block IDs and current build configuration', and tells the agent to check 'context.origin.apiManageable' before attempting an edit. It also defines the conditions for use against non-API Riddles and provides the when-not: manual Riddles are rejected, so a wholesale replacement goes to the type-specific builder. This is a clear when / when-not / alternatives directive.

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.1/5.0

Disambiguation5/5

Each tool has a clear, unique purpose. The riddle_builder_* variants are distinct by Riddle type, questionBank_* and riddleTemplate_* cover separate objects, and stats_* differ by scope. No two tools appear to perform the same function.

Naming Consistency4/5

Naming is largely consistent with domain prefixes (riddle_, questionBank_, riddleTemplate_, stats_, project_, palette_, reference_). Minor deviations like riddle_account_list vs. riddle_list and whoami (no prefix) and riddle_get_embed_code vs. riddle_qr_code slightly break the pattern, but overall it is predictable.

Tool Count2/5

With 62 tools, the server is far beyond the typical 3-15 well-scoped range. While each tool is functional and the breadth reflects the platform's complexity, the sheer number makes it heavy and increases the cognitive load for an agent, suggesting over-granularity.

Completeness5/5

The tool set covers the full lifecycle: create (builder variants), read (get/list), update (builder_update, rename), delete, publish/unpublish, tagging, templates, question banks, stats, projects, palettes, and reference documentation. No obvious domain operation is missing.

Resources

Need Help?