Skip to content

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.

An advanced strategy cannot generate a pool

A strategy that carries outcome factors — factors built from survey response columns, appended by Advancing a Strategy — is refused here, and by preview_pool_generation and refresh_pool_from_strategy too. The error names the offending factors. An outcome factor's value comes from an answer, and pool selection runs before anyone has answered, so there is nothing to select on. Advanced strategies exist to grade a fielded sample; use a strategy whose factors are all respondent attributes to build one.

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"}
Not an owner of the pool's project {"error": "forbidden", "detail": "caller is not an owner of this project and lacks an admin role"}

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