LimeSurvey MCP Server

Read a survey, group or question as a description

limesurvey_get_survey_spec

Read-onlyIdempotent

Instructions

Read a survey, one group or one question as a survey description (spec), with read methods only. With survey_id alone the whole survey is read (level survey); with group_id one group (level group); with question_id one question (level question); group_id and question_id exclude each other. Returns { level, survey_id, group_id (level group), question_id (level question), languages, active, spec, ids, position, fingerprint, unreadable [{ code, detail }], missing_translations [{ path, language }] }. spec has the format of limesurvey_create_survey_from_spec: level survey { survey, groups }, level group one group, level question one question; every text is a map per language, line breaks are \n and HTML entities are decoded except the markup characters; attribute values equal to the default of the question theme are left out; subquestions and answers come ordered by scale, and scale_id appears only for scale 1 (the columns of : and ;, the second answer scale of 1). spec holds no IDs: ids lists them by path (level survey: groups [{ path, group_id }] and questions [{ path, code, question_id }]; level group: group_id and questions; level question: question_id and group_id) and position gives the 1-based place of a group in the survey or of a question in its group. fingerprint is the SHA-256 of the spec. unreadable lists what RemoteControl cannot read and the spec therefore lacks (conditions of the old condition table, quota members, URL parameter assignments, stored attributes that the type, theme or a plugin does not define, archived response columns, at level survey the survey settings outside the spec, the default of the "Other" option of M and P questions, texts of a question that has no text row in a language); an entry that belongs to an element also has path and language. missing_translations lists the texts that have no row in a survey language, which the map then lacks. The spec can be checked with limesurvey_validate_spec and, at level survey, creates a copy with limesurvey_create_survey_from_spec. The tool never shortens the answer: if it would exceed LIMESURVEY_MAX_RESPONSE_CHARS it answers SPEC_TOO_LARGE with an outline (level survey: group_id, title, questions and estimated_chars per group) so that groups can be read one by one. An ID of another survey answers GROUP_SURVEY_MISMATCH or QUESTION_SURVEY_MISMATCH. The tool changes nothing and needs no write scope.

Input Schema

Name	Required	Description
`group_id`	No	Optional ID of a group of this survey: read this group only.
`survey_id`	Yes	Numeric LimeSurvey survey ID.
`question_id`	No	Optional ID of a main question of this survey: read this question only.

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?

Goes well beyond the readOnly/idempotent annotations: it discloses the exact response shape, the SHA-256 fingerprint, the SPEC_TOO_LARGE fallback with group outline instead of silent truncation, the mismatch error codes for foreign IDs, and an exhaustive list of what 'unreadable' excludes from the spec. It also affirms the tool changes nothing and needs no write scope.

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?

Front-loaded with purpose, but then delivers everything as one very dense run-on paragraph mixing response shape, spec formatting rules, unreadable causes, and error codes. Much of it earns its place for a complex tool, yet the lack of scannable structure and the deep spec-internals detail make it heavier than necessary.

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 read tool it covers the modes, the return contract, the size ceiling and its fallback, and the error conditions, so an agent can call it correctly without trial and error. The detailed return enumeration is redundant against the output schema but harmless and adds clarity.

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 beyond it: the mutual exclusivity of group_id and question_id, and the level (survey/group/question) each parameter combination selects. It does not add format or validation detail beyond what the schema already states.

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?

Opens with a specific verb+resource ('Read a survey, one group or one question as a survey description (spec)') and immediately maps each ID combination to a distinct level, so the agent knows exactly which mode it is invoking. It distinguishes itself from read siblings such as get_survey_properties or list_questions by framing output as a spec with a fingerprint rather than raw properties.

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?

Explicitly states when to pass survey_id alone vs group_id vs question_id, notes group_id and question_id are mutually exclusive, and points to limesurvey_validate_spec and limesurvey_create_survey_from_spec as follow-ups. It does not, however, say when to prefer this over limesurvey_get_survey_properties / get_group_properties / get_question_properties, which cover overlapping read territory.

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

Deploy Server