Respondent Pool Tools — MCP Tool Reference

Pool tools manage reusable groups of respondents for campaigns. Pools can be created manually or generated from a sampling strategy for representative samples. Strategy-generated pools track quality scores and can be refreshed as the respondent base changes.

list_respondent_pools

List all respondent pools, optionally filtered by project or name.

Parameter	Type	Required	Default	Description
project_id	string	No	—	Filter by project ID
name	string	No	—	Case-insensitive substring filter
limit	integer	No	100	Maximum results to return

Returns: { items: [...], count, limit }. Each item includes source_type, source_strategy_id, respondent_count, and quality_score.

---

get_respondent_pool

Get a respondent pool by ID, including full respondent list and quality details.

Parameter	Type	Required	Default	Description
pool_id	string	Yes	—	Pool UUID

Returns: Full pool object with id, name, description, project_id, source_type, source_strategy_id, respondent_ids, respondent_count, quality_score, quality_details, generated_at.

---

create_respondent_pool

Create a new respondent pool (manual source type).

Parameter	Type	Required	Default	Description
name	string	Yes	—	Pool name
description	string	No	—	Pool description
project_id	string	No	—	Project for organization
respondent_ids	string[]	No	—	Initial respondent IDs

Returns: { id, name, description, project_id, respondent_count }

---

add_respondents_to_pool

Add respondents to an existing pool. Duplicates are silently skipped.

Parameter	Type	Required	Default	Description
pool_id	string	Yes	—	Pool UUID
respondent_ids	string[]	Yes	—	Respondent IDs to add

Returns:

{
  "pool_id": "...",
  "added": 8,
  "duplicates_skipped": 2,
  "new_total": 50
}

---

remove_respondents_from_pool

Remove respondents from a pool.

Parameter	Type	Required	Default	Description
pool_id	string	Yes	—	Pool UUID
respondent_ids	string[]	Yes	—	Respondent IDs to remove

Returns:

{
  "pool_id": "...",
  "removed": 3,
  "not_found": 1,
  "new_total": 47
}

---

generate_pool_from_strategy

Generate a new respondent pool using a sampling strategy. The strategy's selection algorithm selects respondents matching target demographic distributions.

Parameter	Type	Required	Default	Description
strategy_id	string	Yes	—	Sampling strategy UUID
pool_name	string	Yes	—	Name for the new pool
description	string	No	—	Pool description
project_id	string	No	—	Project ID. Defaults to the strategy's project

Returns:

{
  "pool_id": "...",
  "pool_name": "Urban Millennials",
  "strategy_id": "...",
  "respondent_count": 200,
  "quality_score": 0.94,
  "quality_details": { },
  "computation_time_ms": 145,
  "warnings": []
}

The created pool has source_type: "strategy" and stores the source_strategy_id for later refresh.

---

preview_pool_generation

Preview pool generation without creating the pool. Runs the selection algorithm and returns quality metrics.

Parameter	Type	Required	Default	Description
strategy_id	string	Yes	—	Sampling strategy UUID
max_preview	integer	No	100	Max respondent IDs to include in preview

Returns:

{
  "eligible_count": 500,
  "target_size": 200,
  "selected_count": 200,
  "quality_score": 0.94,
  "quality_details": { },
  "sample_respondent_ids": ["..."],
  "computation_time_ms": 130,
  "warnings": []
}

---

refresh_pool_from_strategy

Re-run the selection algorithm on a strategy-generated pool. Only works for pools with source_type: "strategy".

Parameter	Type	Required	Default	Description
pool_id	string	Yes	—	Pool UUID (must be strategy-generated)

Returns:

{
  "pool_id": "...",
  "previous_size": 195,
  "new_size": 200,
  "added": 10,
  "removed": 5,
  "quality_score": 0.96,
  "quality_details": { }
}

---

delete_respondent_pool

Delete a respondent pool.

Parameter	Type	Required	Default	Description
pool_id	string	Yes	—	Pool UUID

Returns: { deleted: true, pool_id, pool_info: { name, respondent_count, source_type } }

---

Error Handling

Common Errors

Scenario	Response
Pool not found	{"error": "Pool {id} not found"}
Strategy not found	{"error": "Strategy {id} not found"}
No eligible respondents	{"error": "No eligible respondents available for this strategy"}
Not strategy-generated	{"error": "Pool was not generated from a strategy — cannot refresh"}
Source strategy deleted	{"error": "Source strategy {id} not found"}

Duplicate Handling

add_respondents_to_pool uses set operations to detect duplicates. Duplicates are silently skipped and reported in the duplicates_skipped count — no error is raised.

Source Type Tracking

Source Type	Created By	Can Refresh
"manual"	create_respondent_pool	No
"strategy"	generate_pool_from_strategy	Yes

Eligibility Filtering

Strategy-based operations filter respondents before selection:

1. If strategy.require_email is set, respondents without email are excluded
2. Respondents in strategy.exclude_respondent_ids are excluded
3. If no eligible respondents remain, an error is returned