Riddle

reference_get

Read-only

Read the documentation of this MCP server: the block types, form field types, result blocks, palette values and response shapes the other tools expect. Every "riddle://reference/..." URI mentioned in another tool's description, in a tool response or in an error message is a topic of this tool - pass it here to read that document. These documents are the authoritative parameter reference for the riddle_builder_* and palette_* tools: read the relevant one BEFORE the first call instead of guessing property names, and re-read it when a call fails with a VALIDATION_ERROR. Available topics:

riddle://reference/index: every document this server has, including the two families below, with exact sizes in bytes. Read this one first when you do not know which of the others you need - it is by far the smallest.
riddle://reference/getting-started: what this server is for, the authentication model, the guided prompts it offers, and the addresses of the concept documents (tools by category, workflows, bulk, move restrictions, editing, publish) that hold the rules themselves. Start here when unsure which tool to use.
riddle://reference/response-format: the {uuid, type, modifiedAt, build, nextBlockId, warnings, published, context} envelope every tool returning a Riddle answers with, plus the bulk envelope.
riddle://reference/riddle-builder/riddle-types: all 9 Riddle types with their required/optional build fields and result structure.
riddle://reference/riddle-builder/block-types: every question and content block type per Riddle type - the reference for the "blocks" of a riddle_builder_* call.
riddle://reference/concepts/defaults: how the per-entity defaults documents below work - what a read-back leaves out for still being at its default, and how to read a property name. Read this once; the documents themselves each state their own defaults completely.
riddle://reference/block-defaults/{blockType} (a family, one address per block type, e.g. riddle://reference/block-defaults/SingleChoice): the default of every property a riddle_get read-back omits from a block of that type for still being at it. Read the one block type you are configuring; see riddle://reference/index for the exact member names.
riddle://reference/form-field-defaults: what every form field type of the FormBuilder block accepts and defaults to, keyed by field type - one document, since a Form is built with several field types at once; pass "fieldTypes" to get only the ones you need.
riddle://reference/publish-defaults: the resolved default of every publish setting ("publish.") a read-back leaves out - one address, since they are the same for every Riddle type that has them.
riddle://reference/riddle-defaults/{riddleType} (a family, one address per Riddle type, e.g. riddle://reference/riddle-defaults/Quiz): the Riddle-level, preset and publish defaults of a Riddle of that type.
riddle://reference/riddle-builder/form-field-types: all 18 form field types of the FormBuilder block.
riddle://reference/riddle-builder/result-blocks: all 12 result page block types with their format and styling options.
riddle://reference/palette/fields: every palette value palette_customize accepts, and where it is used in a published Riddle.
riddle://reference/palette/built-in-palettes: the built-in palettes usable as a starting point for a custom one.
riddle://reference/palette/fonts: the font families available as the palette font.
riddle://reference/question-bank/overview: what a question bank is, its draft/publish model, and how its items relate to a QuestionBank block - read before the first questionBank_create.

Request only the documents you actually need - most are long. Up to 8 at a time, which is the size of the full Riddle Builder set (riddle-types + block-types + form-field-types + result-blocks) plus a handful of the entity addresses above.

"riddleType" and "blockTypes" narrow riddle-types and block-types down to one Riddle type's (or one block type's) own material - e.g. {"topics": ["riddle://reference/riddle-builder/block-types"], "riddleType": ["Quiz"]} drops every other type's question blocks. "fieldTypes" does the same for form-field-types, e.g. {"topics": ["riddle://reference/riddle-builder/form-field-types"], "fieldTypes": ["Dropdown"]} returns that one field type plus the property sets it refers to. All three are ignored (whole document returned) on a topic without that split, which every response says explicitly rather than silently returning everything. The block-defaults and riddle-defaults documents have nothing left to filter this way - they are already one address per entity, so reading riddle://reference/block-defaults/SingleChoice IS the filtered result, with no parameter needed. "fieldTypes" narrows form-field-defaults the same way it narrows form-field-types, so {"topics": ["riddle://reference/riddle-builder/form-field-types", "riddle://reference/form-field-defaults"], "fieldTypes": ["Dropdown"]} is the complete reference for one field type - what it is for, what it accepts, what it defaults to - and nothing else.

Input Schema

TableJSON Schema

Name	Required	Description
`topics`	Yes	The reference documents to read, as their "riddle://reference/..." URIs.
`blockTypes`	No	Narrow block-types further, to these block type name(s) (e.g. "SingleChoice", "WheelSpinner"), on top of whatever "riddleType" already kept. Names are NOT enumerated here - there are dozens across 9 Riddle types, and this schema is read by every agent on every turn regardless of whether it filters. An unknown name, or one that exists but is not part of the Riddle type(s) you filtered to, is rejected and the error names the valid names for your situation. Omit for every block type.
`fieldTypes`	No	Narrow form-field-types down to these form field type name(s) (e.g. "Dropdown", "Privacy"). The property sets a kept field type refers to (propertySets/commonProperties) and the "fields" usage notes are always returned with it. Names are NOT enumerated here for the same reason "blockTypes" does not enumerate its own - an unknown one is rejected with the full list of the 18 valid names. Ignored on every other topic. Omit for every field type.
`riddleType`	No	Narrow riddle-types/block-types down to these Riddle type(s) - e.g. ["Quiz"] on block-types drops every other type's question blocks while keeping the shared conventions (commonBlockProperties, the general Content/Ad/Quote blocks, ...). Ignored, with the whole document returned, on a topic that has no per-type split (form-field-types, result-blocks, concepts/defaults, the palette/question-bank documents). Not applicable to the block-defaults/riddle-defaults families - read the entity's own address instead. Omit for every type.
`includeAvailableTopics`	No	Whether the response should carry the full "availableTopics" catalogue. Omit it: the first reference_get of a session gets the catalogue, every call after it gets a one-line pointer back to it instead of repeating ~2.5 KB you already have - which on a small document is several times the document itself. Pass true to get it again (a fresh conversation on an existing session, or after losing it), false to never pay for it.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`references`	Yes	One entry per requested topic, in the order requested.
`availableTopics`	Yes	Every topic this tool can return - sent in full on the FIRST reference_get of a session only, so a client that reached this tool without reading its schema still learns what else is documented and what reading it would cost. Later calls carry a short {omitted, namesAndSizesIn, resend} pointer instead of repeating ~2.5 KB the caller already has; "includeAvailableTopics" overrides both directions. In the full form the static documents are listed as uri => {sizeBytes, summary}, same as riddle://reference/index and what resources/list advertises as "size". The two generated families (block-defaults, riddle-defaults - one address per entity) are compacted under "families": the address template, how many addresses it has and what they cost in total, without the individual names - those, with their exact sizes, are in riddle://reference/index. An address is built by replacing the {variable} of a "uriTemplate" with the entity you are working on, e.g. riddle://reference/block-defaults/Flashcard.

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the readOnlyHint=true annotation, the description discloses substantive behaviors: the 'Up to 8 at a time' request limit, the fact that filter parameters are 'ignored (whole document returned) on a topic without that split, which every response says explicitly rather than silently returning everything,' and the includeAvailableTopics behavior of the first call carrying the catalogue while later calls get a one-line pointer. It also discloses the error behavior for unknown filter names — rejection with valid names listed. No annotation contradiction.

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?

The description is long (roughly 600+ words), but almost every sentence earns its place: the topic enumeration is functional because those exact URIs are the parameter values, and the filtering rules are correctness-critical. It is front-loaded with the clearest statement of purpose in the first sentence, followed by routing advice and then the topic directory. A tighter restatement of the filter semantics is possible, but nothing here is cheap filler.

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 tool with 5 parameters, 13 enumerated topic URIs plus two families, an existing output schema, and maxItems/minItems constraints, the description covers every angle: what the documents are, which to read first, how to narrow them, the size limit, and failure recovery via VALIDATION_ERROR. An agent reading only this description can decide, with the right document(s), construct a valid request, and interpret the response without ever opening the schema.

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% and each parameter's schema description is already thorough, so the baseline is 3. The description earns a bump by adding concrete working examples of the interplay between filters (e.g. {"topics": ["riddle://reference/riddle-builder/block-types"], "riddleType": ["Quiz"]} drops every other type's question blocks), and by explaining that block-defaults/riddle-defaults families are already one-address-per-entity so no filter parameter applies. This is genuinely additive to the schema rather than duplicative.

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 opening sentence states a specific verb and resource: 'Read the documentation of this MCP server: the block types, form field types, result blocks, palette values and response shapes the other tools expect.' It then defines scope precisely by stating that every 'riddle://reference/...' URI encountered in other tools, responses, or errors is a topic of this tool. This clearly differentiates it from the dozens of operational siblings (palette_*, riddle_builder_*, questionBank_*, stats_*): it is the server's meta-reference tool.

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 explicit when-to-use instructions: read the relevant document 'BEFORE the first call instead of guessing property names, and re-read it when a call fails with a VALIDATION_ERROR.' It also routes to alternatives by condition — read index 'when you do not know which of the others you need' and getting-started 'when unsure which tool to use.' This is the explicit grammar of when/when-not that the dimension asks for.

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?