Skip to main content
Glama

RooQuiz

by com.rooquiz

add_question

Append an item to the end of a form. type is a question type, Breaker (page break — only formId + type are needed, other fields are ignored) or a display block (Statement / Swiper). Question types: SingleCheck / MultiCheck / TrueFalse; FillBlank (free text — scored in quiz via correctAnswer, an unscored data-collection field in scored_quiz); DropDown (single or multiple via multiple — prefer it over SingleCheck/MultiCheck past 20 choices); Cascade (hierarchical via choices[i].children, scored_quiz only); Ordering (quiz only, order-sensitive grading); DateField / TimeField (unscored data-collection fields, scored_quiz only, no correctAnswer/score); NumberField (quiz: optional numeric correctAnswer + score; scored_quiz: the submitted number feeds report formulas); Rate (scored_quiz only, the submitted 1..steps rating is the question score unless per-star scores are set in the web app). Display blocks carry no answer: { type: "Statement", content } renders a rich-text passage (intro, section lead-in, disclaimer) and { type: "Swiper", items } an image carousel; both work in every scene. Configure random_knowledge_quiz question banks in the web app. Not idempotent: if the call times out it may still have succeeded, so retrying blindly can create a duplicate — check first, then retry only if it is really missing.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
maxNoNumberField only: maximum allowed input value (must be >= min). Rejected for other question types.
minNoNumberField only: minimum allowed input value (respondents cannot submit a smaller number). Rejected for other question types.
codeNoOptional stable identifier for this question (field code). Omit it to let the server auto-generate one. Set a meaningful code (e.g. "q1") when report.formula or a dimension needs to reference this question, so you can write the formula as `{{q1}}` in the same call instead of round-tripping via get_form. Rules: start with a letter or underscore, then only letters/digits/underscores (no hyphens, spaces, or leading digit), at most 64 chars, and not a reserved math word (e, E, pi, PI, tau, phi, i, Infinity, NaN, true, false, null, undefined). Must be unique among all items in the form.
nameNoQuestion stem text. Allows plain text or restricted HTML (tag allowlist: <p> <strong>/<b> <em>/<i> <u> <s> <mark> <span> <sup> <sub> <br>; other tags are stripped and the text kept).
typeYesQuestion type; Breaker means a page break, no name/choices etc. needed; Statement / Swiper are display-only blocks that collect no answer
unitNoNumberField only: display unit suffix shown after the input, e.g. "kg" / "$" / "min". Rejected for other question types.
itemsNoSwiper only, and required there: the carousel slides in display order, 1-10 of them. Upload the images with prepare_image_upload / finalize_image_upload first and pass the returned media IDs. Rejected for every other type.
scoreNoPoints this question is worth, default 0 (not scored). Quiz scene: awarded when the answer matches correctAnswer, and a positive value is required once correctAnswer is set. Scored Quiz scene: pairing it with correctAnswer enables the fallback mode above, but choices[i].score is more flexible. Rejected in the outcome_quiz scene, for DateField / TimeField / Rate, and — in the scored_quiz scene — for NumberField (where the submitted number itself is the score) and FillBlank (collected only, never scored).
stepsNoRate only: number of rating steps, i.e. the highest rating (3-10, default 5). In the scored_quiz scene the submitted rating value (1..steps) is the question score, unless a per-star score is configured in the web app. Rejected for other question types.
wordsNoRate only: optional scale labels evenly distributed under the rating control, e.g. ["Poor", "Excellent"] for the two endpoints (up to 5 labels). Rejected for other question types.
formIdYesThe form ID to append the item to
aiMatchNoOnly for FillBlank in the knowledge_quiz scene. Enables AI grading: the AI compares the respondent answer against correctAnswer and scores by accuracy, instead of requiring an exact string match. Requires correctAnswer (the standard answer) and score > 0 (the score earned when accuracy reaches the threshold). Pass an empty object {} to enable with default settings; omit for plain exact-match grading.
choicesNoChoice-based questions only (SingleCheck / MultiCheck / DropDown / Ordering / Cascade), where it is required; ignored for every other type, including TrueFalse — its two options come from trueLabel / falseLabel. Per-type limits: SingleCheck / MultiCheck 2-20 items — for a longer list use DropDown (2-100 items) instead; Ordering 2-10 items; Cascade nests via choices[i].children (up to 3 levels, at most 100 nodes in total). IMPORTANT (knowledge_quiz scene): vary the position of the correct option(s) across questions — do NOT always place the correct answer first. Distribute correct answers roughly evenly over all positions so they are not predictable.
contentNoStatement only, and required there: the text respondents read — an intro, a section lead-in, instructions, a disclaimer. The block renders this and nothing else. Same rich-text rules as `description` (headings / lists / links / <img src> / math formulas). This field also accepts an inline image: put an <img src="..."> in it, where src is a direct image URL that renders in <img src> (a page URL that merely contains an image does not work). Use finalize_image_upload to host an image yourself, or a direct URL the user supplied. Never invent an image URL — omit the image instead of risking a broken one.
explainNoOptional answer explanation. The frontend renders it in the question's "answer explanation" field (DescriptionEditor); the rich-text rules are identical to description. Do not stuff the answer explanation into description — that is the question's supplementary note and will not be shown as an explanation to respondents/graders.
shuffleNoOrdering only: shuffle the displayed choice order for each respondent. Defaults to true for MCP-created questions — the stored choices order would otherwise leak the correct order when correctAnswer matches it. Pass false only when the initial order is intentionally meaningful. Rejected for other question types.
multipleNoDropDown only: allow selecting multiple options (default false = single select). Affects the quiz-scene correctAnswer shape: an array of labels/codes when true, a single one when false. Rejected for other question types (SingleCheck/MultiCheck are inherently single/multi).
requiredNoWhether the question is required, default false
precisionNoDateField / TimeField only: picker precision. DateField accepts year | month | day | hour | minute | second (default day; e.g. "month" shows a year-month picker, "second" a full datetime picker). TimeField accepts only minute | second (default minute). Ignored for other question types.
trueLabelNoTrueFalse only: custom display text for the "true" option (e.g. "Yes" / "Agree"). Ignored for other question types. Leave empty to fall back to the built-in default for the form language ("Correct" in English forms). Does not change the stored answer value, which stays "true".
falseLabelNoTrueFalse only: custom display text for the "false" option (e.g. "No" / "Disagree"). Ignored for other question types. Leave empty to fall back to the built-in default for the form language ("Incorrect" in English forms). Does not change the stored answer value, which stays "false".
descriptionNoOptional supplementary note for the question. Allows a wider HTML subset: everything the stem allows + <h1>-<h6> <ul> <ol> <li> <blockquote> <a href> <img src> <hr> <art-field> (variable placeholder, data-type / data-cid); unsafe protocols (javascript:/data:) and unknown attributes are stripped. This field also accepts an inline image: put an <img src="..."> in it, where src is a direct image URL that renders in <img src> (a page URL that merely contains an image does not work). Use finalize_image_upload to host an image yourself, or a direct URL the user supplied. Never invent an image URL — omit the image instead of risking a broken one.
trueOutcomesNoOutcome scene + TrueFalse only (required there together with falseOutcomes): the outcome codes that answering "true" votes for. Use [] for a side that votes for nothing. Rejected for other question types / scenes.
correctAnswerNoThe "correct answer" of the knowledge_quiz scene; setting it makes the question scored, so pair it with a positive `score`. The shape follows the question type — see the anyOf branches; a choice is referenced by its label or its code, so reference it by code whenever the same label appears more than once (Ordering rejects an ambiguous label outright). Required on SingleCheck / MultiCheck / DropDown / Ordering in the knowledge_quiz scene, optional on FillBlank / NumberField there. NumberField answers must be typeable within min / max and decimalPlaces. Rejected for DateField / TimeField / Rate (data-collection and rating fields; configure date/time scoring in the web app), rejected for FillBlank in the scored_quiz scene (free text is collected only there), and rejected in the outcome_quiz scene (no right or wrong answers there). In the scored_quiz scene prefer choices[i].score per option; passing correctAnswer + score there only falls back to "the matching choice gets score, others get 0".
decimalPlacesNoNumberField only: how many decimal places respondents may enter (stored as the field's numeric precision), default 0 = integers only. Rejected for other question types. Note this is different from the string `precision` of DateField / TimeField.
falseOutcomesNoOutcome scene + TrueFalse only (required there together with trueOutcomes): the outcome codes that answering "false" votes for. Use [] for a side that votes for nothing. Rejected for other question types / scenes.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
fieldNoThe created question, including its generated code
formIdNoThe form that was edited
itemCountNoQuestion / page-break count after the append

TDQS

A3.9/5.0
Behavior4/5

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

Annotations declare readOnlyHint=false, so mutation is implied. The description goes beyond by explicitly warning 'Not idempotent: if the call times out it may still have succeeded, so retrying blindly can create a duplicate — check first, then retry only if it is really missing.' This is a critical behavioral disclosure. It also clarifies that some fields are 'Rejected' or 'Ignored' depending on type/scene, which helps manage expectations. No auth or rate-limit details, but annotations already cover part of the behavioral profile.

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 very long and dense, covering all question types and scene rules. For a tool with 26 parameters and 14 enum values, some length is necessary. However, much of the content repeats what is already in the schema's field applicability description and property descriptions. It could be shortened by focusing only on high-level guidance and pointing to the schema for details. The structure is reasonable, but the size pushes it beyond 'concise' into 'thorough but verbose'.

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?

Given the tool's high complexity, the description is largely complete: it covers the main purpose, type-specific extensions, scene restrictions, and the non-idempotency caveat. An output schema exists, so return values are not required. The main gap is the lack of explicit differentiation from insert_question regarding positional use, which could leave an agent uncertain about tool selection. For a mutation tool of this scale, this is a minor omission.

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 description coverage is 100%, so the schema already documents every parameter thoroughly. The description adds value beyond the schema by providing practical guidance like 'DropDown — prefer it over SingleCheck/MultiCheck past 20 choices' and clarifying that Cascade is 'scored_quiz only', which duplicates some schema text but also gives heuristics not present in the schema. Since schema coverage is high, the baseline is 3, and the description's extra context justifies a 4.

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?

The description clearly states 'Append an item to the end of a form', identifying a specific verb and resource. It also details the item types. However, it does not explicitly distinguish this from the sibling tool insert_question, which likely inserts at a custom position. The word 'append' implies end-of-form, but an explicit comparison would be clearer.

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?

The description provides clear context about when to use this tool: to add a question or display block to a form, with extensive guidance on per-scene and per-type applicability. It mentions 'Configure random_knowledge_quiz question banks in the web app', implying a limitation, but it never explicitly states when to use an alternative tool like insert_question or update_question. Exclusions are implied through rejection statements in the schema, not stated in the description.

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

All RooQuiz toolsInspect
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
Disambiguation4/5

Most tools pair a distinct resource with a distinct verb, and the descriptions do a good job of separating related concepts like leads, records, examinees, and bookings. The only real ambiguity is between list_records (submission records, also called leads) and list_leads (CRM leads), plus a mild overlap between update_form and update_form_settings, but careful reading resolves both.

Naming Consistency5/5

All tool names follow a consistent verb_noun snake_case pattern, using standard verbs like get_, list_, create_, update_, delete_, add_, insert_, move_, and set_. Minor stylistic variation such as add_question vs. insert_question is still predictable and does not hurt usability.

Tool Count2/5

48 tools is a very heavy surface for an MCP server. While each tool appears purposeful, the server spans forms, questions, translations, analytics, leads, bookings, examinees, media, and team administration, making it feel like a full platform API rather than a focused server. Most agents will only ever need a subset of these tools.

Completeness4/5

The core quiz lifecycle is well covered: form creation/editing/deletion/restore/duplicate/translation, question CRUD/move, delivery settings, statistics/funnels, lead CRM, bookings, examinees, media upload, and tenant basics. The main gaps are minor — no member list/remove/role management beyond invite, no media library listing/deletion, and no bulk export of records — but these do not create dead ends in the primary quiz/lead/booking workflows.

Resources