LimeSurvey MCP Server

Change a question to a described end state

limesurvey_update_question_from_spec

Destructive

Change one existing question to the end state given as a question spec (typically the spec of limesurvey_get_survey_spec at level question, changed).

Instructions

Change one existing question to the end state given as a question spec (typically the spec of limesurvey_get_survey_spec at level question, changed). The tool compares the end state with the question and picks the mode: none (nothing differs, nothing is written); texts (only question, help and subquestion texts: written in place with set_question_properties questionl10ns, also at an active survey); columns (code, mandatory, relevance, preg, other, same_default, same_script, encrypted, question_theme_name, modulename, inactive survey only: written in place, the question ID stays); replace (anything else: subquestions, answers and answer texts, attributes, defaults, type, script; inactive survey only): the end state is imported as a new question, moved to the place of the old one and read back completely; only if it matches is the old question deleted, otherwise the new one is deleted again and the old one keeps everything. Texts the end state does not change are written back as LimeSurvey stores them. dry_run true only reads (write scope none) and returns { survey_id, question_id, survey_active, mode (none, texts, columns, replace, or rejected when an active survey would need more than texts), changes [{ path, kind (text, column, structure), current, desired, and for a subquestion or answer its code and, on scale 1, scale_id }], changes_total, risks [{ code, blocking, acknowledgeable, detail, locations }], plan, fingerprint }. The real run needs expected_fingerprint (of get_survey_spec or the dry run; STALE_SPEC if the question changed since) and confirm_destructive_action true, and returns the same plus applied, verification { ok, differences } and, after a replacement, the new question_id and old_question_id. Blocking risks stop the call with UPDATE_QUESTION_BLOCKED before anything is written: qid_bound_links (every replacement: URL parameters, archived responses, quota memberships of the old ID), quota_members, other_default, removals, translation_gaps (import_question fills missing translations of the survey) and unreadable_texts (texts of the question that cannot be read in a language get the base-language text; both acknowledged with fill_translation_gaps) and answer_code_references can be acknowledged; code_references (the old code or removed fields such as CODE_SQ, CODE_SQcomment, CODE_other named anywhere, the end state of the question included; free texts are searched inside {...} only), sgqa_references and data_uri cannot. Each risk lists at most a part of its locations (locations_total). Errors: SPEC_INVALID, STALE_SPEC, SURVEY_ACTIVE (with the changes that need an inactive survey), UPDATE_QUESTION_BLOCKED, QUESTION_SURVEY_MISMATCH, REPLACE_QUESTION_FAILED (failed_step, rolled_back, manual_cleanup, differences), UPDATE_QUESTION_FAILED (texts and columns; the old values are written back and read back, manual_cleanup names what is not back), VERIFY_READ_FAILED (written: true; only the read-back failed). Texts of the survey, groups and questions alone go with limesurvey_update_survey_texts; a new question with limesurvey_add_question_from_spec. Needs the write scope content (dry run: none).

Input Schema

Name	Required	Description
`dry_run`	No	true: only show mode, changes, risks and plan; nothing is written (default false).
`question`	Yes	The end state of the question as a question spec, for example the spec of limesurvey_get_survey_spec at level question, changed.
`survey_id`	Yes	Numeric LimeSurvey survey ID.
`acknowledge`	No	Confirmed risks of the dry run: qid_bound_links, quota_members, other_default, removals, fill_translation_gaps (for the risks translation_gaps and unreadable_texts) and answer_code_references.
`question_id`	Yes	ID of the main question of this survey to change.
`expected_fingerprint`	No	The fingerprint of the question as read (limesurvey_get_survey_spec or a dry run); required unless dry_run is true.
`confirm_destructive_action`	No	Must be true for a real run (dry_run not true): a replacement deletes the old question.

Output Schema

Name	Required	Description	Default
`result`	Yes
`workflow`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.6.0Oct 14, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already flag destructiveHint=true, and the description goes far beyond them: it discloses the transactional replace semantics (import new, move, read back, delete old only on match), which risks block vs. can be acknowledged, the dry-run write scope of none, and the full error taxonomy. It also states the write-scope requirement and fingerprint/confirmation preconditions.

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 core purpose is front-loaded, but the rest is a single dense paragraph packing modes, risk codes, and every error string into one block. The content is largely necessary for a tool this complex, yet the wall-of-text structure makes selective reading hard and could be broken into scannable sections.

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, transactional, multi-mode tool with nested spec objects, the description covers preconditions, modes, risks, error handling, and recovery behavior. An output schema exists, so the return-value narrative is redundant but ensures nothing an agent needs is missing.

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%, so the baseline is 3, but the description adds real meaning for expected_fingerprint (source and STALE_SPEC behavior), confirm_destructive_action, and acknowledge (which risk codes map to which risks, e.g. fill_translation_gaps). The question spec itself is not re-explained, which is correct since the schema fully documents it.

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?

States a specific verb and resource ('Change one existing question to the end state given as a question spec') and immediately frames the spec as the get_survey_spec question-level object. It is clearly distinguishable from add_question_from_spec (new question) and update_survey_texts (texts only), which it names.

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 routing rules: 'Texts of the survey, groups and questions alone go with limesurvey_update_survey_texts; a new question with limesurvey_add_question_from_spec.' It also explains when each internal mode (none/texts/columns/replace) is chosen based on what differs, so the agent knows when the tool is the right call.

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

Deploy Server