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

Geography beyond location belongs in custom_attributes

location is the only geographic field a respondent stores — free text, typically "City, Country". Finer geography (street, city, state, postal code, country as separate values) goes into custom_attributes, where it is addressable as custom_attributes.<key> everywhere a respondent attribute can be named: sampling factors and external-input mappings. A calibration target names the dataset column the attribute was extracted into, _custom_<key> (see set_calibration_targets). Extra top-level keys are ignored rather than stored, so a payload sending city as its own field loses that value silently.

---

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
}

When the survey's campaign offers the AI assistant, the result also carries connector_url, the respondent connector address (https://portor.<tenant>.askalot.io/respond/mcp), so an invitation you relay by hand can name both ways in. The pairing code itself is never returned here: the respondent gets it from their own survey page. See AI-Assisted Self-Interview.

---

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
}

When the survey's campaign offers the AI assistant, the email adds a paragraph telling the respondent they can open the link and choose to take the survey with their own AI assistant, and the result also carries connector_url.

---

bulk_delete_respondents

Delete multiple respondents by filter criteria. Uses a two-step workflow: call with dry_run=true first to preview what will be deleted, then call again with dry_run=false to execute.

At least one filter must be specified to prevent accidental mass deletion.

Parameter	Type	Required	Default	Description
source_system	string	No	—	Filter by source system (e.g., "bulk_generate", "mcp_review")
project_id	string	No	—	Filter by project ID
orphans_only	boolean	No	false	Only target respondents with no project (combines with other filters)
dry_run	boolean	No	true	Preview mode — returns count and sample without deleting

Dry run returns:

{
  "dry_run": true,
  "count": 50,
  "sample": [{"id": "...", "name": "...", "source_system": "bulk_generate", "project_id": null}],
  "message": "Would delete 50 respondents. Call again with dry_run=False to execute."
}

Execute returns: { dry_run: false, deleted: 50 }

Destructive Operation

This tool permanently deletes respondent records. Always preview with dry_run=true first.

---

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"}