LimeSurvey MCP Server

Create a survey from a description

limesurvey_create_survey_from_spec

Instructions

Create a new survey from a survey description (spec { survey, groups }). The spec is checked first: an invalid spec answers SPEC_INVALID with errors [{ path, message, fix }] and sends nothing to LimeSurvey. A valid spec becomes a LimeSurvey structure file (.lss) that import_survey imports; the new survey stays inactive and is not activated. The tool then reads the survey back (read methods only) and compares it with the spec. Returns { survey_id, title, languages, groups, questions, active, verification { ok, differences [{ path, expected, actual, and for a subquestion or answer its code and, on scale 1, scale_id }], differences_total, truncated }, truncated }, plus warnings, missing_translations and unreadable (each with a _total) when there are any. A list shows at most 200 entries and is cut further to stay within LIMESURVEY_MAX_RESPONSE_CHARS; the _total fields hold the full numbers and truncated says whether a list was cut. A difference is a finding of the comparison, not an error of the call. If LimeSurvey answers the import with an error, the tool answers CREATE_SURVEY_FAILED with LimeSurvey's message and details.created false (nothing was created). If the import call itself fails (transport or JSON-RPC error, or no survey ID in the answer), details.created is "unknown" with manual_cleanup, the title and a recovery that names limesurvey_find_surveys: look for the survey before calling again. If only the read-back fails, CREATE_SURVEY_FAILED names the created survey_id. The tool takes no file path, adds nothing to existing surveys, activates nothing and deletes nothing. A spec can be checked beforehand with limesurvey_validate_spec; limesurvey_get_survey_spec returns the spec of an existing survey in this format. A text is one string (for every language) or a map per language. A spec with a Ranking question makes the tool read the generation of the instance once (get_group_properties for group 0): on LimeSurvey 7 the entries are written as subquestions of type R (code up to 20 characters, with relevance), on LimeSurvey 6 as answers (code up to 5 characters, no relevance). The second scale of the types 1 (answers) and : and ; (subquestions, the columns) is given with scale_id 1. Needs the write scope content.

Input Schema

Name	Required	Description	Default
`spec`	Yes	The survey description. Its fields depend on kind; unknown fields are reported by the check, not rejected.

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.5/5.0

Behavior5/5

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

Far beyond what the annotations declare, the description discloses the full behavioral contract: the spec is validated before anything is sent, the created survey 'stays inactive and is not activated,' the tool reads the survey back with read methods only, and it details error codes (SPEC_INVALID, CREATE_SURVEY_FAILED), details.created=false/'unknown' with manual_cleanup and a named recovery path, plus response truncation rules (200 entries, LIMESURVEY_MAX_RESPONSE_CHARS) and the write-scope requirement. Annotations only cover the safety profile, which matches (non-destructive, not idempotent, no contradiction).

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?

It is front-loaded with the core purpose, but the body is an extremely dense, run-on paragraph mixing validation, error codes, return shape, truncation, and version-specific quirks with little formatting. Much of it earns its place, yet the lack of structure makes it hard to scan.

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 high-complexity, nested-spec creation tool, the description covers success, validation failure, import failure, partial failure, truncation, and version-specific edge cases. It even restates the return shape (redundant given the output schema) but nothing an agent needs to call it correctly 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% (baseline 3), and the description adds real semantics beyond it: language handling ('one string for every language or a map per language'), the scale_id convention for the second scale of types 1, : and ;, and the Ranking-question read-back behavior that differs across LimeSurvey 6 and 7. This clarifies cross-field relationships the flat schema cannot.

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 names a specific verb+resource ('Create a new survey from a survey description') and immediately scopes it with '(spec { survey, groups })'. It actively distinguishes itself from siblings: import_survey consumes the generated .lss, validate_spec pre-checks, get_survey_spec reads an existing spec, and it explicitly states it 'takes no file path, adds nothing to existing surveys, activates nothing and deletes nothing.' An agent can place this among add/import/activate without opening another schema.

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?

Clear context is given: use this when you have a spec, check it first with limesurvey_validate_spec, and use limesurvey_get_survey_spec to obtain a spec for an existing survey. The negative scoping ('adds nothing to existing surveys, activates nothing, deletes nothing') further routes the agent away from sibling mutation tools. It stops short of an explicit when-not-to-use statement for add_survey vs this tool, so it is strong but not exhaustive.

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

Deploy Server