Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@limesurvey-mcp-server create a new survey from the template file survey.lss"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP (Model Context Protocol) server for LimeSurvey 6's RemoteControl 2 JSON-RPC
API. It exposes one MCP tool per API method (import_survey, activate_survey,
list_surveys, export_responses, add_participants, etc.), plus a diagnostic tool,
limesurvey_connection_test.
This repository is the standalone server: it doesn't depend on any other project. If
you're looking for help getting a coding agent to generate .lss/.lsq/.lsg surveys
and upload them with this server, check out the
limesurvey-ai-boost skill, which is
complementary and consumes these same tools.
Automatic session handling: credentials come from your configuration; the session
key is obtained, cached, and renewed automatically. The MCP client never handles
sSessionKey.
Files by path: import methods (import_survey, import_group, import_question,
upload_file) accept file_path; export methods (export_responses,
export_statistics, ...) accept output_path. The server base64-encodes/decodes for
you — it never dumps large files into the LLM's context. The same methods also accept
base64 content sent directly over HTTP.
Actionable errors: API failures come back as ERROR: ... text with the error code
(ERR_NO_PERMISSION, ERR_INVALID_SURVEY, ...) instead of a stack trace.
Full coverage of the RemoteControl 2 API: surveys, groups, questions, languages, participants/tokens, responses, quotas, users.
Related MCP server: Langflow MCP Server
Requires Python ≥3.10. pipx is recommended for installing it in an isolated environment without managing venvs by hand:
pipx install limesurvey-mcpIt also works with plain pip, inside your own virtual environment:
python3 -m venv .venv
source .venv/bin/activate # on Windows: .venv\Scripts\activate
pip install limesurvey-mcpBoth leave a limesurvey-mcp-server command available (on the PATH with pipx, or inside
the venv with pip).
The server needs 3 required variables and a few optional ones. You can provide them in two ways:
Option A — direct environment variables (recommended if your MCP client injects them, see below):
LIMESURVEY_URL=https://your-server/index.php/admin/remotecontrol
LIMESURVEY_USERNAME=admin
LIMESURVEY_PASSWORD=change-thisOption B — a .env file. Copy the template and fill it in:
cp .env.example .env # or download it from the repo if you only installed the packageThe server looks for .env in this order: LIMESURVEY_MCP_ENV_FILE (explicit path) →
$LIMESURVEY_MCP_HOME/.env → ~/.config/limesurvey-mcp/.env → ./.env in the directory
it's launched from. If none is found, it doesn't fail: it assumes the variables are
already present in the environment (Option A).
In LimeSurvey: Global settings → Interfaces → RemoteControl must be set to JSON-RPC (this server always uses JSON, never XML-RPC).
Available variables — see .env.example for details on each one
(LIMESURVEY_URL, LIMESURVEY_USERNAME, LIMESURVEY_PASSWORD, LIMESURVEY_AUTH_PLUGIN,
LIMESURVEY_TIMEOUT, LIMESURVEY_VERIFY_SSL).
stdio transport. Generic example (Claude Desktop, Claude Code, or any other MCP-compatible client):
{
"mcpServers": {
"limesurvey": {
"command": "limesurvey-mcp-server",
"env": {
"LIMESURVEY_URL": "https://your-server/index.php/admin/remotecontrol",
"LIMESURVEY_USERNAME": "admin",
"LIMESURVEY_PASSWORD": "change-this"
}
}
}
}If you'd rather not put credentials directly in the client config, omit the env block
and use a .env file (Option B) — in that case, add LIMESURVEY_MCP_HOME pointing to
the folder where you placed the .env.
Verify the installation with the limesurvey_connection_test tool before operating: it
authenticates and returns the site name and how many surveys you can see.
The server operates against a real LimeSurvey instance. delete_survey,
delete_group, delete_question, delete_response, delete_participants, and
activate_survey are destructive or hard to reverse.
invite_participants, remind_participants, and mail_registered_participants send
real emails.
The .env file (if you use one) contains credentials: don't commit it to version
control (.gitignore already excludes it) or share it in plain text.
Prefer testing against a test instance/survey before pointing at production.
git clone https://github.com/pmanciniq/limesurvey-mcp-server.git
cd limesurvey-mcp-server
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
cp .env.example .env # and fill it in
limesurvey-mcp-serverMIT. See LICENSE.
Activate a survey (creates the responses table). Returns the activation result.
| Name | Required | Description | Default |
|---|---|---|---|
| iSurveyID | Yes | ID of the survey to activate. | |
| userActivationSettings | No | Optional. Activation settings (e.g. anonymized, datestamp, ipaddr...). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds that activation 'creates the responses table,' which provides some behavioral context beyond annotations. However, it does not disclose side effects like whether existing data is affected, permissions needed, or reversibility. Annotations already indicate destructiveness, so the description adds moderate value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a parenthetical, covering the core purpose and outcome efficiently. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple activation tool with two parameters and no output schema, the description is mostly complete: it explains what activation does, the parameters are documented in the schema, and the return value is mentioned. Minor gaps like the exact format of the activation result or error conditions are acceptable given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for both parameters. The description does not add further meaning (e.g., default values or constraints for userActivationSettings). Baseline 3 is appropriate as the schema already captures all parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (activate a survey) and the specific outcome (creates the responses table). It differentiates from sibling tools like get, set, copy, delete, etc., which are distinct operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as prerequisites (e.g., survey must exist, not already activated) or when not to use it (e.g., if survey has responses or other constraints).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add an empty question group. Returns the new group ID.
| Name | Required | Description | Default |
|---|---|---|---|
| iSurveyID | Yes | Survey ID. | |
| sGroupTitle | Yes | Group name. | |
| sGroupDescription | No | Optional. Group description. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide basic safety hints (readOnlyHint=false, destructiveHint=false). The description adds 'empty question group' and 'returns the new group ID', but does not disclose aspects like idempotency (already hinted by idempotentHint=false) or permission requirements. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that states the action and return value with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward creation tool with 3 parameters and no output schema, the description covers the essential aspects: action and return value. However, it could mention that the group is added to a survey (implied by parameter) and any constraints like uniqueness of title.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter described. The description adds no extra meaning beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Add' and the resource 'empty question group', and specifies the return value. It distinguishes from siblings like 'import_group' which might import non-empty groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not indicate when to use this tool versus alternatives such as 'import_group' or 'set_group_properties', nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a language to a survey.
| Name | Required | Description | Default |
|---|---|---|---|
| iSurveyID | Yes | Survey ID. | |
| sLanguage | Yes | Language code to add, e.g. 'en', 'fr'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a write operation (readOnlyHint=false) that is not destructive. The description adds no behavioral context beyond the action, such as potential constraints or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and to the point. It efficiently states the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (2 params, no output schema), the description is basic but sufficient for a straightforward tool. However, it lacks usage context such as when a language can be added.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters. The description does not add any additional meaning to the parameters beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Add' and resource 'language to a survey'. It distinguishes from sibling tools like add_group, add_survey, etc. However, it does not explicitly differentiate its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not specify when to use this tool, prerequisites (e.g., survey must exist), or alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a response to a survey. Returns the ID of the inserted response.
| Name | Required | Description | Default |
|---|---|---|---|
| iSurveyID | Yes | Survey ID (must be active). | |
| aResponseData | Yes | Object {question_code: value} with the response. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false) and non-idempotent behavior. The description adds only the return ID, but does not disclose any side effects, authorization needs, or rate limits. Without annotations, this would be a significant gap, but annotations partially cover safety traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two sentences), immediately stating the action and return value. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity tool with 2 parameters and no output schema, the description adequately states the purpose and return. However, it omits validation behavior (e.g., error if survey inactive) and does not discuss possible side effects on the survey data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The tool description provides no additional meaning beyond what is already in the schema parameter descriptions. It does not add context like expected format for question_code values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add') and the resource ('response to a survey'), and specifies the return value. It is distinct from sibling tools like copy_survey or get_survey_properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., when to add a response vs. modify one). No prerequisites or exclusions are mentioned, despite the schema hinting the survey must be active.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an empty survey with the bare minimum (id, title, language). Returns the new survey ID.
| Name | Required | Description | Default |
|---|---|---|---|
| sformat | No | Presentation format: 'A' (all on one page), 'G' (group by group), 'S' (one question per page). Default 'G'. | |
| iSurveyID | Yes | Desired ID for the new survey (if it already exists, another is assigned). | |
| sSurveyTitle | Yes | Title of the new survey. | |
| sSurveyLanguage | Yes | Base language, e.g. 'es', 'en'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description aligns with annotations (readOnlyHint=false) and adds return value. No contradictions. Could mention behavior on duplicate iSurveyID, but schema covers it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with verb and resource. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters fully described in schema, no output schema needed beyond return ID. Adequate for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. Description adds no extra meaning beyond schema for parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates an empty survey with minimal fields (id, title, language) and returns the new ID. It distinguishes from siblings like copy_survey and set_survey_properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when creating a new survey from scratch. It doesn't explicitly contrast with alternatives, but the purpose is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Copy an existing survey to a new one. Returns the new survey ID.
| Name | Required | Description | Default |
|---|---|---|---|
| sNewname | Yes | Name of the new survey. | |
| DestSurveyID | No | Optional. Desired ID for the copy. | |
| iSurveyID_org | Yes | ID of the source survey. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-read-only and non-destructive behavior, which aligns with the description. The description adds that it returns the new ID, but does not disclose potential side effects like whether all sub-entities are copied or if there are limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two short sentences—with no wasted words. It front-loads the action and outcome.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple copy tool with no output schema, the description covers the essential purpose and return value. It is complete enough given the low complexity, though it could optionally mention that the copy includes all survey contents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all three parameters, so the description adds no additional meaning beyond the schema. The mention of the return value is not parameter-related.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'copy', the resource 'survey', and the outcome 'returns the new survey ID'. It effectively distinguishes from sibling tools like add_survey or import_survey.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for duplicating a survey but provides no explicit guidance on when to use this tool versus alternatives like add_survey or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import participants into the central participants database (CPDB).
| Name | Required | Description | Default |
|---|---|---|---|
| update | No | Optional. True = update existing ones. Default False. | |
| aParticipants | Yes | Array of participants to import into the CPDB. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and openWorldHint=true, which the description does not elaborate on. The description adds no behavioral context beyond the basic action, leaving potential side effects or failure modes unstated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that conveys the essential function. It is front-loaded and contains no extraneous information, though it could benefit from slightly more structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool lacks an output schema, and the description does not explain what the tool returns or how to interpret results (e.g., success indicators, error behavior). Given the import nature, more context on duplicate handling or validation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full descriptions for both parameters (update and aParticipants), so the description adds no additional semantics. With 100% schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Import' and the resource 'participants into the central participants database (CPDB),' providing a specific purpose. It distinguishes from sibling tools like 'import_group' which targets groups, not participants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The sibling tools are survey- or group-focused, so the context is implied, but no usage conditions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a group from a survey. Returns the deleted ID.
| Name | Required | Description | Default |
|---|---|---|---|
| iGroupID | Yes | ID of the group to delete. | |
| iSurveyID | Yes | Survey ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and idempotentHint=false. The description adds that it returns the deleted ID, but does not disclose additional behavioral traits such as permanence, cascading effects, or permission requirements. The value added beyond annotations is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It could be slightly more informative, but it is appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and a simple input schema, the description is minimal. It lacks details about side effects (e.g., cascading deletes, irreversibility) and error conditions (e.g., what happens if group doesn't exist). The return value is mentioned, but more context is needed for a deletion tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters documented. The description does not add extra meaning beyond what the schema provides, leading to a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete a group from a survey') and the return value ('Returns the deleted ID'). It uses a specific verb and resource, distinguishing it from sibling tools like 'list_groups' or 'add_group'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool versus alternatives, nor does it mention prerequisites (e.g., survey must exist, group must be present). No context on when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a question by its ID. Returns the deleted ID.
| Name | Required | Description | Default |
|---|---|---|---|
| iQuestionID | Yes | ID of the question to delete. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, so the description's mention of 'Delete' adds little beyond that. It does disclose the return value but omits side effects like cascading deletion of responses or preconditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no extraneous words. Every part (verb, resource, return value) is essential.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one parameter and no output schema, the description is nearly complete. It specifies the action and return value. However, it could mention the impact on associated survey data or that the ID must exist.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter, and the description does not add extra meaning beyond the schema's 'ID of the question to delete.' Hence, baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete), the resource (question by ID), and the return value (the deleted ID). It is distinct from sibling tools that list, get properties, or set properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. For example, it does not mention that deletion is irreversible or that settings like deactivation might be preferable in some cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a survey by its ID. Irreversible.
| Name | Required | Description | Default |
|---|---|---|---|
| iSurveyID | Yes | ID of the survey to delete. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds 'Irreversible,' which confirms but does not substantially extend the behavioral transparency beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two short sentences. Every word serves a purpose: stating the action and emphasizing irreversibility.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter, no output schema, and clear annotations), the description is sufficient to convey its core function and consequence. Minor missing details like error handling are not critical for a straightforward delete operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a description for iSurveyID. The description does not add any additional meaning or clarification beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete'), the resource ('survey'), and the method ('by its ID'). This distinguishes it from sibling tools like copy_survey or activate_survey, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., deactivate_survey or copy_survey). It only states what it does, leaving the agent to infer appropriate use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the fieldmap of a survey.
| Name | Required | Description | Default |
|---|---|---|---|
| language | No | Optional. Language (default: the survey's). | |
| surveyId | Yes | Survey ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with the readOnlyHint and destructiveHint annotations by indicating a read operation ('Get'). It does not contradict annotations, but it also adds no additional behavioral context beyond what the structured data already conveys. With annotations covering safety traits, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is appropriately sized for the tool's simplicity and is front-loaded with the key action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description should clarify what the fieldmap contains or its structure. It does not, leaving a significant gap. The context signals (e.g., openWorldHint) suggest variability, but without elaboration, the description is incomplete for an AI agent to understand the return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already well-documented in the schema. The description ('Get the fieldmap of a survey') adds no extra meaning beyond confirming the purpose. The baseline of 3 is justified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Get) and the resource (fieldmap of a survey). However, it does not explain what a fieldmap is, leaving some ambiguity. It is distinguishable from siblings like get_survey_properties or get_summary by using the term 'fieldmap', but lacks specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, context, or exclusions, making it difficult for an AI agent to select it over similar tools like get_survey_properties or get_summary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get properties of a group.
| Name | Required | Description | Default |
|---|---|---|---|
| iGroupID | Yes | Group ID. | |
| sLanguage | No | Optional. Language for multilingual groups. | |
| aGroupSettings | No | Optional. Properties to get. Null = all. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's simple statement adds no new behavioral context. It does not disclose what happens if the group does not exist, how language affects results, or the nature of the properties returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no extraneous words, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description should hint at what properties are returned or the effect of optional parameters. It provides none of this context, making it incomplete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The description does not add any additional meaning beyond the schema, but since coverage is high, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get properties of a group' uses a specific verb ('Get') and a clear resource ('properties of a group'), which clearly distinguishes it from sibling tools like set_group_properties or list_groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get_survey_properties or get_question_properties, nor does it mention prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get properties of a question (includes answeroptions, subquestions, attributes...).
| Name | Required | Description | Default |
|---|---|---|---|
| sLanguage | No | Optional. Language. | |
| iQuestionID | Yes | Question ID. | |
| aQuestionSettings | No | Optional. Properties to get. Null = all. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds context about included properties but does not elaborate on open world behavior, performance implications, or any side effects beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no unnecessary words. However, adding a word like 'Read-only' could improve front-loading, though annotations already cover that aspect.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must convey return value structure. It lists example included properties but is vague on the full structure or whether all properties are always present. Given moderate complexity, it is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; all three parameters have descriptions in the schema. The description adds no additional information about parameters beyond what's in the schema, meeting the baseline for complete schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'properties of a question', and includes examples of what is retrieved (answeroptions, subquestions, attributes). This distinguishes it from sibling tools like set_question_properties or get_survey_properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not mention prerequisites, such as requiring a survey context, or when not to use it. Sibling tools are listed but no comparative advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Participation summary for a survey (complete/incomplete responses, token usage...).
| Name | Required | Description | Default |
|---|---|---|---|
| iSurveyID | Yes | Survey ID. | |
| sStatName | No | Specific statistic or 'all'. Options: completed_responses, incomplete_responses, full_responses, token_count, token_invalid, token_sent, token_opted_out, token_completed, token_screenout. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to repeat safety info. It adds context about token usage but does not disclose additional behavioral traits like pagination or data freshness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently communicates the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately conveys what the summary contains (responses and token details). It covers the key aspects but lacks details on structure or specificity about the 'all' option.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters documented. The description adds minimal value beyond the schema, only hinting at token usage which is already covered by the sStatName enum options.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides a participation summary for a survey, listing examples like complete/incomplete responses and token usage. It distinguishes the tool from sibling tools (e.g., get_survey_properties, list_questions) by focusing on participation statistics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives. While the examples hint at its purpose, there is no guidance on when not to use it or mention of sibling tools for different aspects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get properties of a survey (all or only the ones requested).
| Name | Required | Description | Default |
|---|---|---|---|
| iSurveyID | Yes | Survey ID. | |
| aSurveySettings | No | Optional. List of property names to get. Null = all. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds the ability to request specific properties but no additional behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with verb and resource. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with no output schema, the description is minimally adequate. It does not explain return format or pagination, but given the tool's simplicity, this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters thoroughly. The description adds meaning by clarifying that aSurveySettings=null retrieves all properties, but this is inferrable from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Get properties of a survey' with scope 'all or only the ones requested', effectively distinguishing it from sibling tools like get_summary or get_fieldmap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Despite many sibling tools (e.g., get_summary, list_groups), the description does not mention exclusion criteria or contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import a group (.lsg/.csv file) into a survey. Pass file_path or sImportData in base64.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | No | Local path to a file. If given, the server reads it and base64-encodes it automatically (alternative to passing the content directly). | |
| sImportData | No | File content in BASE64. Not needed if using `file_path`. | |
| sNewGroupName | No | Optional. New group name. | |
| sImportDataType | No | Type: 'lsg' or 'csv'. Inferred from the extension if using `file_path`. | |
| sNewGroupDescription | No | Optional. New group description. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description indicates mutation (importing) and the two input methods (file_path or sImportData), but lacks details on whether duplicate groups are overwritten, error handling, or permission requirements. Annotations provide non-destructive hint, but behavioral context is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that front-loads purpose and key parameter alternatives. No fluff or redundant information. Ideal conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 optional parameters and no output schema, the description covers the primary usage scenario. It could mention behavior on duplicate group names or validation, but overall sufficient for a straightforward import tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are documented. The description adds value by clarifying the mutual exclusivity of file_path and sImportData, and the expected file format (.lsg/.csv). This goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's action ('Import a group') and resource (a group from .lsg/.csv file into a survey). It distinguishes from sibling tools like add_group by specifying file-based import.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a file is available, but does not explicitly state when to use this tool over siblings (e.g., list_groups, add_group) or when not to use it. No exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import a survey from a .lss/.csv/.txt/.lsa file. Returns the new survey ID. Pass file_path with the local path to the .lss (recommended) OR sImportData in base64.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | No | Local path to a file. If given, the server reads it and base64-encodes it automatically (alternative to passing the content directly). | |
| sImportData | No | File content in BASE64. Not needed if using `file_path`. | |
| DestSurveyID | No | Optional. Desired ID (if in use, another is assigned). | |
| sNewSurveyName | No | Optional. New name for the imported survey. | |
| sImportDataType | No | Type: 'lss', 'csv', 'txt', or 'lsa'. Inferred from the extension if using `file_path`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-readonly and non-destructive behavior. The description adds the return value (new survey ID) and the file/ base64 handling, enhancing transparency without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with purpose, and contains no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters and no output schema, the description covers purpose, return, and parameter hints adequately. Minor gap: no mention of error conditions, but schema provides sufficient detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds valuable guidance: file_path is recommended, server auto-encodes, and sImportDataType is inferred from extension. This clarifies the relationship between parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Import a survey from a .lss/.csv/.txt/.lsa file' with a specific verb and resource, and distinguishes it from sibling tools like copy_survey or add_survey by emphasizing file import.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains the two parameter alternatives (file_path recommended vs sImportData) and implies usage context, but lacks explicit comparisons to siblings or when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify configuration and connectivity with LimeSurvey: authenticates with the .env credentials and returns the site name and the number of visible surveys. Use it before operating if you're not sure the connection works.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true and openWorldHint=true, and the description adds context about authentication and the specific return values (site name, visible surveys). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the key information: verification purpose and usage suggestion. No extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of a connection test, the description fully covers what the tool does, what it returns, and when to use it. No output schema exists, but the description explains the return values (site name, visible surveys).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. The description adds no new parameter details, but it is not needed. The baseline for zero-parameter tools is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool verifies configuration and connectivity, authenticates, and returns specific values (site name, visible surveys). This distinguishes it from sibling tools that perform operations like copy or activate surveys.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends using this tool before operating when unsure about connectivity. It does not mention when not to use or alternatives, but the guidance is clear and sufficient for a simple diagnostic tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the question groups of a survey.
| Name | Required | Description | Default |
|---|---|---|---|
| iSurveyID | Yes | Survey ID. | |
| sLanguage | No | Optional. Language for multilingual groups. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already specify readOnlyHint=true; description adds no additional behavioral context beyond the obvious 'list' operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words, purpose immediately clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema; description does not specify return structure or fields of groups, leaving agent uninformed about what the response contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides 100% parameter descriptions; description adds no extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'list' and resource 'question groups of a survey', distinct from siblings like list_questions and add_group.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage for viewing groups, but no explicit when-to-use, when-not-to-use, or alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List questions (and subquestions) of a survey or group.
| Name | Required | Description | Default |
|---|---|---|---|
| iGroupID | No | Optional. Group ID to filter by. | |
| iSurveyID | Yes | Survey ID. | |
| sLanguage | No | Optional. Language for multilingual questions. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds limited behavioral context. It clarifies that subquestions are included, which is valuable beyond annotations, but doesn't elaborate on optional filtering behavior or pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately states the action and scope. It is front-loaded and contains no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a listing tool with no output schema, the description fails to mention the return format (e.g., list of question IDs, details). It adequately covers the purpose and parameter roles but lacks completeness regarding output and edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all three parameters. The description adds no additional parameter semantics, so it meets the baseline but does not enhance understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'List' and the resource 'questions', and explicitly mentions inclusion of subquestions. It distinguishes from sibling tools like 'list_groups' (which lists groups) and 'get_question_properties' (which retrieves properties for a specific question).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use: to list questions of a survey or group. However, it provides no explicit guidance on when not to use or alternatives, such as 'get_question_properties' for detailed properties or 'delete_question' for removal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the quotas of a survey.
| Name | Required | Description | Default |
|---|---|---|---|
| iSurveyID | Yes | Survey ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description does not add behavioral info beyond annotations. Annotations already declare readOnlyHint=true, openWorldHint=true, which this aligns with. No additional disclosure (e.g., pagination, limits).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, clear sentence with no unnecessary words. Efficiently conveys purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with full schema coverage, annotations, and no output schema, the description is adequate. Minimal but complete enough for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter described as 'Survey ID.' Description adds no extra meaning beyond schema, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states 'List the quotas of a survey.' It uses a specific verb (List) and resource (quotas), clearly distinguishing it from siblings like list_surveys, list_questions, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. No mention of context, prerequisites, or when quotas are available.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the user's surveys (id, title, group, dates, whether active).
| Name | Required | Description | Default |
|---|---|---|---|
| gsid | No | Optional. Survey group ID to filter by. | |
| sUsername | No | Optional. User whose surveys to list (admin only). Null = own surveys. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description need not restate that. The description adds that the output includes specific fields, which is useful but minimal. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is front-loaded with the core purpose. However, it could be slightly more structured (e.g., separate lines for output fields), but still concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with no output schema, the description specifies the output fields (id, title, group, dates, active). No further details like pagination or sorting are expected given the tool's simplicity and the presence of annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description does not need to add parameter details. The description does not mention parameters, but the schema already covers them adequately. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list), resource (user's surveys), and the fields returned (id, title, group, dates, whether active). It distinguishes from sibling tools like get_survey_properties or copy_survey by focusing on listing multiple surveys.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided. It is implied that this tool is for listing surveys, but there is no mention of alternatives or exclusions, such as when to use get_survey_properties for a single survey.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send registration emails to the registered participants of a survey.
| Name | Required | Description | Default |
|---|---|---|---|
| iSurveyID | Yes | Survey ID. | |
| overrideAllConditions | No | Optional. Conditions that override the defaults. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with annotations (non-read-only, non-destructive). However, it does not disclose behavioral details such as whether conditions affect sending, whether emails are sent immediately, or if there are rate limits. The 'openWorldHint' annotation suggests the output may not be fully specified, but this is not elaborated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is direct and free of unnecessary words. It communicates the essential purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple email-sending mutation tool with two parameters, the description covers the core action. However, it does not mention that the tool uses survey's registration email settings or that it only sends to registered participants (assumed). The conditions parameter and its impact on the behavior are left unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. The description adds no extra meaning beyond the schema. The 'overrideAllConditions' parameter remains vague; the description does not clarify what 'conditions' refer to (e.g., participant eligibility or email content).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('send registration emails') and the target ('registered participants of a survey'). It is specific and distinguishes from sibling tools like 'remind_participants' which handle reminder emails, but the distinction is implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., 'remind_participants'). No conditions or prerequisites are mentioned. The description only states the action without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send email reminders to participants of a survey.
| Name | Required | Description | Default |
|---|---|---|---|
| aTokenIds | No | Optional. Participant ID filter. | |
| iSurveyID | Yes | Survey ID. | |
| iMaxReminders | No | Optional. Maximum number of reminders. | |
| continueOnError | No | Optional. Don't stop on the first invalid one. Default False. | |
| iMinDaysBetween | No | Optional. Minimum days since the last reminder. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is consistent with annotations (e.g., mutation implied by 'send'), but it does not add any behavioral context beyond what annotations already convey, such as auth requirements or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that gets to the point. It is concise but could arguably include more context without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one required parameter and no output schema, the description is adequate but lacks details about optional parameters' effects (e.g., what happens when token IDs are provided).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters have descriptions in the input schema (100% coverage), so the description does not need to add parameter details. It does not provide any additional semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (send) and the resource (email reminders to participants). However, it does not differentiate from the sibling 'mail_registered_participants', which may cause confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'mail_registered_participants' or under what conditions reminders should be sent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set properties of a group ('sid' and 'gid' cannot be set).
| Name | Required | Description | Default |
|---|---|---|---|
| iGroupID | Yes | Group ID. | |
| aGroupData | Yes | Object {property: value} to set. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false), non-destructive (destructiveHint=false), non-idempotent, and open-world. The description adds that 'sid' and 'gid' cannot be set, which is a valuable behavioral constraint not captured by annotations. However, it does not disclose other potential behaviors like overwrite vs. merge semantics, side effects, or required permissions. It provides moderate additional transparency on top of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately conveys the core purpose and an important constraint. It is front-loaded with the main action and contains no redundant information. Every word is necessary and contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter mutation tool with annotations present, the description is largely sufficient. It states the main operation and a key restriction. However, it does not mention return values or error behavior, which could be useful given no output schema. Despite this, the description covers the essential context needed for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described. The description adds critical meaning by explicitly listing the properties that cannot be set ('sid' and 'gid'), which is not present in the schema. This helps the agent avoid invalid calls. The description does not elaborate on the format of 'aGroupData' beyond 'Object {property: value}', but given the schema already specifies it's an object, the added restriction is valuable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: setting properties of a group, with the explicit restriction that 'sid' and 'gid' cannot be set. This distinguishes it from sibling tools like 'get_group_properties' (reading), 'add_group' (creation), and 'delete_group' (removal). The verb 'set' and resource 'group properties' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., group must exist), or any conditions under which this tool should be avoided. While the restriction on 'sid' and 'gid' hints at constraints, there is no direct statement about usage context or comparisons with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set properties of a question (qid, gid, sid, type, language... cannot be set).
| Name | Required | Description | Default |
|---|---|---|---|
| sLanguage | No | Optional. Language. | |
| iQuestionID | Yes | Question ID. | |
| aQuestionData | Yes | Object {property: value} to set. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-readonly (readOnlyHint=false) and non-destructive (destructiveHint=false), so the description's extra note about unsettable properties adds minimal behavioral context. It does not disclose side effects, error handling, or atomicity beyond what annotations imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the primary action and appends a concise constraint. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with a nested object parameter and no output schema, the description lacks details on success/failure reporting, response format, or partial update behavior. Schema and annotations cover only part of the context, leaving gaps for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though schema description coverage is 100%, the main description adds unique value by specifying which properties cannot be set, guiding valid usage of the aQuestionData parameter. This provides semantic constraints beyond the schema's raw property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Set' and resource 'properties of a question', and explicitly lists properties that cannot be set (qid, gid, sid, type, language), distinguishing it from siblings like get_question_properties or set_survey_properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a useful constraint on which properties cannot be set, but does not explicitly explain when to use this tool versus alternatives (e.g., get_question_properties for reading, or when to avoid setting certain properties). It gives indirect guidance but lacks explicit when-to-use or when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set properties of a survey.
| Name | Required | Description | Default |
|---|---|---|---|
| iSurveyID | Yes | Survey ID. | |
| aSurveyData | Yes | Object {property: value} to set. 'sid' and 'active' cannot be set. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates a write operation ('Set'), which aligns with readOnlyHint=false. Annotations already convey that it is non-destructive and open-world. The description adds no further behavioral details (e.g., side effects, rate limits, authentication needs) beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one sentence) but lacks critical context, such as the restriction on setting 'sid' and 'active'. It is not front-loaded with the most important information, and the brevity sacrifices completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has two parameters (one an object) and no output schema, the description should explain key behaviors like the immutability of 'sid' and 'active', but it does not. The description is insufficient for an agent to fully understand the tool's operation and constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for both parameters (iSurveyID and aSurveyData). The description adds no additional meaning beyond the schema, so it meets the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Set') and resource ('survey properties'), making the tool's purpose understandable. However, it does not distinguish it from sibling tools like set_group_properties or set_question_properties, and it omits the important constraint that 'sid' and 'active' cannot be set (though that is in the schema).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., get_survey_properties for reading, activate_survey for activation). There is no mention of prerequisites or context-specific scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0activate_surveyadd_groupadd_languageadd_responseadd_surveycopy_surveycpd_importParticipantsdelete_groupdelete_questiondelete_surveyget_fieldmapget_group_propertiesget_question_propertiesget_summaryget_survey_propertiesimport_groupimport_surveylimesurvey_connection_testlist_groupslist_questionslist_quotaslist_surveysmail_registered_participantsremind_participantsset_group_propertiesset_question_propertiesset_survey_propertiesScored across 27 tools
Tools are mostly grouped by resource (surveys, groups, questions, participants, responses) and the verb_noun names make their targets clear. A couple of pairs such as get_summary vs get_fieldmap and remind_participants vs mail_registered_participants could be confused, but the descriptions generally resolve the ambiguity.
Most tools follow a consistent verb_noun snake_case pattern like list_surveys, add_group, and delete_question. The main deviations are cpd_importParticipants, which mixes prefix and camelCase, and limesurvey_connection_test, which is a noun phrase rather than a verb-based action.
With 27 tools, the server exceeds the threshold where tool selection becomes unwieldy. While LimeSurvey is a broad domain, many of these tools could be consolidated or the server split into focused sub-servers to reduce mental overhead.
The server covers surveys, groups, and several property operations, but key lifecycle gaps exist: there is no add_question, no response read/update/delete, no quota mutation, and no survey deactivate/export. These missing operations will cause failures in common LimeSurvey automation workflows.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
MCP server exposing the Backtest360 engine API as tools for AI agents.
