Sampling Strategy Tools — MCP Tool Reference

Sampling strategy tools define target demographic distributions for creating representative respondent samples. Strategies contain factors — demographic dimensions with target proportions — used by pool generation to select respondents matching your sample design.

list_sampling_strategies

List all sampling strategies, 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 target_size, oversample_factor, factor_count, selection_algorithm, quality_metric.

---

get_sampling_strategy

Get a sampling strategy by ID, including the full factor definitions.

Parameter	Type	Required	Default	Description
strategy_id	string	Yes	—	Strategy UUID

Returns: Full strategy object with factors array, selection_algorithm, quality_metric, aggregation_method, require_email, exclude_respondent_ids.

---

create_sampling_strategy

Create a sampling strategy with demographic distribution factors.

Parameter	Type	Required	Default	Description
name	string	Yes	—	Strategy name
project_id	string	Yes	—	Parent project ID
target_size	integer	No	100	Target sample size
factors	object[]	No	—	Distribution factor definitions (see below)
selection_algorithm	string	No	"greedy"	"greedy" or "random_constrained"
oversample_factor	float	No	1.0	Non-response buffer (e.g., 1.2 = 20% extra)
quality_metric	string	No	"rmse"	"rmse", "mae", "chi_square", or "max_deviation"
description	string	No	—	Strategy description
require_email	boolean	No	false	Only include respondents with email addresses

Returns: { id, name, description, project_id, target_size, selection_algorithm, factor_count }

Factor Schema

Each factor in the factors array defines a demographic dimension:

Field	Type	Required	Default	Description
name	string	Yes	—	Display name (e.g., "Gender")
attribute_path	string	Yes	—	Respondent attribute (e.g., "gender") or QML item ID for outcome factors
target_distribution	object	Yes	—	Category → proportion mapping. Must sum to 1.0 (±0.01 tolerance)
factor_type	string	No	"discrete"	"discrete", "bucketed", or "geographic"
source	string	No	"demographic"	"demographic" (respondent property) or "outcome" (survey response column)
bucket_ranges	array	No	—	For bucketed type: list of [min, max, label] tuples
weight	float	No	1.0	Importance weight for this factor

Example:

{
  "name": "Gender",
  "attribute_path": "gender",
  "target_distribution": {"male": 0.48, "female": 0.50, "other": 0.02},
  "factor_type": "discrete",
  "source": "demographic",
  "weight": 1.0
}

---

create_default_strategy

Create a strategy with standard gender and age distribution factors.

Parameter	Type	Required	Default	Description
name	string	Yes	—	Strategy name
project_id	string	Yes	—	Parent project ID
target_size	integer	No	100	Target sample size

Returns: { id, name, description, project_id, target_size, factors: [...] }

Default factors:

• Gender: male 48%, female 50%, other 2%
• Age Group: 18–24 (15%), 25–34 (20%), 35–44 (20%), 45–54 (18%), 55–64 (15%), 65+ (12%)

---

update_sampling_strategy

Update an existing sampling strategy (partial update — only provided fields change).

Parameter	Type	Required	Default	Description
strategy_id	string	Yes	—	Strategy UUID
name	string	No	—	New name
description	string	No	—	New description
target_size	integer	No	—	New target size
oversample_factor	float	No	—	New oversample factor
factors	object[]	No	—	Replace all factors (not merged)
selection_algorithm	string	No	—	New algorithm
quality_metric	string	No	—	New quality metric
require_email	boolean	No	—	New email requirement

Returns: { id, name, target_size, factor_count, updated: true }

Factors Replacement

When factors is provided, it completely replaces the existing factor list — it does not merge.

---

delete_sampling_strategy

Delete a sampling strategy. Protected if the strategy is the default or has linked pools.

Parameter	Type	Required	Default	Description
strategy_id	string	Yes	—	Strategy UUID

Returns: { deleted: true, strategy_id, strategy_info: { name, project_id, target_size, factor_count } }

---

Error Handling

Factor Validation

Scenario	Response
Missing required field	{"error": "Each factor must have 'name', 'attribute_path', and 'target_distribution'"}
Distribution doesn't sum to 1.0	{"error": "Factor '{name}' target_distribution must sum to 1.0 (got {sum:.3f})"}
Invalid source value	{"error": "Factor '{name}' source must be 'demographic' or 'outcome'"}

Factor validation applies to both create_sampling_strategy and update_sampling_strategy.

Default Strategy Protection

Scenario	Response
Modify default strategy	{"error": "Cannot modify the default sampling strategy"}
Delete default strategy	{"error": "Cannot delete the default sampling strategy"}

Linked Pool Protection

Scenario	Response
Delete strategy with pools	{"error": "Cannot delete strategy: {count} pool(s) are linked to it", "linked_pool_ids": [...]}

Common Errors

Scenario	Response
Strategy not found	{"error": "Strategy {id} not found"}