Skip to main content
Glama

Invite survey participants

limesurvey_invite_participants

Send survey invitation emails to selected or eligible participants. Preview first with dry_run=true: it sends nothing and never calls invite_participants, it simulates the selection from the participant list and reports would_receive and…

Instructions

Send survey invitation emails to selected or eligible participants. Preview first with dry_run=true: it sends nothing and never calls invite_participants, it simulates the selection from the participant list and reports would_receive and would_not_receive with a reason for every participant who is skipped (completed, already_invited, emailstatus_not_ok, invalid_email_address, not_valid_yet, expired, ...). Without continue_on_error LimeSurvey stops at the first participant whose validity window fails; the preview names that participant as stops_at_tid. The report stays within LIMESURVEY_MAX_RESPONSE_CHARS regardless of the table size: unselected participants (token_ids) are only counted as not_selected, and would_receive, would_not_receive and not_reached list at most 100 entries each (truncated_lists says which were cut, counts hold the full numbers). send_email=false is NOT a dry run: it resends the invitation to those who were already invited. Verified against the LimeSurvey 6.17.11 source; older releases may differ. Requires confirm_send_email=true unless dry_run=true.

Calls LimeSurvey RemoteControl method invite_participants. Authentication uses the configured service account; do not provide a session key.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "survey_id": "<survey_id>"
    },
    "name": "limesurvey_invite_participants"
  }
}

Input Schema

NameRequiredDescriptionDefault
dry_runNoMCP-only, never sent to LimeSurvey. true: send nothing and do not call invite_participants; read the participants (list_participants) and report who would receive an invitation and why the others would not. Allowed under every write scope; confirm_send_email is not needed.
survey_idYesNumeric LimeSurvey survey ID.
token_idsNoOptional participant row IDs; null (or an empty list) selects eligible participants.
send_emailNoWhich participants get an email. true (default): invite only participants who were not invited yet (sent = N or empty). false: resend the invitation ONLY to participants who are already invited (sent holds a date) - it does not turn the sending off. Emails are sent in both cases. To see who would be mailed without sending, use dry_run=true.
response_formatNoOutput format. JSON preserves the complete structured result; Markdown is optimized for reading.json
continue_on_errorNoContinue after a participant whose validity window (validfrom/validuntil) fails; by default LimeSurvey stops at the first one.
confirm_send_emailNoRequired acknowledgement that email may be sent to participants; not needed with dry_run=true.
server_utc_offset_minutesNoMCP-only, never sent to LimeSurvey. UTC offset of the LimeSurvey server's local time in minutes (for example 120 for UTC+2). validfrom and validuntil are stored without a zone in that local time; without this value the timezone of the MCP host is assumed (reported as time_basis.offset_source).

Output Schema

NameRequiredDescriptionDefault
methodYes
resultYes
warningsNo
truncatedNo
truncation_messageNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changedv1.6.0
    • changedInput schema / properties / confirm_send_email / description
      Previous value: -"Required acknowledgement that email may be sent to participants."New value: +"Required acknowledgement that email may be sent to participants; not needed with dry_run=true."
    • changedInput schema / properties / continue_on_error / description
      Previous value: -"Continue after individual email errors."New value: +"Continue after a participant whose validity window (validfrom/validuntil) fails; by default LimeSurvey stops at the first one."
    • addedInput schema / properties / dry_run
      Added value: +{
      +  "default": false,
      +  "description": "MCP-only, never sent to LimeSurvey. true: send nothing and do not call invite_participants; read the participants (list_participants) and report who would receive an invitation and why the others would not. Allowed under every write scope; confirm_send_email is not needed.",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / send_email / description
      Previous value: -"Actually send invitation emails."New value: +"Which participants get an email. true (default): invite only participants who were not invited yet (sent = N or empty). false: resend the invitation ONLY to participants who are already invited (sent holds a date) - it does not turn the sending off. Emails are sent in both cases. To see who would be mailed without sending, use dry_run=true."
    • addedInput schema / properties / server_utc_offset_minutes
      Added value: +{
      +  "description": "MCP-only, never sent to LimeSurvey. UTC offset of the LimeSurvey server's local time in minutes (for example 120 for UTC+2). validfrom and validuntil are stored without a zone in that local time; without this value the timezone of the MCP host is assumed (reported as time_basis.offset_source).",
      +  "maximum": 840,
      +  "minimum": -840,
      +  "type": "integer"
      +}
    • changedInput schema / properties / token_ids / description
      Previous value: -"Optional participant row IDs; null selects eligible participants."New value: +"Optional participant row IDs; null (or an empty list) selects eligible participants."
    • changedInput schema / required
      Previous value: -[
      -  "survey_id",
      -  "confirm_send_email"
      -]New value: +[
      +  "survey_id"
      +]
    • addedOutput schema / properties / warnings
      Added value: +{
      +  "items": {
      +    "$ref": "#/definitions/__schema0"
      +  },
      +  "type": "array"
      +}
  2. First observedv1.3.1

TDQS

A4.3/5.0
Behavior5/5

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

Adds substantial context beyond annotations: stops at the first participant whose validity window fails (named as stops_at_tid unless continue_on_error), response truncation rules (LIMESURVEY_MAX_RESPONSE_CHARS, 100-entry lists, truncated_lists), the confirm_send_email gate, service-account auth, and the version-verification caveat.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and the dry_run preview workflow, and every sentence carries information. However, it is a dense block that restates several schema-level details, adding length without new value.

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?

Complete for a non-idempotent emailing tool: safety gate, dry-run behavior, error-continuation, timezone handling, and auth are all covered, and an output schema exists so return-format explanation is not needed.

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 baseline is 3, but the description adds cross-parameter semantics the schema does not: 'send_email=false is NOT a dry run: it resends the invitation to those who were already invited' and the interaction of confirm_send_email with dry_run. Some of this duplicates the schema text, capping it below 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Send survey invitation emails to selected or eligible participants.' Scope (selected vs eligible) is stated, but no sibling is named (e.g. remind_participants, mail_registered_participants), so the agent must infer the distinction from tool names.

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?

Gives clear operational routing with 'Preview first with dry_run=true' and 'Use dry_run=true to see who would be mailed without sending,' plus the confirm_send_email prerequisite. Guidance is all within-tool (dry_run vs. real send); it never routes to sibling tools like remind_participants.

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

Deploy Server

Other Tools