QuestionPunk

Question Update Text

question_update_text

Destructive

Rewrite a question's wording, and its answer options, matrix rows/columns or scale labels, in one language; also how you write a translation. Send the question's current answer_type and the full itemDetails for that language (all answer_options, not only the changed one), both from survey_get. langCode must be one of the survey's languages, and auto-translate must be off for it unless it is the primary language. A missing language is rejected, so add it first (survey_lang_create where this connection has it, otherwise the user adds it in the editor at editorUrl from survey_get). Needs surveyVersion = versions.current; the result returns the next one. On a published survey the new text is live at once.

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": {
      "surveyItemId": "<surveyItemId>",
      "surveyVersion": "<surveyVersion>",
      "langCode": "<langCode>",
      "text": "<text>",
      "answer_type": "<answer_type>"
    },
    "name": "question_update_text"
  }
}

Input Schema

Name	Required	Description
`text`	Yes	The full new question text
`langCode`	Yes	One of the survey's languages (survey_get lists them), e.g. "en"
`answer_type`	Yes	The question's current answer_type from survey_get; any other value is rejected as not found (change the type with question_update)
`itemDetails`	No	Localized details for this language (answer_options, rows/columns, labels, ...). Required for types that have them; send the full object, not a partial one.
`surveyItemId`	Yes	Question ID (survey_items[].id from survey_get)
`surveyVersion`	Yes	Current survey version: versions.current from survey_get, or the surveyVersion your last edit returned. A stale version is rejected (WRONG_VERSION). The result returns the next one as surveyVersion.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 7, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already flag destructiveHint=true, idempotentHint=false and openWorldHint=true, but the description adds material consequences: on a published survey the new text goes live immediately, a stale version is rejected with WRONG_VERSION, and an unknown language is rejected outright. It stops short of saying the supplied text wholesale replaces the existing localized content, which is the main thing a destructive edit should spell out.

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?

Dense but front-loaded: the operation and scope come first, then preconditions, then version chaining, then the publication effect. Semicolon-chained sentences make it slightly harder to scan, and the 'send answer_type and full itemDetails ... both from survey_get' clause repeats the schema, but nothing is 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 destructive, versioned, multi-language edit with six parameters and nested itemDetails, the definition covers prerequisites, failure modes (WRONG_VERSION, missing language), the recovery path when survey_lang_create is unavailable, and the immediate live effect. Since an output schema exists, no return-value explanation is needed, and none is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents itemDetails as needing the full object (not a partial) and answer_type as the current value from survey_get. The description largely restates those points; its only genuine addition is the per-language auto-translate constraint on langCode. Emphasis on the full-object requirement is useful but duplicative.

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 opens with a specific verb+resource: rewriting a question's wording plus its answer options, matrix rows/columns or scale labels, scoped to one language, with the translation-authoring case called out explicitly. It does not name question_update as the sibling for changing answer type (that routing only appears in the schema's answer_type description), so sibling differentiation is incomplete from the description alone.

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?

Gives explicit preconditions and alternatives: langCode must already exist in the survey, auto-translate must be off unless it is the primary language, and a missing language must be added first via survey_lang_create or in the editor at editorUrl. It also states the version contract — pass versions.current and chain the returned next version — which is exactly the when/when-not guidance an agent needs before calling a destructive edit.

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

All QuestionPunk tools Inspect

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

Need Help?