Skip to main content
Glama
Sign In

SurveyNinja

by io.surveyninja
OverviewDiscussionsAdmin

Quiz questions and structure

update_quiz_widgets
Destructive

Saves quiz widget structure (ids + entities). Before calling, read the current structure via the quiz://{id}/structure resource. The plan limits the number of questions and the question types: a save that adds questions over the limit or a question of an unavailable type is rejected. ids — ordered array of widget identifiers; entities — object of configs keyed by those ids. IMPORTANT: widget identifiers are unique RFC 4122 UUIDs (e.g. 550e8400-e29b-41d4-a716-446655440000). Only the service strings "welcome" (first) and "submit" (last) are allowed; every other id must be a unique UUID. When adding new widgets, generate a new UUID for each one; duplicate ids are not allowed. The thank you screen ("thanks", "thank you page") is a SEPARATE widget with type = "finish" and a new UUID placed before "submit"; editing the submit fields does not create it. The special options "Other / Custom answer", "Hard to answer" and "None of the above" are switched on with the choiceTextOther / dropdownOther / hardToAnswer / noneOfAbove flags instead of being added as items to the option list. The tool response carries what was actually saved (saved: the widget count and the breakdown by type) — check it before telling the user the change has been applied.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "quiz_id": "<quiz_id>",
      "ids": "<ids>",
      "entities": "<entities>"
    },
    "name": "update_quiz_widgets"
  }
}

Input Schema

NameRequiredDescriptionDefault
idsYesWidget order: "welcome", then unique widget UUIDs, then "submit". Each id is a unique UUID (except welcome / submit).
quiz_idYesQuiz ID to update.
entitiesYesWidget configs: key — UUID from ids (unique per widget). Option ids inside a widget (choiceTextIds, dropdownIds, matrixRowIds and the other option lists) must be freshly generated UUIDs as well; sequential names such as "q2_1" are not accepted — a quiz built with them saves fine but fails to publish.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the destructiveHint and non-idempotent annotations, the description discloses that saves can be rejected by plan limits, that widget ids and option ids must be unique RFC 4122 UUIDs, that welcome and submit are fixed endpoints, and that the finish screen is a separate widget. It also says to inspect the saved response before confirming success.

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 front-loaded with the save operation and the prerequisite read step, then organized around id rules, special widgets, and response verification. It is dense and largely earns its length, but some UUID and special-option guidance overlaps with the schema descriptions.

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?

Given the very large nested schema, destructive mutation semantics, and absence of an output schema, the description supplies the critical behavioral context an agent needs: prerequisite read, validation limits, UUID generation rules, special flag behavior, finish-screen handling, and what the response reports.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is already 100%, the description adds important meaning: ids are ordered with welcome first and submit last, entities are keyed by those ids, new widgets require new UUIDs, and special options such as Other and Hard to answer must be enabled by flags rather than inserted as ordinary option items.

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: "Saves quiz widget structure (ids + entities)." It distinguishes the operation from reading the structure by naming the quiz://{id}/structure resource and explains that the payload is an ordered ids array plus an entities config map.

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 gives a clear prerequisite: read the current structure via the quiz://{id}/structure resource before calling. It also explains that plan limits govern question count and question types and that invalid saves are rejected, but it does not explicitly route the agent to sibling tools such as update_quiz_logic or update_quiz_settings.

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

All SurveyNinja toolsInspect
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.

Resources