Befragtenpool-Tools — MCP-Tool-Referenz
Die Pool-Tools verwalten wiederverwendbare Gruppen von Befragten für Kampagnen. Pools lassen sich manuell anlegen oder für repräsentative Stichproben aus einer Stichprobenstrategie erzeugen. Aus einer Strategie erzeugte Pools führen Qualitätsscores, halten die Ziehungseinstellungen fest, mit denen sie erzeugt wurden (angeforderte Größe, Oversampling-Faktor, Auswahlalgorithmus, E-Mail-Pflicht, Ausschlüsse), und lassen sich mit denselben Einstellungen aktualisieren, wenn sich der Bestand an Befragten ändert. Die Strategie selbst trägt keine Ziehungseinstellungen, sodass eine Strategie Pools unterschiedlicher Größe speisen kann.
list_respondent_pools
Abschnitt betitelt „list_respondent_pools“Listet alle Befragtenpools auf, optional nach Projekt oder Namen gefiltert.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
project_id |
string |
Nein | — | Nach Projekt-ID filtern |
name |
string |
Nein | — | Teilzeichenfolgen-Filter ohne Berücksichtigung der Groß- und Kleinschreibung |
limit |
integer |
Nein | 100 |
Maximale Anzahl an Ergebnissen |
Rückgabe: { data: [...], count, limit }. Jeder Eintrag enthält source_type, source_strategy_id, respondent_count, quality_score und die fünf Ziehungseinstellungen (requested_size, oversample_factor, selection_algorithm, require_email, exclude_respondent_ids) – alle null bei einem Pool ohne festgehaltene Ziehung (manuelle, zusammengeführte oder aufgeteilte Pools).
get_respondent_pool
Abschnitt betitelt „get_respondent_pool“Ruft einen Befragtenpool anhand seiner ID ab, einschließlich der vollständigen Liste der Befragten und der Qualitätsdetails.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
pool_id |
string |
Ja | — | UUID des Pools |
Rückgabe: Vollständiges Pool-Objekt mit id, name, description, project_id, source_type, source_strategy_id, respondent_ids, respondent_count, den fünf Ziehungseinstellungen (requested_size, oversample_factor, selection_algorithm, require_email, exclude_respondent_ids; null, wenn keine Ziehung festgehalten ist), quality_score, quality_details, generated_at.
requested_size ist das, was die Ziehung angefordert hat; respondent_count ist die tatsächliche Zahl der Mitglieder des Pools. Beide dürfen voneinander abweichen – durch Oversampling, einen Mangel an geeigneten Befragten oder spätere manuelle Änderungen.
create_respondent_pool
Abschnitt betitelt „create_respondent_pool“Legt einen neuen Befragtenpool an (Quelltyp manuell).
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
name |
string |
Ja | — | Name des Pools |
description |
string |
Nein | — | Beschreibung des Pools |
project_id |
string |
Nein | — | Projekt zur Zuordnung |
respondent_ids |
string[] |
Nein | — | IDs der Befragten, die der Pool von Beginn an enthält |
Rückgabe: { id, name, description, project_id, respondent_count }
add_respondents_to_pool
Abschnitt betitelt „add_respondents_to_pool“Fügt einem bestehenden Pool Befragte hinzu. Duplikate werden stillschweigend übersprungen.
Ein Pool enthält nur Befragte seines eigenen Projekts, sodass jede Person, die den Pool lesen darf, auch jedes Mitglied lesen darf. Eine befragte Person aus einem anderen Projekt wird abgelehnt, selbst wenn Sie sie lesen dürfen. In einer Organisation, die ihr Befragtenpanel teilt, und bei einem Pool ohne Projekt kann jede befragte Person der Organisation hinzugefügt werden.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
pool_id |
string |
Ja | — | UUID des Pools |
respondent_ids |
string[] |
Ja | — | Hinzuzufügende IDs der Befragten |
Rückgabe:
{ "pool_id": "...", "added": 8, "duplicates_skipped": 2, "new_total": 50}remove_respondents_from_pool
Abschnitt betitelt „remove_respondents_from_pool“Entfernt Befragte aus einem Pool.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
pool_id |
string |
Ja | — | UUID des Pools |
respondent_ids |
string[] |
Ja | — | Zu entfernende IDs der Befragten |
Rückgabe:
{ "pool_id": "...", "removed": 3, "not_found": 1, "new_total": 47}generate_pool_from_strategy
Abschnitt betitelt „generate_pool_from_strategy“Zieht einen neuen Befragtenpool aus einer Stichprobenstrategie. Der Auswahlalgorithmus wählt Befragte, die den demografischen Zielverteilungen der Strategie entsprechen. Die Ziehungseinstellungen sind hier Eingaben, keine Eigenschaften der Strategie, und der neue Pool speichert sie, sodass jede Aktualisierung auf dieselbe Weise neu zieht.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
strategy_id |
string |
Ja | — | UUID der Stichprobenstrategie |
pool_name |
string |
Ja | — | Name des neuen Pools |
description |
string |
Nein | — | Beschreibung des Pools |
project_id |
string |
Nein | — | Projekt-ID. Standard ist das Projekt der Strategie |
requested_size |
integer |
Ja | — | Anzahl der Befragten, für die diese Ziehung gedacht ist, vor dem Oversampling (> 0) |
oversample_factor |
float |
Nein | 1.0 |
Puffer für Nonresponse auf requested_size (≥ 1; z. B. 1.2 = 20 % zusätzlich) |
selection_algorithm |
string |
Nein | "greedy" |
"greedy" oder "random_constrained" |
require_email |
boolean |
Nein | false |
Nur Befragte mit E-Mail-Adresse kommen infrage |
exclude_respondent_ids |
string[] |
Nein | [] |
UUIDs von Befragten, die für diese Ziehung nie infrage kommen (z. B. aus einer früheren Welle) |
Ungültige Einstellungen (eine Größe von 0, ein Oversampling unter 1, ein unbekannter Algorithmus, ein Ausschluss, der keine UUID einer befragten Person ist) werden abgelehnt, bevor überhaupt eine befragte Person gelesen wird.
Die Ziehung berücksichtigt nur die Befragten des Projekts, zu dem der neue Pool gehört. Ein Pool nimmt also nie Befragte auf, die die anderen Eigentümer des Projekts nicht sehen können. Das gilt ebenso, wenn der Pool aktualisiert wird, gleich wer ihn aktualisiert. In einer Organisation, die ihr Befragtenpanel teilt, und bei einem Pool ohne Projekt berücksichtigt die Ziehung das gesamte Panel.
Beispiel:
{ "strategy_id": "...", "pool_name": "Urban Millennials — main wave", "requested_size": 200, "oversample_factor": 1.2}Rückgabe:
{ "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 ist requested_size × oversample_factor (abgerundet), die Anzahl, die die Ziehung anstrebt. Kommen zu wenige Befragte infrage, erhält der Pool weniger Mitglieder, und warnings enthält eine Fehlmengenmeldung mit beiden Größen, zum Beispiel Could not fill the draw: 90 of 120 drawn (requested 100 x oversample 1.2); only 90 candidates eligible.
Der angelegte Pool hat source_type: "strategy" und speichert die source_strategy_id sowie die Ziehungseinstellungen für spätere Aktualisierungen. Um mit einer anderen Größe zu ziehen, erzeugen Sie einen weiteren Pool aus derselben Strategie.
preview_pool_generation
Abschnitt betitelt „preview_pool_generation“Zeigt eine Vorschau der Pool-Erzeugung, ohne den Pool anzulegen. Führt dieselbe Ziehung wie generate_pool_from_strategy aus und liefert Qualitätskennzahlen.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
strategy_id |
string |
Ja | — | UUID der Stichprobenstrategie |
project_id |
string |
Nein | — | Das Projekt, zu dem der Pool gehören würde, wie bei generate_pool_from_strategy. Standard ist das Projekt der Strategie |
max_preview |
integer |
Nein | 100 |
Höchstzahl an IDs von Befragten in der Vorschau |
Das Tool nimmt außerdem dieselben Ziehungseinstellungen wie generate_pool_from_strategy entgegen: requested_size (erforderlich), oversample_factor, selection_algorithm, require_email, exclude_respondent_ids.
Rückgabe:
{ "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
Abschnitt betitelt „refresh_pool_from_strategy“Zieht einen aus einer Strategie erzeugten Pool an Ort und Stelle aus dem aktuellen Bestand an Befragten neu. Funktioniert nur bei Pools mit source_type: "strategy". Die Aktualisierung nimmt keine Ziehungseinstellungen entgegen: Sie zieht mit der angeforderten Größe, dem Oversampling-Faktor, dem Algorithmus, der E-Mail-Pflicht und den Ausschlüssen neu, die der Pool bei seiner Erzeugung gespeichert hat, und zwar anhand der aktuellen Faktoren der Strategie. Um die Größe zu ändern, erzeugen Sie einen neuen Pool und weisen ihn der Kampagne zu.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
pool_id |
string |
Ja | — | UUID des Pools (muss aus einer Strategie erzeugt sein) |
Rückgabe:
{ "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
Abschnitt betitelt „delete_respondent_pool“Löscht einen Befragtenpool.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
pool_id |
string |
Ja | — | UUID des Pools |
Rückgabe: { pool_id, deleted }
Fehlerbehandlung
Abschnitt betitelt „Fehlerbehandlung“Häufige Fehler
Abschnitt betitelt „Häufige Fehler“| Situation | Antwort |
|---|---|
| Pool nicht gefunden | {"error": "Pool {id} not found"} |
| Strategie nicht gefunden oder in einem Projekt, das der Aufrufer nicht lesen darf (Erzeugen, Vorschau) | {"error": "Strategy {id} not found"} |
| Keine geeigneten Befragten | {"error": "No eligible respondents available for this strategy"} |
| Nicht aus einer Strategie erzeugt | {"error": "Pool was not generated from a strategy — cannot refresh"} |
| Quellstrategie gelöscht oder in einem Projekt, das der Aufrufer nicht lesen darf (Aktualisieren) | {"error": "Source strategy {id} not found"} |
| Strategie-Pool ohne festgehaltene Ziehung (Aktualisieren) | Konflikt: Der Pool hat keine Ziehungseinstellungen gespeichert und kann daher nicht aktualisiert werden. Erzeugen Sie stattdessen einen neuen Pool aus der Strategie in der gewünschten Größe und weisen Sie ihn der Kampagne zu. |
| Kein Eigentümer des Projekts des Pools | {"error": "forbidden", "detail": "caller is not an owner of this project and lacks an admin role"} |
Umgang mit Duplikaten
Abschnitt betitelt „Umgang mit Duplikaten“add_respondents_to_pool erkennt Duplikate über Mengenoperationen. Duplikate werden stillschweigend übersprungen und in der Anzahl duplicates_skipped gemeldet – es wird kein Fehler ausgelöst.
Nachverfolgung des Quelltyps
Abschnitt betitelt „Nachverfolgung des Quelltyps“| Quelltyp | Erzeugt durch | Aktualisierbar |
|---|---|---|
"manual" |
create_respondent_pool |
Nein |
"strategy" |
generate_pool_from_strategy |
Ja, mit den gespeicherten Ziehungseinstellungen des Pools |
Filterung nach Eignung
Abschnitt betitelt „Filterung nach Eignung“Jede Ziehung (Erzeugen, Vorschau, Aktualisieren) beginnt mit den Befragten, die Sie sehen können: dem gesamten Panel in einer privaten Organisation oder für eine Administratorin bzw. einen Administrator, sonst den Befragten der Projekte, deren Eigentümer Sie sind. Das gilt auch für die Standardstrategie der Organisation, sodass eine Ziehung nie eine befragte Person nennt, die list_respondents Ihnen nicht anzeigen würde.
Anschließend filtert sie diese vor der Auswahl anhand der Ziehungseinstellungen:
- Ist
require_emailgesetzt, werden Befragte ohne E-Mail-Adresse ausgeschlossen - Befragte in
exclude_respondent_idswerden ausgeschlossen - Bleiben keine geeigneten Befragten übrig, liefern Erzeugen und Aktualisieren einen Fehler (eine Aktualisierung leert nie einen Pool); die Vorschau meldet
eligible_count: 0
Ein Mitglied, das von Hand aus einem Pool entfernt wurde, wird nicht in exclude_respondent_ids aufgenommen, sodass die nächste Aktualisierung es erneut ziehen kann.