Respondent Tools — MCP Tool Reference

Respondent tools manage survey targets — creating, updating, and deleting respondents, bulk generation for testing, and sending survey invitations. Respondents are not platform users; they access surveys via magic links without authentication.

list_respondents

List respondents with optional filters.

Parameter	Type	Required	Default	Description
source_system	string	No	—	Filter by source (e.g., "crm", "panel_provider")
project_id	string	No	—	Filter by project
name	string	No	—	Case-insensitive substring match
limit	integer	No	100	Maximum results to return

Returns: { items: [...], count, limit }

---

get_respondent

Get a respondent by ID.

Parameter	Type	Required	Default	Description
respondent_id	string	Yes	—	Respondent UUID

Returns: Respondent object or { error }.

---

create_respondent

Create a single respondent with demographic attributes.

Parameter	Type	Required	Default	Description
name	string	Yes	—	Display name
project_id	string	No	—	Project ID
email	string	No	—	Email for invitations
external_id	string	No	—	ID from external system (CRM, panel)
source_system	string	No	—	Source system name (e.g., "crm")
age	integer	No	—	Age
gender	string	No	—	Gender
location	string	No	—	Location
custom_attributes	object	No	{}	Custom key-value pairs for targeting

Returns: Created respondent object.

Demographic Attributes

Respondents support these demographic fields for sampling strategy matching and survey analysis:

Attribute	Type	Used By
age	integer	Age-based sampling factors, mass_fill_surveys persona weighting
gender	string	Gender-based sampling factors
location	string	Geographic sampling factors
custom_attributes	object	Custom targeting and segmentation

---

update_respondent

Update respondent information (partial update — only provided fields change).

Parameter	Type	Required	Default	Description
respondent_id	string	Yes	—	Respondent UUID
name	string	No	—	New name
email	string	No	—	New email
age	integer	No	—	New age
gender	string	No	—	New gender
location	string	No	—	New location
external_id	string	No	—	New external ID
source_system	string	No	—	New source system
custom_attributes	object	No	—	New custom attributes (replaces existing)

Returns: Updated respondent object. If no changes detected: { message: "No changes detected", respondent: {...} }.

---

delete_respondent

Remove a respondent.

Parameter	Type	Required	Default	Description
respondent_id	string	Yes	—	Respondent UUID

Returns: { deleted: true, respondent_id, respondent_info: { name, email, external_id, source_system } }

---

bulk_create_respondents

Create multiple respondents with realistic fake demographics. For test data only — do not use for production data.

Parameter	Type	Required	Default	Description
count	integer	Yes	—	Number to create (1–100)
project_id	string	No	—	Project ID
name_prefix	string	No	"Test"	Prefix for generated names
source_system	string	No	"bulk_generate"	Source system name
generate_demographics	boolean	No	true	Generate realistic demographics using Faker

Returns:

{
  "created": 50,
  "project_id": "...",
  "source_system": "bulk_generate",
  "respondents": [
    {"id": "...", "name": "John Smith", "email": "[email protected]", "project_id": "..."}
  ]
}

Generated Demographics

When generate_demographics is true (default), Faker generates:

Field	Generation Method
name	faker.name()
email	faker.email()
age	Random integer 18–75
gender	Random: "male", "female", or "other"
location	"{city}, {country}"
external_id	"bulk-{random_hex}"

When generate_demographics is false, generates sequential names ("Test Respondent 1") and emails with no demographic data.

---

generate_survey_access_token

Generate a magic link token for a respondent to access their survey without authentication.

Parameter	Type	Required	Default	Description
survey_id	string	Yes	—	Survey UUID
respondent_id	string	Yes	—	Respondent UUID (must match survey's respondent)
expiration_hours	integer	No	168	Hours until token expires (default: 7 days)

Returns:

{
  "token": "...",
  "survey_url": "https://sirway.dev.askalot.io/s/{token}",
  "survey_id": "...",
  "respondent_id": "...",
  "expiration_hours": 168
}

---

send_survey_invitation

Send a survey invitation email with a magic link to a respondent. Sends a real email.

Parameter	Type	Required	Default	Description
survey_id	string	Yes	—	Survey UUID
respondent_id	string	Yes	—	Respondent UUID (must match survey's respondent)
expiration_hours	integer	No	168	Hours until link expires (default: 7 days)
subject	string	No	—	Custom email subject. Default: "You're invited to complete: {questionnaire_name}"
body_template	string	No	—	Custom body with placeholders: {name}, {url}, {expiration}, {questionnaire}

Returns:

{
  "status": "sent",
  "survey_id": "...",
  "respondent_id": "...",
  "email": "[email protected]",
  "survey_url": "https://sirway.dev.askalot.io/s/{token}",
  "message_id": "...",
  "message_bus_used": true
}

---

Error Handling

Common Errors

Scenario	Response
Respondent not found	{"error": "Respondent {id} not found"}
Survey not found	{"error": "Survey {id} not found"}
Respondent mismatch	{"error": "Respondent is not the respondent for this survey"}
No email address	{"error": "Respondent has no email address"}
Opted out	{"error": "Respondent has opted out of notifications"}
Email send failed	{"error": "Failed to send email: {details}"}

Bulk Creation Limits

Scenario	Response
Count exceeds 100	{"error": "Maximum 100 respondents per request"}
Count below 1	{"error": "Count must be at least 1"}