Kampagnen-Tools – MCP-Tool-Referenz
Kampagnen-Tools verwalten den Lebenszyklus von Umfragekampagnen: Kampagnen anlegen, Interviewer und Befragtenpools zuweisen, die Arbeitslast verteilen und Einladungen versenden. Viele Operationen verwenden ein Batch-Antwortmuster mit den Feldern added/skipped/reasons.
list_campaigns
Abschnitt betitelt „list_campaigns“Alle Kampagnen auflisten, optional gefiltert nach Projekt, Name oder Status.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
project_id |
string |
Nein | — | Nach Projekt-ID filtern |
name |
string |
Nein | — | Nach Kampagnenname filtern |
status |
string |
Nein | — | Nach Status filtern |
limit |
integer |
Nein | 100 |
Höchstzahl der zurückgegebenen Ergebnisse |
Rückgabe: { items: [...], count, limit }
get_campaign
Abschnitt betitelt „get_campaign“Eine Kampagne über ihre ID abrufen.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
campaign_id |
string |
Ja | — | UUID der Kampagne |
Rückgabe: Kampagnenobjekt oder { error }. Es enthält offered_languages: die Sprachen, die Befragte wählen können – zuerst die Quellsprache des Fragebogens, dann jede vollständige Übersetzung der gepinnten Version, jeweils als { locale, name, human_edited }. Eine Kampagne ohne gepinnte Version bietet nur die Quellsprache an.
create_campaign
Abschnitt betitelt „create_campaign“Eine neue Kampagne anlegen. Der Kampagnenmodus ergibt sich automatisch daraus, ob Interviewer zugewiesen sind.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
name |
string |
Ja | — | Anzeigename der Kampagne |
project_id |
string |
Ja | — | ID des übergeordneten Projekts |
questionnaire_id |
string |
Ja | — | Zu verwendender Fragebogen |
status |
string |
Nein | "draft" |
Anfangsstatus: draft, active oder scheduled. Alles andere wird abgelehnt |
admits_volunteers |
boolean |
Ja | — | Ob Personen teilnehmen dürfen, die nie in den Pool der Kampagne gezogen wurden (spontan Teilnehmende, der offene Link). Kein Standardwert: Geben Sie ihn an. |
offers_ai_channel |
boolean |
Ja | — | Ob Befragte die Umfrage auch in ihrem eigenen KI-Assistenten beantworten dürfen. Kein Standardwert: Geben Sie ihn an. |
intro_text |
string |
Wenn offers_ai_channel true ist |
— | Wer die Daten erhebt und warum; wird vor der ersten Frage wortwörtlich angezeigt |
consent_text |
string |
Wenn offers_ai_channel true ist |
— | Worin die befragte Person einwilligt; wird wortwörtlich angezeigt, gefolgt von einem festen Absatz über den KI-Anbieter, der immer angehängt wird |
Rückgabe: das angelegte Kampagnenobjekt.
update_campaign ändert status nur entlang des Lebenszyklus der Kampagne: draft → active oder scheduled; scheduled → active oder draft; active → paused, completed oder aborted; paused → active, completed oder aborted; completed oder aborted → draft. Jeder andere Übergang oder ein unbekannter Status wird abgelehnt, und nichts wird geändert.
update_campaign akzeptiert außerdem offers_ai_channel, intro_text und consent_text, jeweils optional; fehlt ein Wert, bleibt der gespeicherte erhalten. Geprüft werden die Texte am Endzustand: Wer den Assistenten für eine Kampagne einschaltet, die bereits beide Texte enthält, muss sie nicht erneut angeben, und einen Text zu leeren, während der Assistent angeboten wird, wird abgelehnt. Schalten Sie den Assistenten aus, verfallen alle noch nicht verwendeten Kopplungscodes; bereits verbundene Befragte können ihre Umfrage noch abschließen.
add_interviewers_to_campaign
Abschnitt betitelt „add_interviewers_to_campaign“Einer Kampagne Interviewer (Benutzer mit Interviewer-Rolle) hinzufügen. Verwendet das Batch-Antwortmuster.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
campaign_id |
string |
Ja | — | UUID der Kampagne |
user_ids |
string[] |
Ja | — | Liste der Benutzer-IDs, die als Interviewer hinzugefügt werden |
Rückgabe:
{ "campaign_id": "...", "added": ["uid1"], "already_present": ["uid2"], "skipped": [{"id": "uid3", "reason": "User not found"}], "total_added": 1}Gründe für das Überspringen: "User not found", "No interviewer role".
remove_interviewers_from_campaign
Abschnitt betitelt „remove_interviewers_from_campaign“Interviewer aus einer Kampagne entfernen.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
campaign_id |
string |
Ja | — | UUID der Kampagne |
user_ids |
string[] |
Ja | — | Liste der zu entfernenden Benutzer-IDs |
Rückgabe:
{ "campaign_id": "...", "removed": ["uid1"], "not_found": ["uid2"], "total_removed": 1}update_campaign_questionnaire
Abschnitt betitelt „update_campaign_questionnaire“Den einer Kampagne zugewiesenen Fragebogen ändern.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
campaign_id |
string |
Ja | — | UUID der Kampagne |
questionnaire_id |
string |
Ja | — | UUID des neuen Fragebogens |
Rückgabe:
{ "campaign_id": "...", "old_questionnaire_id": "...", "new_questionnaire_id": "...", "success": true, "warning": "Campaign has existing surveys — they reference the old questionnaire"}assign_respondents_to_interviewer
Abschnitt betitelt „assign_respondents_to_interviewer“Bestimmte Befragte innerhalb einer Kampagne einem bestimmten Interviewer zuweisen, um die Arbeitslast zu verteilen.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
campaign_id |
string |
Ja | — | UUID der Kampagne |
interviewer_id |
string |
Ja | — | Benutzer-UUID des Interviewers |
respondent_ids |
string[] |
Ja | — | Liste der zuzuweisenden Befragten-IDs |
Rückgabe:
{ "assigned": ["r1"], "already_assigned": ["r2"], "not_in_campaign": ["r3"]}unassign_respondents_from_interviewer
Abschnitt betitelt „unassign_respondents_from_interviewer“Befragte aus der Zuweisung eines Interviewers entfernen. Die Befragten bleiben im Pool der Kampagne, sind aber nicht mehr zugewiesen.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
campaign_id |
string |
Ja | — | UUID der Kampagne |
interviewer_id |
string |
Ja | — | Benutzer-UUID des Interviewers |
respondent_ids |
string[] |
Ja | — | Liste der Befragten-IDs, deren Zuweisung aufgehoben wird |
Rückgabe:
{ "unassigned": ["r1"], "not_assigned": ["r2"]}get_interviewer_workload
Abschnitt betitelt „get_interviewer_workload“Die Arbeitslast eines bestimmten Interviewers in einer Kampagne abrufen – zugewiesene Befragte und den Abschlussstand ihrer Umfragen.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
campaign_id |
string |
Ja | — | UUID der Kampagne |
interviewer_id |
string |
Ja | — | Benutzer-UUID des Interviewers |
Rückgabe:
{ "campaign_id": "...", "interviewer_id": "...", "assigned_respondents": [ {"id": "...", "name": "...", "email": "...", "age": 35, "gender": "female", "location": "Berlin"} ], "survey_status": { "respondent_id": {"survey_id": "...", "status": "completed", "completed": true} }, "statistics": { "total_assigned": 10, "completed": 3, "in_progress": 2, "not_started": 5, "completion_rate": 0.3 }}get_unassigned_respondents
Abschnitt betitelt „get_unassigned_respondents“Befragte einer Kampagne abrufen, die noch keinem Interviewer zugewiesen sind.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
campaign_id |
string |
Ja | — | UUID der Kampagne |
Rückgabe:
{ "campaign_id": "...", "unassigned_count": 5, "unassigned_respondents": [ {"id": "...", "name": "...", "email": "...", "age": 28, "gender": "male", "location": "Munich"} ]}assign_pool_to_campaign
Abschnitt betitelt „assign_pool_to_campaign“Einer Kampagne einen Befragtenpool zuweisen. Verknüpft den Pool, sodass bulk_create_surveys Umfragen für alle Befragten im Pool anlegen kann.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
campaign_id |
string |
Ja | — | UUID der Kampagne |
pool_id |
string |
Ja | — | UUID des Befragtenpools |
Rückgabe:
{ "campaign_id": "...", "pool_id": "...", "pool_name": "Urban Millennials", "respondent_count": 200, "previous_pool_id": null}get_campaign_pool
Abschnitt betitelt „get_campaign_pool“Den einer Kampagne zugewiesenen Befragtenpool abrufen.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
campaign_id |
string |
Ja | — | UUID der Kampagne |
Rückgabe (Pool zugewiesen):
{ "campaign_id": "...", "pool_id": "...", "pool_name": "...", "pool_description": "...", "respondent_count": 200, "respondent_ids": ["..."], "source_type": "strategy", "source_strategy_id": "...", "quality_score": 0.95, "has_pool": true}Rückgabe (kein Pool): { campaign_id, pool_id: null, has_pool: false, message: "..." }
send_campaign_invitations
Abschnitt betitelt „send_campaign_invitations“Umfrage-Einladungen per E-Mail an die Befragten einer Kampagne senden. Versendet echte E-Mails mit Zugang per Magic Link.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
campaign_id |
string |
Ja | — | UUID der Kampagne |
respondent_ids |
string[] |
Nein | — | Bestimmte Befragte, die eingeladen werden |
send_to_all_uninvited |
boolean |
Nein | false |
An alle noch nicht eingeladenen Befragten senden |
Jede Einladung ist in der Sprache ihres Empfängers verfasst: in der bevorzugten Sprache der befragten Person, wenn die Kampagne darin eine vollständige Übersetzung anbietet, andernfalls in der Quellsprache des Fragebogens.
Rückgabe:
{ "campaign_id": "...", "results": { "sent": [{"respondent_id": "...", "name": "...", "email": "...", "survey_id": "...", "survey_url": "..."}], "skipped": [{"respondent_id": "...", "name": "...", "reason": "No email address"}], "failed": [{"respondent_id": "...", "name": "...", "reason": "Email send failed: ..."}] }, "summary": {"sent": 8, "skipped": 1, "failed": 1}}Bietet die Kampagne den KI-Assistenten an, enthält jede Einladungs-E-Mail einen zusätzlichen Absatz, der die befragte Person auf die KI-Option auf ihrer Umfrageseite hinweist, und jeder Eintrag in sent trägt außerdem connector_url, die Connector-Adresse für Befragte.
Voraussetzungen je befragter Person:
- Sie muss eine E-Mail-Adresse haben
notification_preferencedarf nicht"none"sein- Die Umfrage darf nicht bereits abgeschlossen oder in Bearbeitung sein
- Die Kampagne muss sie zulassen. Jemanden einzuladen, der nie in ihren Pool gezogen wurde, erfordert eine Kampagne, die Freiwillige zulässt und sich aktiv in der Feldphase befindet – dieselbe Schranke, die auch spontan Teilnehmende passieren. Ihre Umfrage wird dann als Freiwillige erfasst, nicht als gezogener Fall, sodass der Datensatz beides weiterhin unterscheiden kann.
Gründe für das Überspringen: "Respondent not found", "No email address", "Opted out of notifications", "Survey already completed", "Survey already in_progress" sowie eine Ablehnung, die nennt, an welcher Hälfte der Zulassungsprüfung es scheiterte – die Kampagne nimmt keine spontan Teilnehmenden an, oder sie befindet sich derzeit nicht in der Feldphase.
Ketten-Tools
Abschnitt betitelt „Ketten-Tools“Zwei der oben beschriebenen Abfolgen gibt es auch als einzelnen Aufruf. Sie sind keine Abkürzungen, die etwas auslassen: Jeder Schritt ist dasselbe auf dieser Seite dokumentierte Tool; es werden also dieselben Datensätze geschrieben, dieselben Audit-Ereignisse erfasst, und jede Ablehnung, die ein einzelnes Tool liefern würde, erhalten Sie hier unverändert – plus stopped_at_step, das nennt, aus welchem Schritt ein Abbruch kam. Nichts wird rückgängig gemacht; eine Kette, die mittendrin abbricht, hinterlässt also, was die früheren Schritte aufgebaut haben, und Sie machen mit den einzelnen Tools weiter.
Eine Kette prüft Ihre Berechtigung für jeden Schritt, bevor sie irgendetwas aufbaut. Deckt Ihr Abonnement einen späteren Schritt nicht ab, wird der Aufruf vorab abgelehnt, statt Ihnen eine halb aufgebaute Feldphase zu hinterlassen.
prepare_campaign_fielding
Abschnitt betitelt „prepare_campaign_fielding“Die gesamte Feldvorbereitungskette einer Kampagne ausführen: die Stichprobenstrategie anlegen, den Befragtenpool erzeugen, den Pool der Kampagne zuweisen, die Fragebogenversion veröffentlichen (und pinnen), mit der die Kampagne ins Feld geht, und die Umfragen anlegen.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
campaign_id |
string |
Ja | — | Vorzubereitende Kampagne. Sie muss bereits den Fragebogen nennen, mit dem Sie ins Feld gehen wollen |
admits_volunteers |
boolean |
Ja | keiner | Die Regel dieser Feldphase zur Zulassung von Freiwilligen, ausdrücklich angegeben. Es gibt keinen Standardwert, und sie muss mit der Einstellung der Kampagne übereinstimmen – ändern Sie diese zuerst mit update_campaign, falls sie falsch ist |
strategy_name |
string |
Ja | — | Name der Stichprobenstrategie, die dieser Lauf anlegt |
target_size |
integer |
Ja | — | Gewünschte Größe der Poolziehung: Zahl der zu ziehenden Befragten vor dem Oversampling (> 0). Wird als requested_size an die Ziehung übergeben und im Pool gespeichert |
factors |
object[] |
Nein | [] |
Demografische Verteilungsfaktoren, an denen die Strategie misst |
selection_algorithm |
string |
Nein | "greedy" |
Auswahlalgorithmus für die Poolziehung ("greedy" oder "random_constrained") |
oversample_factor |
number |
Nein | 1.0 |
Oversampling-Multiplikator für die Poolziehung (≥ 1) |
quality_metric |
string |
Nein | "rmse" |
Kennzahl, mit der die Strategie die Übereinstimmung bewertet: "rmse", "mae", "chi_square" oder "max_deviation". Jeder andere Wert wird abgelehnt, bevor etwas aufgebaut wird |
require_email |
boolean |
Nein | false |
Die Poolziehung lässt nur Befragte mit E-Mail-Adresse zu |
pool_name |
string |
Nein | — | Name des erzeugten Pools; standardmäßig eine aus der Strategie abgeleitete Bezeichnung |
Die Strategie, die dieser Lauf anlegt, enthält nur factors und quality_metric. Die Ziehungseinstellungen (target_size, oversample_factor, selection_algorithm, require_email) gehen an den Pool-Schritt und werden im Pool gespeichert, genau wie bei einem direkten Aufruf von generate_pool_from_strategy.
Rückgabe: ready_to_invite, die strategy_id, pool_id, pool_respondent_count, qml_version_id, die offered_languages, die Befragte für diese Version wählen können (wie bei get_campaign), und die erzeugten surveys_created / surveys_skipped, dazu next_step. Bei einem Abbruch: stopped_at_step mit error und detail des ablehnenden Schritts sowie alles, was frühere Schritte bereits aufgebaut hatten.
Warum der Veröffentlichungsschritt wichtig ist. Eine von Hand gebaute Kette vergisst häufig das Veröffentlichen, und eine Kampagne ohne gepinnte Version verwendet bei jedem Lesen den jeweils neuesten Stand des Fragebogens – eine Änderung mitten in der Feldphase verändert dann stillschweigend das Instrument für Befragte, die bereits geantwortet haben.
Ein erneuter Lauf zieht erneut. Jeder Lauf legt eine neue Strategie und einen neuen Pool an und bindet die Kampagne neu daran (ein Pool ist nur einmal verwendbar), legt dann für den neuen Pool Umfragen an und überspringt Befragte, die für diese Kampagne bereits eine Umfrage haben. Bei einem Befragtenbestand, der größer als target_size ist, ergänzt ein zweiter Lauf daher neu gezogene Befragte, statt jemanden zu ersetzen.
simulate_campaign_responses
Abschnitt betitelt „simulate_campaign_responses“Die Umfragen der Kampagne anlegen und anschließend synthetische Antworten darüber erzeugen. Was die einzelnen Verteilungsmodi und Persona-Profile bewirken, steht unter mass_fill_surveys.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
campaign_id |
string |
Ja | — | Kampagne, deren Umfragen angelegt und dann gefüllt werden |
distribution |
string |
Nein | "realistic" |
"realistic", "random" oder "llm" |
max_surveys |
integer |
Nein | — | Obergrenze, wie viele Umfragen der Kampagne gefüllt werden |
profiles |
string[] |
Nein | ["random"] |
Persona-Namen, die reihum auf Befragte verteilt werden |
concurrency |
integer |
Nein | 1 |
Parallelität der inneren Schleife beim Füllen |
Rückgabe: surveys_created / surveys_skipped und eine task_id für das Füllen mit status: "pending". Fragen Sie sie mit get_task_status ab, genau wie einen mass_fill_surveys-Lauf. Bei einem Abbruch: stopped_at_step mit error und detail des ablehnenden Schritts sowie task_id: null.
Fehlerbehandlung
Abschnitt betitelt „Fehlerbehandlung“Häufige Fehler
Abschnitt betitelt „Häufige Fehler“| Situation | Antwort |
|---|---|
| Kampagne nicht gefunden | {"error": "Campaign {id} not found"} |
| Interviewer nicht in der Kampagne | {"error": "Interviewer {id} is not assigned to this campaign"} |
| Kein Fragebogen/Pool | {"error": "Campaign has no questionnaire assigned"} |
Muster für Batch-Operationen
Abschnitt betitelt „Muster für Batch-Operationen“Die meisten Kampagnen-Tools, die Listen von IDs annehmen, liefern strukturierte Ergebnisse, statt an einzelnen Einträgen zu scheitern:
{ "added": ["id1"], "already_present": ["id2"], "skipped": [{"id": "id3", "reason": "User not found"}], "total_added": 1}Dieses Muster gilt für: add_interviewers_to_campaign, remove_interviewers_from_campaign, assign_respondents_to_interviewer, unassign_respondents_from_interviewer und send_campaign_invitations.
Jeder übersprungene oder fehlgeschlagene Eintrag enthält ein Feld reason, das erklärt, warum er von der Operation ausgeschlossen wurde.