Outils de vivier de répondants — référence des outils MCP
Les outils de vivier gèrent des groupes réutilisables de répondants destinés aux campagnes. Un vivier peut être créé à la main ou généré à partir d’une stratégie d’échantillonnage pour obtenir un échantillon représentatif. Les viviers générés par une stratégie suivent un score de qualité, enregistrent les paramètres de tirage avec lesquels ils ont été produits (taille demandée, facteur de suréchantillonnage, algorithme de sélection, exigence d’adresse e-mail, exclusions) et peuvent être actualisés avec ces mêmes réglages à mesure que la base de répondants évolue. La stratégie elle-même ne porte aucun paramètre de tirage : une même stratégie peut donc alimenter des viviers de tailles différentes.
list_respondent_pools
Section intitulée « list_respondent_pools »Liste tous les viviers de répondants, avec un filtre facultatif par projet ou par nom.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
project_id |
string |
Non | — | Filtre par identifiant de projet |
name |
string |
Non | — | Filtre par sous-chaîne, insensible à la casse |
limit |
integer |
Non | 100 |
Nombre maximal de résultats renvoyés |
Renvoie : { data: [...], count, limit }. Chaque élément comporte source_type, source_strategy_id, respondent_count, quality_score et les cinq paramètres de tirage (requested_size, oversample_factor, selection_algorithm, require_email, exclude_respondent_ids) — tous à null pour un vivier sans tirage enregistré (viviers manuels, fusionnés ou scindés).
get_respondent_pool
Section intitulée « get_respondent_pool »Récupère un vivier de répondants par son identifiant, avec la liste complète de ses répondants et le détail de sa qualité.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
pool_id |
string |
Oui | — | UUID du vivier |
Renvoie : l’objet vivier complet avec id, name, description, project_id, source_type, source_strategy_id, respondent_ids, respondent_count, les cinq paramètres de tirage (requested_size, oversample_factor, selection_algorithm, require_email, exclude_respondent_ids ; null en l’absence de tirage enregistré), quality_score, quality_details, generated_at.
requested_size correspond à ce que le tirage a demandé ; respondent_count au nombre de membres effectifs du vivier. Les deux peuvent légitimement différer : suréchantillonnage, manque de répondants éligibles ou modifications manuelles ultérieures.
create_respondent_pool
Section intitulée « create_respondent_pool »Crée un nouveau vivier de répondants (type de source manuel).
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
name |
string |
Oui | — | Nom du vivier |
description |
string |
Non | — | Description du vivier |
project_id |
string |
Non | — | Projet de rattachement |
respondent_ids |
string[] |
Non | — | Identifiants des répondants initiaux |
Renvoie : { id, name, description, project_id, respondent_count }
add_respondents_to_pool
Section intitulée « add_respondents_to_pool »Ajoute des répondants à un vivier existant. Les doublons sont ignorés sans avertissement.
Un vivier ne contient que les répondants de son propre projet : quiconque peut lire le vivier peut donc lire chacun de ses membres. Un répondant d’un autre projet est refusé, même si vous pouvez le lire. Dans une organisation qui partage son panel de répondants, ainsi que pour un vivier sans projet, n’importe quel répondant de l’organisation peut être ajouté.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
pool_id |
string |
Oui | — | UUID du vivier |
respondent_ids |
string[] |
Oui | — | Identifiants des répondants à ajouter |
Renvoie :
{ "pool_id": "...", "added": 8, "duplicates_skipped": 2, "new_total": 50}remove_respondents_from_pool
Section intitulée « remove_respondents_from_pool »Retire des répondants d’un vivier.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
pool_id |
string |
Oui | — | UUID du vivier |
respondent_ids |
string[] |
Oui | — | Identifiants des répondants à retirer |
Renvoie :
{ "pool_id": "...", "removed": 3, "not_found": 1, "new_total": 47}generate_pool_from_strategy
Section intitulée « generate_pool_from_strategy »Tire un nouveau vivier de répondants à partir d’une stratégie d’échantillonnage. L’algorithme de sélection retient les répondants correspondant aux distributions démographiques cibles de la stratégie. Les paramètres de tirage se transmettent à chaque appel et ne sont pas des propriétés de la stratégie ; le nouveau vivier les enregistre afin que chaque actualisation refasse le tirage de la même manière.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
strategy_id |
string |
Oui | — | UUID de la stratégie d’échantillonnage |
pool_name |
string |
Oui | — | Nom du nouveau vivier |
description |
string |
Non | — | Description du vivier |
project_id |
string |
Non | — | Identifiant du projet. Par défaut, le projet de la stratégie |
requested_size |
integer |
Oui | — | Nombre de répondants visé par ce tirage, avant suréchantillonnage (> 0) |
oversample_factor |
float |
Non | 1.0 |
Marge pour la non-réponse appliquée à requested_size (≥ 1 ; par ex. 1.2 = 20 % de plus) |
selection_algorithm |
string |
Non | "greedy" |
"greedy" ou "random_constrained" |
require_email |
boolean |
Non | false |
Seuls les répondants disposant d’une adresse e-mail sont éligibles |
exclude_respondent_ids |
string[] |
Non | [] |
UUID de répondants jamais éligibles pour ce tirage (par ex. une vague précédente) |
Les paramètres invalides (une taille de 0, un suréchantillonnage inférieur à 1, un algorithme inconnu, une exclusion qui n’est pas un UUID de répondant) sont refusés avant la lecture du moindre répondant.
Le tirage ne prend en compte que les répondants du projet auquel appartient le nouveau vivier : un vivier n’intègre donc jamais de répondants que les autres propriétaires du projet ne peuvent pas voir. Il en va de même lors de l’actualisation du vivier, quelle que soit la personne qui l’actualise. Dans une organisation qui partage son panel de répondants, ainsi que pour un vivier sans projet, le tirage porte sur l’ensemble du panel.
Exemple :
{ "strategy_id": "...", "pool_name": "Urban Millennials — main wave", "requested_size": 200, "oversample_factor": 1.2}Renvoie :
{ "pool_id": "...", "pool_name": "Urban Millennials — main wave", "strategy_id": "...", "respondent_count": 240, "requested_size": 200, "effective_size": 240, "quality_score": 0.94, "quality_details": { }, "computation_time_ms": 145, "warnings": []}effective_size vaut requested_size × oversample_factor (arrondi à l’entier inférieur) : c’est l’effectif visé par le tirage. Lorsque trop peu de répondants sont éligibles, le vivier compte moins de membres et warnings contient un message de déficit indiquant les deux tailles, par exemple Could not fill the draw: 90 of 120 drawn (requested 100 x oversample 1.2); only 90 candidates eligible.
Le vivier créé porte source_type: "strategy" et enregistre source_strategy_id ainsi que les paramètres de tirage, en vue d’une actualisation ultérieure. Pour tirer à une autre taille, générez un autre vivier à partir de la même stratégie.
preview_pool_generation
Section intitulée « preview_pool_generation »Prévisualise la génération d’un vivier sans le créer. Exécute le même tirage que generate_pool_from_strategy et renvoie les métriques de qualité.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
strategy_id |
string |
Oui | — | UUID de la stratégie d’échantillonnage |
project_id |
string |
Non | — | Projet auquel le vivier appartiendrait, comme pour generate_pool_from_strategy. Par défaut, le projet de la stratégie |
max_preview |
integer |
Non | 100 |
Nombre maximal d’identifiants de répondants inclus dans l’aperçu |
L’outil accepte aussi les mêmes paramètres de tirage que generate_pool_from_strategy : requested_size (obligatoire), oversample_factor, selection_algorithm, require_email, exclude_respondent_ids.
Renvoie :
{ "eligible_count": 500, "requested_size": 200, "effective_size": 200, "selected_count": 200, "quality_score": 0.94, "quality_details": { }, "sample_respondent_ids": ["..."], "computation_time_ms": 130, "warnings": []}refresh_pool_from_strategy
Section intitulée « refresh_pool_from_strategy »Refait sur place le tirage d’un vivier généré par stratégie, à partir de la base de répondants actuelle. Ne fonctionne que pour les viviers portant source_type: "strategy". L’actualisation n’accepte aucun paramètre de tirage : elle refait le tirage avec la taille demandée, le facteur de suréchantillonnage, l’algorithme, l’exigence d’adresse e-mail et les exclusions enregistrés sur le vivier lors de sa génération, en s’appuyant sur les facteurs actuels de la stratégie. Pour changer la taille, générez un nouveau vivier et affectez-le à la campagne.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
pool_id |
string |
Oui | — | UUID du vivier (doit avoir été généré par stratégie) |
Renvoie :
{ "pool_id": "...", "previous_size": 195, "new_size": 200, "added": 10, "removed": 5, "requested_size": 200, "effective_size": 200, "quality_score": 0.96, "quality_details": { }, "warnings": []}delete_respondent_pool
Section intitulée « delete_respondent_pool »Supprime un vivier de répondants.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
pool_id |
string |
Oui | — | UUID du vivier |
Renvoie : { pool_id, deleted }
Gestion des erreurs
Section intitulée « Gestion des erreurs »Erreurs courantes
Section intitulée « Erreurs courantes »| Cas | Réponse |
|---|---|
| Vivier introuvable | {"error": "Pool {id} not found"} |
| Stratégie introuvable, ou située dans un projet que l’appelant ne peut pas lire (génération, aperçu) | {"error": "Strategy {id} not found"} |
| Aucun répondant éligible | {"error": "No eligible respondents available for this strategy"} |
| Vivier non généré par stratégie | {"error": "Pool was not generated from a strategy — cannot refresh"} |
| Stratégie source supprimée, ou située dans un projet que l’appelant ne peut pas lire (actualisation) | {"error": "Source strategy {id} not found"} |
| Vivier de stratégie sans tirage enregistré (actualisation) | Conflit : le vivier n’a enregistré aucun paramètre de tirage et ne peut donc pas être actualisé. Générez plutôt un nouveau vivier à partir de la stratégie, à la taille souhaitée, et affectez-le à la campagne. |
| L’appelant n’est pas propriétaire du projet du vivier | {"error": "forbidden", "detail": "caller is not an owner of this project and lacks an admin role"} |
Gestion des doublons
Section intitulée « Gestion des doublons »add_respondents_to_pool détecte les doublons par des opérations ensemblistes. Les doublons sont ignorés sans avertissement et comptabilisés dans duplicates_skipped — aucune erreur n’est levée.
Suivi du type de source
Section intitulée « Suivi du type de source »| Type de source | Créé par | Actualisable |
|---|---|---|
"manual" |
create_respondent_pool |
Non |
"strategy" |
generate_pool_from_strategy |
Oui, avec les paramètres de tirage enregistrés sur le vivier |
Filtrage d’éligibilité
Section intitulée « Filtrage d’éligibilité »Tout tirage (génération, aperçu, actualisation) part des répondants que vous pouvez voir : l’ensemble du panel dans une organisation privée ou pour un administrateur, sinon les répondants des projets dont vous êtes propriétaire. Cela vaut aussi pour la stratégie par défaut de l’organisation : un tirage ne désigne donc jamais un répondant que list_respondents ne vous montrerait pas.
Il les filtre ensuite avant la sélection, selon les paramètres du tirage :
- Si
require_emailest activé, les répondants sans adresse e-mail sont exclus - Les répondants figurant dans
exclude_respondent_idssont exclus - S’il ne reste aucun répondant éligible, la génération et l’actualisation renvoient une erreur (une actualisation ne vide jamais un vivier) ; l’aperçu indique
eligible_count: 0
Un membre retiré à la main d’un vivier n’est pas ajouté à exclude_respondent_ids : la prochaine actualisation peut donc le tirer de nouveau.