Skip to main content
Glama
Sign In

QUESTIONSTAR

by com.questionstar.mcp
OverviewDiscussionsAdmin

Add Question

add_question

Adds a question to a survey and returns its variable code (Q1, Q2, …). title is the question text. type is a structural key of the form family.modifier[.variant]. Supported (creatable) keys: instruction.default; single-choice.default, single-choice.column-left-label, single-choice.row, single-choice.rows, single-choice.columns, single-choice.row.button (a 0–10 NPS scale); multi-choice.default, multi-choice.column-left-label, multi-choice.row, multi-choice.rows, multi-choice.columns; text-input.single-line, text-input.single-line.number, text-input.single-line.email, text-input.multiline, text-input.form, text-input.form.constant-sum; matrix.simple, matrix.simple.checkbox, matrix.simple.bulky-text, matrix.side-by-side, matrix.bipolar; dropdown.default; sliders.sliders, sliders.ratings, sliders.emotions, sliders.gradient-sliders, sliders.balks, sliders.sliders.constant-sum, sliders.ratings.constant-sum; sorting.rank-order, sorting.rank-assignment; code.default. requireType is none | soft | strict (default: leave the type's own setting). Fields apply by presence: options[] (label, optional code, hasCustomField for an 'other' field, isExclusive for checkbox) fill choice options / matrix or scale columns; rows[] fill matrix statements; scale{min,max} sets numeric/slider bounds; customID sets an author id. Anything omitted keeps the type's own default (e.g. an nps/single-choice.row.button question keeps its 0–10 scale and anchor labels). For choice, dropdown, sorting and matrix types always pass your own options[] (and rows[] for matrices) — omitting them leaves the seed's generic placeholder options. page places the question on a specific page (1-based, the numbering add_survey_page and get_survey report); omitted, the question is appended to the LAST page. add_question never creates pages — create them with add_survey_page first, a non-existent number is an error. Show/skip logic fires on the move between pages: a branching source question takes effect only on questions placed on a later, separate page; a condition and its targets on the same page cannot work. These types must be set up in the QUESTIONSTAR UI and return an error here: autocomplete.single-answer, autocomplete.multiple-answers, heatmap.default, file-upload.default, signature.default. Verified by readback: the survey is re-read through get_survey and the reply reports the question as actually stored, including the page it landed on. Requires the edit-survey right on this survey.

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": {
      "code": "<code>",
      "type": "<type>",
      "title": "<title>"
    },
    "name": "add_question"
  }
}

Input Schema

NameRequiredDescriptionDefault
codeYesSurvey publication code — the 8-character code from the survey's public link (e.g. 1a2b3c4d). Returned by list_surveys.
pageNo1-based page number to place the question on. Omit → appended to the LAST page. A page number that does not exist is an error — create the page with add_survey_page first.
rowsNoMatrix row statements. Applied when the type has a statement list; otherwise ignored.
typeYesQuestion type — a structural key such as single-choice.default, text-input.single-line.number or single-choice.row.button (see the tool description for the full supported set).
scaleNoNumeric/slider bounds {min,max}. Applied when the type carries a range; otherwise ignored.
titleYesQuestion text.
optionsNoAnswer options (choice types) or scale/matrix columns. Applied when the type has an option list; otherwise ignored.
customIDNoOptional author-defined custom id for the question.
requireTypeNoAnswer requirement. Omit to keep the type's default.

Output Schema

NameRequiredDescriptionDefault
messageNoWhat the call did, verified, refused or previewed — the complete human-readable outcome.
previewNotrue when the call was a preview (confirm not passed): nothing was changed.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Beyond the annotations (readOnly false, openWorld true, idempotent false, destructive false), the description discloses that omitted fields keep type defaults, choice/dropdown/sorting/matrix types require explicit options/rows to avoid placeholder seeds, unsupported types return errors, and the reply is verified by re-reading through get_survey. This adds substantial behavioral context not present in structured fields.

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 purpose and is dense with necessary detail, but it reads as one long paragraph, making the extensive type list and conditional rules harder to scan than a bulleted structure would be. Every sentence is substantive, though the formatting could be improved.

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 a 9-parameter mutation tool with nested objects and many structural type variants, the description covers placement rules, default behavior, required explicit inputs, unsupported types, branching-logic constraints, permission requirements, and readback verification. With an output schema present, return-value details are appropriately left to the schema.

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?

Schema coverage is 100%, but the description adds meaningful semantics: it enumerates supported type keys, explains that fields apply by presence and otherwise keep type defaults, clarifies when options[] and rows[] must be supplied, and explains the page parameter's 1-based numbering and append-to-last-page default. This goes well beyond the schema's field-level descriptions.

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: 'Adds a question to a survey and returns its variable code (Q1, Q2, …).' It distinguishes the tool from add_survey_page by noting add_question never creates pages, and from update_question by its creation-only scope.

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?

It gives explicit prerequisites: create pages with add_survey_page first, a non-existent page number is an error, and the edit-survey right is required. It also names unsupported types that must be set up in the QUESTIONSTAR UI and describes the branching-logic constraint that sources and targets must be on separate later pages.

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

All QUESTIONSTAR 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