Umfrage-Tools – MCP-Tool-Referenz
Umfrage-Tools steuern den Ablauf der Durchführung: Umfragesitzungen anlegen, durch Fragebogenabläufe navigieren, Antworten übermitteln und synthetische Testdaten erzeugen. Comment-Elemente werden automatisch übersprungen – Aufrufer erhalten sie nie.
list_surveys
Abschnitt betitelt „list_surveys“Umfragen auflisten, optional gefiltert nach Fragebogen, Kampagne, befragter Person, Interviewer oder Status.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
questionnaire_id |
string |
Nein | — | Nach Fragebogen-ID filtern |
campaign_id |
string |
Nein | — | Nach Kampagnen-ID filtern |
respondent_id |
string |
Nein | — | Nach Befragten-ID filtern |
interviewer_user_id |
string |
Nein | — | Nach zugewiesenem Interviewer (Benutzer) filtern |
status |
string |
Nein | — | Filter: "pending", "in_progress" oder "completed" |
expand |
boolean |
Nein | false |
Verschachtelte Objekte für Fragebogen/Interviewer/befragte Person/Kampagne befüllen |
cursor |
string |
Nein | — | Paginierungs-Cursor einer vorherigen Seite |
limit |
integer |
Nein | 50 |
Seitengröße (max. 100) |
Rückgabe: { data: [...], next_cursor, has_more } – Cursor-paginiert. Jede Umfrage enthält status sowie einen abgeleiteten, schreibgeschützten Boolean completed (true genau dann, wenn status gleich "completed" ist); status ist die einzige maßgebliche Quelle, und in der gesamten Umfrage-Schnittstelle gibt es weder einen Filter noch eine Eingabe completed.
update_survey
Abschnitt betitelt „update_survey“Die veränderlichen Felder einer Umfrage ändern. Die gebundenen Entitäten (Fragebogen, befragte Person, Interviewer, Kampagne) sind hier unveränderlich – um sie neu zu binden, löschen Sie die Umfrage und legen sie neu an.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
survey_id |
string |
Ja | — | UUID der Umfrage |
status |
string |
Nein | — | Neuer Status; mit "completed" drücken Sie den Abschluss aus (eine separate Eingabe completed gibt es nicht) |
qml_state |
object |
Nein | — | Fortgeschritten: den Ablaufzustand der Umfrage ersetzen |
current_block_id |
string |
Nein | — | Fortgeschritten: den Ablaufzeiger neu setzen |
current_item_id |
string |
Nein | — | Fortgeschritten: den Ablaufzeiger neu setzen |
Rückgabe: das geänderte Umfrageobjekt (gleiche Form wie die Einträge von list_surveys, completed aus status abgeleitet).
create_survey
Abschnitt betitelt „create_survey“Eine neue Umfrage für eine befragte Person anlegen.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
questionnaire_id |
string |
Ja | — | Zu verwendender Fragebogen |
respondent_id |
string |
Ja | — | UUID der befragten Person |
interviewer_user_id |
string |
Nein | — | Für telefonische oder persönliche Interviews. Bei Selbstausfüllung weglassen |
campaign_id |
string |
Nein | — | Einer Kampagne zuordnen |
Rückgabe: { id, questionnaire_id, interviewer_user_id, respondent_id, campaign_id, mode }
mode wird abgeleitet, nie gesetzt: field_interview, wenn ein Interviewer gebunden ist, ai_assisted, sobald die befragte Person in ihrem KI-Assistenten eingewilligt hat, bevor sie eine Antwort gab, andernfalls direct. Jedes Umfrageobjekt dieser Schnittstelle enthält es. Siehe Umfragemodus.
Eine befragte Person hat pro Kampagne höchstens eine laufende Umfrage. Hat sie bereits eine, wird der Aufruf als Konflikt abgelehnt (REST 409), mit der ID dieser Umfrage: Setzen Sie sie fort oder löschen Sie sie zuerst.
bulk_create_surveys
Abschnitt betitelt „bulk_create_surveys“Umfragen für alle Befragten im zugewiesenen Pool einer Kampagne anlegen. Befragte, die bereits Umfragen haben, werden übersprungen.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
campaign_id |
string |
Ja | — | UUID der Kampagne |
Rückgabe:
{ "status": "success", "campaign_id": "...", "created_count": 45, "skipped_count": 5, "surveys": [{"id": "...", "respondent_id": "..."}]}Voraussetzung: Der Kampagne müssen sowohl ein Fragebogen als auch ein Befragtenpool zugewiesen sein.
get_survey_current_item
Abschnitt betitelt „get_survey_current_item“Die aktuelle Frage einer Umfrage abrufen. Beim ersten Aufruf wird der Umfragezustand initialisiert.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
survey_id |
string |
Ja | — | UUID der Umfrage |
Rückgabe (Frage): das aktuelle Element mit eingebetteten Antwortoptionen und dem Steuerelementtyp – ein einziger Roundtrip liefert alles, was zum Antworten nötig ist.
{ "survey_id": "...", "status": "in_progress", "item": { "id": "q_gender", "kind": "Question", "text": "What is your gender?" }, "control_type": "radio", "options": [ {"value": "male", "text": "Male"}, {"value": "female", "text": "Female"}, {"value": "other", "text": "Other"} ], "required": true}Bei einem Slider-Steuerelement enthält options einen einzigen Bereichsdeskriptor:
{"control_type": "slider", "options": [{"type": "range", "min": 18, "max": 99, "step": 1}]}Die Steuerelemente editbox, range und textarea liefern eine leere Liste options; lesen Sie ihre Grenzen oder Texteinstellungen aus dem input des Elements. Steuerelementtypen: radio, dropdown, checkbox, slider, switch, editbox, range, textarea.
Rückgabe (abgeschlossen): { survey_id, status: "completed", message: "..." }
submit_survey_response
Abschnitt betitelt „submit_survey_response“Eine Antwort auf die aktuelle Frage übermitteln und zum nächsten Element weitergehen.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
survey_id |
string |
Ja | — | UUID der Umfrage |
item_id |
string |
Ja | — | ID des beantworteten Elements |
outcome |
any |
Ja | — | Antwortwert (der Typ hängt vom Steuerelement ab; eine Range-Antwort ist ein Paar [low, high]) |
Rückgabe:
{ "survey_id": "...", "status": "in_progress", "output": { }, "next": { }}status ist "in_progress" oder "completed". next bettet den folgenden Schritt ein (gleiche Form wie bei get_survey_current_item), sodass Sie ihn nicht separat abrufen müssen – sobald die Umfrage abgeschlossen ist, ist es null. Nachfolgende Comment-Elemente werden nach jeder Übermittlung automatisch verarbeitet.
finish_survey
Abschnitt betitelt „finish_survey“Eine Umfrage ausdrücklich als abgeschlossen markieren. Für Sonderfälle, in denen der automatische Abschluss nicht greift.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
survey_id |
string |
Ja | — | UUID der Umfrage |
Rückgabe: { status: "success" | "already_complete", survey_id, message }.
mass_fill_surveys
Abschnitt betitelt „mass_fill_surveys“Einen asynchronen Hintergrund-Task einreihen, der alle ausstehenden Umfragen einer Kampagne mit synthetischen Testantworten füllt. Nicht für Kampagnen mit echten Befragtendaten verwenden.
Das Tool liefert sofort eine task_id; die Generierungsschleife läuft als Hintergrundjob auf Portors eigenem Worker. Fragen Sie get_task_status ab, bis der Task einen Endzustand erreicht: completed (jede Umfrage gefüllt), partial (einige Umfragen gefüllt, andere fehlgeschlagen – z. B. wegen fehlerhafter Befragtendaten oder eines vorübergehenden QML-Fehlers) oder failed (keine Umfrage gefüllt – entweder ein Validierungsfehler vor dem Lauf, etwa eine fehlende Kampagne, oder jede Umfrage des Laufs ist fehlgeschlagen; last_error erklärt den Grund). Die drei Zustände schließen einander aus: Jede Mischung aus Erfolgen und Fehlschlägen endet bei partial, nie bei failed.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
campaign_id |
string |
Ja | — | UUID der Kampagne |
distribution |
string |
Nein | "realistic" |
Strategie: "realistic", "random" oder "llm"; jeder andere Wert wird abgelehnt |
max_surveys |
integer |
Nein | — | Zahl der zu füllenden Umfragen begrenzen. null = alle ausstehenden |
profiles |
string[] |
Nein | ["random"] |
Persona-Profile, reihum zugewiesen |
concurrency |
integer |
Nein | 1 |
Größe des Thread-Pools je Task für die innere Schleife |
| Verteilung | Wie Antworten gewählt werden | Geeignet für |
|---|---|---|
realistic |
Gewichtet nach Demografie und Persona-Profil der befragten Person: Auswahlfragen mit profilabhängigen Gewichten, Slider mit einer Gauß-Verteilung, Texteingaben mit profilspezifischen Formulierungen | Pipeline-Tests mit hohem Volumen (schnell) |
random |
Gleichverteilt, ohne demografischen Einfluss | Belastungstests (am schnellsten) |
llm |
Ein Claude-Haiku-Aufruf pro Frage, mit der Persona, der Demografie der befragten Person und jeder früheren Antwort in der Umfrage, sodass eine Umfrage in sich stimmig bleibt. Etwa eine Sekunde pro Frage | Plausible offene Antworten; erfordert KI-Zugangsdaten in Ihrem Profil |
Profile: young_single, married_family, retired, high_income, random.
Rückgabe (synchron, nach der Validierung beim Einreihen):
{ "task_id": "f5b6c7d8-...", "status": "pending", "campaign_id": "...", "distribution": "realistic", "profiles": ["young_single", "retired"]}Fragen Sie get_task_status(task_id) ab, bis state den Wert completed, partial oder failed hat. status_text zeigt den laufenden Fortschritt (z. B. "47 of 200 surveys processed") und in einem Endzustand eine Zusammenfassung des Füllens (z. B. "47 of 200 surveys filled (3 failed)"); last_error enthält bei einem Fehlschlag einen bereinigten Grund. Um es nach einem partial-Ergebnis erneut zu versuchen, rufen Sie mass_fill_surveys noch einmal für dieselbe Kampagne auf – das Füllen verarbeitet nur Umfragen, die noch nicht abgeschlossen sind, bereits gefüllte werden also übersprungen.
Verteilungsmodi
Abschnitt betitelt „Verteilungsmodi“| Modus | Engine | Geschwindigkeit | Beschreibung |
|---|---|---|---|
realistic |
Gewichteter Zufall | Schnell | Profilbezogene demografische Gewichtung (Standard) |
random |
Gleichverteilter Zufall | Schnell | Reiner Zufall, ohne demografischen Einfluss |
llm |
Claude-Haiku-API | ~1 s/Frage | KI-generierte, zur Persona passende Antworten. Erfordert, dass Ihr Reasoning-Anbieter (oder der Ihrer Organisation) Anthropic API oder AWS Bedrock ist und dessen Zugangsdaten gespeichert sind |
Persona-Profile
Abschnitt betitelt „Persona-Profile“Reihum auf Befragte verteilt. Verfügbare Profile:
| Profil | Alter | Einkommen | Verhalten |
|---|---|---|---|
young_single |
25–35 | $65k | Progressiv, technikaffin, bevorzugt mittlere Optionen |
married_family |
30–50 | $80k | Pragmatisch, preisbewusst |
retired |
65+ | $55k | Konservativ, bevorzugt frühe/traditionelle Optionen |
high_income |
45 | $150k+ | Qualitätsorientiert, bevorzugt Premium-Optionen |
random |
40 | $70k | Keine besondere Tendenz |
Umgang mit Elementarten
Abschnitt betitelt „Umgang mit Elementarten“Antworten sind numerische Codes (die labels eines Auswahl-Steuerelements ordnen ganzzahligen Codes Anzeigetexte zu; übermittelt wird der Code) – Freitext nur beim Steuerelement textarea. Den vollständigen Vertrag finden Sie unter Darstellungsformat von Umfragen.
| Elementart | Format der Antwort | Beispiel |
|---|---|---|
Comment |
null (automatisch übersprungen) |
Informationstext |
Question |
Eine einzelne Zahl: Antwortcode / numerischer Wert / Switch 1-0 (Checkbox: Bitmasken-Integer; Textarea: String) |
2, 42, true |
QuestionGroup |
Liste von Zahlen, eine je Unterfrage – alle aus dem einen gemeinsamen Steuerelement der Gruppe | [1, 3, 2] |
MatrixQuestion |
Verschachtelte Liste von Zahlen, Zeilen × Spalten – ein gemeinsames Steuerelement | [[1, 2], [3, 1]] |
bulk_delete_surveys
Abschnitt betitelt „bulk_delete_surveys“Mehrere Umfragen nach Filterkriterien löschen. Verwendet einen zweistufigen Ablauf: Rufen Sie zuerst mit dry_run=true auf, um zu sehen, was gelöscht würde, und dann erneut mit dry_run=false, um es auszuführen.
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
campaign_id |
string |
Ja | — | Umfragen in dieser Kampagne löschen |
status |
string |
Nein | — | Nur Umfragen mit diesem Status betreffen: "pending", "in_progress" oder "completed" |
dry_run |
boolean |
Nein | true |
Vorschaumodus – liefert Anzahl und Stichprobe, ohne zu löschen |
Rückgabe des Probelaufs:
{ "dry_run": true, "count": 25, "sample": [{"id": "...", "respondent_id": "...", "status": "pending", "campaign_id": "..."}], "message": "Would delete 25 surveys. Call again with dry_run=False to execute."}Rückgabe bei Ausführung: { dry_run: false, deleted: 25 }
Fehlerbehandlung
Abschnitt betitelt „Fehlerbehandlung“Häufige Fehler
Abschnitt betitelt „Häufige Fehler“| Situation | Antwort |
|---|---|
| Umfrage nicht gefunden | {"error": "Survey {id} not found"} |
| Kampagne nicht gefunden | {"error": "Campaign {id} not found"} |
| Fragebogen nicht gefunden | {"error": "Questionnaire {id} not found"} |
| Umfrage nicht initialisiert | {"error": "Survey not initialized. Call get_survey_current_item first."} |
| Kein Pool zugewiesen | {"error": "Campaign has no respondent pool assigned"} |
| Keine unvollständigen Umfragen | {"status": "no_surveys", "message": "No incomplete surveys found in campaign"} |
Zustandsautomat der Umfrage
Abschnitt betitelt „Zustandsautomat der Umfrage“[Not Started] → get_survey_current_item → [In Progress][In Progress] → submit_survey_response → [In Progress | Completed][In Progress] → finish_survey → [Completed]- Initialisierung: Der erste Aufruf von
get_survey_current_itemlädt das QML und legt den Umfragezustand an - Automatischer Abschluss: Umfragen werden automatisch abgeschlossen, sobald das letzte Element beantwortet ist
- Überspringen von Comments: Comment-Elemente werden unbemerkt verarbeitet (bis zu 50 aufeinanderfolgende) – Aufrufer erhalten sie nie
- Persistenz: Jede Antwort wird sofort in der Datenbank gespeichert