MCP-Schnittstelle
Askalot unterstützt das Model Context Protocol (MCP), einen offenen Standard, über den KI-Assistenten direkt mit der Plattform arbeiten können. So können KI-Agenten im natürlichsprachigen Gespräch Umfragen anlegen, Kampagnen verwalten, Fragebogenabläufe durchlaufen und Ergebnisse analysieren.
Was ist MCP?
Abschnitt betitelt „Was ist MCP?“MCP ist ein standardisiertes Protokoll, mit dem KI-Systeme wie Claude externe Werkzeuge und Datenquellen nutzen. Mit der MCP-Schnittstelle von Askalot können Sie:
- Umfrage-Workflows automatisieren – Projekte, Fragebögen und Kampagnen im Gespräch mit der KI anlegen
- Umfragen programmatisch durchführen – durch Fragebogenabläufe navigieren und Antworten übermitteln
- Befragte verwalten – Befragte importieren, ordnen und Kampagnen zuweisen
- Den Audit-Trail abfragen – Änderungen nachverfolgen und Compliance sicherstellen
- Auf die Dokumentation zugreifen – KI-Agenten können die Plattformdokumentation als Kontext lesen
Verbindung zur MCP-Schnittstelle
Abschnitt betitelt „Verbindung zur MCP-Schnittstelle“Endpunkt
Abschnitt betitelt „Endpunkt“https://portor.<tenant>.askalot.io/mcpErsetzen Sie <tenant> durch den Tenant-Namen Ihrer Organisation.
Dieser Connector ist für Sie und Ihr Team bestimmt. Befragte verbinden sich nie mit diesem Connector: Eine Kampagne, die den KI-Assistenten anbietet, gibt jeder befragten Person einen eigenen Connector, https://portor.<tenant>.askalot.io/respond/mcp, den sie mit einem Kopplungscode von ihrer Umfrageseite erreicht. Er enthält nur ihre eigene Umfrage. Siehe KI-gestütztes Selbstinterview.
Authentifizierung
Abschnitt betitelt „Authentifizierung“Die MCP-Schnittstelle authentifiziert über OAuth 2.1, nicht über ein eingefügtes API-Token. Beim ersten Tool-Aufruf antwortet Portor mit 401 und einem OAuth-Discovery-Hinweis, und Ihr MCP-Client (zum Beispiel das Askalot-Plugin für Claude Code) führt Sie durch eine Anmeldung im Browser beim OIDC-Anbieter der Plattform. Anschließend speichert der Client die erhaltenen Access- und Refresh-Tokens und sendet das Access-Token bei jedem Aufruf als Authorization: Bearer – den Bearer-Wert selbst bekommen Sie nie zu sehen.
Endpunkt konfigurieren (nur die URL):
Konfigurieren müssen Sie nur die Server-URL. Das Askalot-Plugin liest sie aus der Umgebungsvariablen ASKALOT_MCP_URL; ein einfacher Eintrag in .mcp.json enthält dieselbe URL und sonst nichts – kein Token-Feld:
{ "mcpServers": { "askalot": { "type": "http", "url": "https://portor.<tenant>.askalot.io/mcp" } }}Anmelden (bei der ersten Nutzung):
- Richten Sie den Client auf Ihren Tenant aus (
export ASKALOT_MCP_URL=https://portor.<tenant>.askalot.io/mcp). - Rufen Sie ein beliebiges MCP-Tool auf. Der Client öffnet in Ihrem Browser den
/authorize-Endpunkt von Portor, der zur OIDC-Anmeldung der Plattform weiterleitet. - Melden Sie sich an. Über dem Formular nennt die Anmeldeseite die anfragende Anwendung und die Adresse, an die Ihr Zugang gesendet wird; fahren Sie nur fort, wenn Sie diese Verbindung aus genau dieser Anwendung gestartet haben. Der Client tauscht den Code gegen Tokens und wiederholt den ursprünglichen Aufruf.
- Der Browser-Handshake findet nur einmal statt; danach wird das Refresh-Token unbemerkt eingelöst.
Ihre aktive Organisation
Abschnitt betitelt „Ihre aktive Organisation“Ihre MCP-Sitzung befindet sich immer in genau einer Organisation – ihrer aktiven Organisation –, und jeder Tool-Aufruf wird in ihr aufgelöst. Projekte, Fragebögen, Kampagnen, Befragte und Datensätze gehören alle zu einer Organisation; deshalb ist die aktive Organisation das Wichtigste, was Sie wissen müssen, um zu verstehen, wo ein Tool sucht.
Wo Sie beginnen. Eine neue Sitzung startet in Ihrer Heimatorganisation, der Organisation, zu der Ihr Konto gehört. Bei der Anmeldung müssen Sie nichts auswählen.
Wo Sie gerade sind. list_organizations liefert jede Organisation, in der die Sitzung handeln darf, markiert die aktive und kennzeichnet versiegelte. Die Liste entspricht genau dem, was Ihnen das Menü Organisation wechseln im Browser anbietet – gehören Sie nur einer Organisation an, ist das die ganze Liste, und es gibt nichts zu verwalten.
Wechseln. switch_organization verschiebt die Sitzung in eine andere Organisation aus dieser Liste. Jeder spätere Aufruf wird in der neuen aufgelöst, und der Wechsel bleibt bestehen: Starten Sie Ihren MCP-Client neu, machen Sie dort weiter, wo Sie aufgehört haben. Der Tenant wird bei der Anmeldung festgelegt und ändert sich nie; ein Wechsel bewegt Sie also immer nur zwischen Organisationen innerhalb eines Tenants.
Eintreten dürfen und handeln dürfen. Die Liste enthält die Organisationen, in denen Sie Mitglied sind – Mitgliedschaften, die ein Administrator vergibt und entzieht, niemals die Sitzung selbst (für einen Askalot-Operator ist das jede Organisation im Tenant). Die Mitgliedschaft lässt die Sitzung eintreten; welche Tools sie dort nutzen kann, ergibt sich aus Ihren Rollen in dieser Organisation, und eine Rolle, die Sie anderswo haben, gilt dort nicht. In einer Organisation, in der Sie Mitglied sind, aber keine Rolle haben, schrumpft die Tool-Liste auf die Sitzungs-Tools – list_organizations, switch_organization, list_toolsets, get_my_entitlements und Ihre Modelleinstellungen –, bis ein Administrator Ihnen dort eine Rolle gibt; so können Sie jederzeit wieder herauswechseln. Entfernt ein Administrator Sie aus der Organisation, in der sich die Sitzung befindet, endet die Verbindung; melden Sie sich erneut an, startet die neue Sitzung in Ihrer Heimatorganisation.
Versiegelte Organisationen
Abschnitt betitelt „Versiegelte Organisationen“Manche Organisationen sind versiegelt – eine kuratierte Demo oder die Daten eines ehemaligen Kunden, die für ihre Aufbewahrungsfrist verfügbar bleiben. list_organizations kennzeichnet sie, sodass Sie es vor dem Handeln wissen.
Versiegelt ist der Forschungsbestand dieser Organisation – ihre Projekte, Fragebögen, Kampagnen, Befragten, Pools, Umfragen, Datensätze und Forschungsberichte. Das Lesen bleibt unberührt: Auflisten und Abrufen all dieser Daten funktioniert weiter, ebenso die Dokumentations- und Methodikbibliothek-Tools. Für die Audit-Tools gelten ihre üblichen Regeln (siehe Audit & Compliance). Anlegen, Ändern und Löschen wird mit org_sealed abgelehnt. Jedes Tool erklärt, ob es liest oder schreibt, und genau diese Erklärung steuert die Ablehnung – die Grenze ist also eine Eigenschaft des Tools, keine Vermutung anhand seines Namens.
Ein Instrument ausprobieren funktioniert weiterhin, weil eine Vorschau nichts am Bestand ändert. create_survey ohne Kampagne startet eine Vorschau statt einer Umfrage, und get_survey_current_item, submit_survey_response und finish_survey durchlaufen sie Schritt für Schritt – so können Sie einen Fragebogen in einer versiegelten Organisation von Anfang bis Ende prüfen. Geben Sie create_survey eine Kampagne mit, wird der Aufruf abgelehnt: Dieser Durchlauf wäre ein echter Fall, und echte Fälle gehen in den Datensatz ein.
list_organizations und switch_organization funktionieren dort beide weiter, sodass eine Sitzung immer sehen kann, wohin sie sonst gehen darf, und die Organisation verlassen kann.
Die Versiegelung deaktiviert außerdem API-Tokens für diese Organisation: Sie können keines erzeugen, und ein vorhandenes funktioniert nicht mehr. Die oben beschriebene OAuth-Anmeldung ist davon nicht betroffen.
Ihre KI-Modelleinstellungen
Abschnitt betitelt „Ihre KI-Modelleinstellungen“Askalot führt in Ihrem Auftrag drei Arten von KI-Aufrufen aus, und jede wählt Anbieter
und Modell separat: Embedding (fest auf das lokale Modell der Plattform eingestellt –
Indexierung und Suche müssen dasselbe verwenden, daher ist es nicht konfigurierbar),
Direct LLM (eine einzelne, direkte Completion: Schlüsselwortextraktion bei einer
Dokumentsuche und der Extraktionsdurchlauf beim Einlesen eines Dokuments) und
Reasoning, das die Agenten ausführt und eine Stufe high / medium / low hat.
get_model_configuration meldet, was für Ihr eigenes Konto gilt, und
je Slot, woher der Wert stammt:
| Quelle | Bedeutung |
|---|---|
user |
Sie haben ihn gewählt |
org |
von Ihrer Organisation übernommen |
platform |
Standard von Askalot (nur der Embedding-Slot) |
mixed |
Anbieter und Modell stammen aus unterschiedlichen Quellen |
unconfigured |
nichts ist eingestellt, und es gibt keinen Plattformstandard |
Der Direct-LLM-Slot und jede Reasoning-Stufe stehen auf unconfigured, bis Sie oder
Ihre Organisation einen Anbieter wählen – und das klärt ein häufiges Missverständnis:
Diese Slots haben absichtlich keinen Plattformstandard, weil die Aufrufe über Ihr
eigenes Anbieterkonto abgerechnet werden. Eine Dokumentsuche oder ein Einlesen, das mit
„requires an LLM provider — none is configured“ abgelehnt wird, oder ein Agent, der Sie
bittet, einen Anbieter einzurichten, zeigt genau diesen Zustand, keinen defekten Schlüssel.
Eine nicht konfigurierte Reasoning-Stufe steht in effective_config auf null.
update_model_configuration ändert Ihre eigenen Slots. Es führt zusammen: Nennen Sie
direct_llm, bleiben Ihre Reasoning-Stufen, wie sie waren; nennen Sie
reasoning: {"high": …}, bleiben medium und low unberührt. Übergeben Sie null für
eine Stufe – oder clear_direct_llm: true –, um einen Slot wieder an den Wert Ihrer
Organisation zurückzugeben. Die drei Reasoning-Stufen müssen am Ende denselben Anbieter
verwenden, und eine nicht gesetzte Stufe zählt als Abweichung; ein erster Schreibvorgang
nennt daher alle drei: Nur high zu setzen wird abgelehnt, weil medium und low
ungesetzt blieben. Aus demselben Grund müssen Sie, um Reasoning zu leeren, wenn Ihre
Organisation nichts festlegt, null für alle drei Stufen gleichzeitig übergeben.
direct_llm und reasoning akzeptieren jeweils anthropic_api oder bedrock. Fragen Sie
get_model_configuration nach den zulässigen Werten
und dem Standardmodell je Anbieter, statt zu raten; ein abgelehnter Schreibvorgang ändert
nichts und nennt, was falsch war.
Immer das neueste Modell verwenden
Abschnitt betitelt „Immer das neueste Modell verwenden“Der Direct-LLM-Slot und die Reasoning-Stufen bilden jeweils einen Bereich mit dem Kontrollkästchen Immer das neueste Modell verwenden, das aktiviert ist, sofern Sie es nicht ausgeschaltet haben. Solange es aktiv ist, hält Askalot die Slots des Bereichs auf dem neuesten Sonnet (Direct LLM) bzw. Opus / Sonnet / Haiku (high / medium / low) und wechselt erst, nachdem ein Testaufruf mit den Zugangsdaten dieses Slots erfolgreich war; wie das funktioniert, steht unter KI-Funktionen & Modelloptionen. Über die Tools:
get_model_configurationliefertauto_latest(je Bereich,direct_llmundreasoning: ob das Kontrollkästchen aktiv ist) undauto_status(je Slot: wann zuletzt geprüft wurde, das Ergebnis und das letzte Modell, dessen Testaufruf fehlschlug). Mögliche Ergebnisse sindok,no_newer_model,pending_verification,no_credential,catalog_unreadable,session_expiredoder der Ablehnungsgrund des Testaufrufs selbst.- Wenn Sie in
update_model_configurationfür einen Slot eines Bereichs einemodel_idnennen, ist das eine manuelle Wahl: Das Kontrollkästchen dieses Bereichs wird im selben Schreibvorgang deaktiviert, der andere Bereich bleibt unberührt. Nennen Sie für einen Bereich mit aktivem Kontrollkästchen nur einen Anbieter (direct_llm={"provider": "bedrock"}oder jede Reasoning-Stufe als{"provider": …}), werden seine Slots mit dem neuesten Modell der jeweiligen Modellfamilie belegt, das der Anbieter bereitstellt; das Kontrollkästchen bleibt aktiv, und die Slots werden für den Test bei der nächsten Prüfung vorgemerkt. Die Antwort enthält das resultierendeauto_latest. - Das Tool aktiviert ein Kontrollkästchen nie wieder; das geschieht auf der Profilseite.
Beide Tools wirken nur auf Ihr Konto. Dieselben Einstellungen finden Sie im Abschnitt KI-Modelle Ihrer Profilseite, und jede Änderung – egal auf welchem Weg – wird im Audit-Trail festgehalten.
MCP oder REST wählen
Abschnitt betitelt „MCP oder REST wählen“Der MCP-Server ist einer von zwei Zugängen zu denselben Funktionen, und er kann Ihnen nicht sagen, wenn Sie die falsche gewählt haben: Der falsche Weg ist langsam und kostet Kontext, ist aber kein Fehler.
- MCP ist für eine einzelne fachliche Aktion, eine Abfrage oder alles, bei dem der Server selbst urteilen muss. Die meiste Arbeit gehört hierher.
- REST (
https://portor.<tenant>.askalot.io/api/v1) ist für Massenarbeit und alles, dessen Payload oder Ergebnis groß ist. Schleifen und Filtern finden außerhalb Ihres Kontexts statt; Sie behalten nur eine Zusammenfassung.
Welche Zugangsdaten – das hängt davon ab, wer aufruft. Das OAuth-Access-Token, das
Ihre MCP-Sitzung authentifiziert, wird auf /api/v1 als
Authorization: Bearer <token> akzeptiert. Ein Personal Access Token gehört dagegen in den
Header X-Api-Token, nie als Bearer; siehe Authentifizierung.
- Ein Programm, das sein eigenes Token hält – ein SDK-Agent, der seine OAuth-Sitzung verwaltet –, darf es für REST wiederverwenden. Es hat die Zugangsdaten bereits in der Hand, und eine Sitzung ist auf beiden Wegen eine Identität.
- Code, den Sie für eine Sandbox erzeugen, oder alles, was die Runde überdauert, verwendet ein PAT. Das ist keine Geschmacksfrage: Eine Sandbox hat keine eigenen Zugangsdaten, mit denen sie diese API erreicht. Ein PAT lässt sich außerdem separat widerrufen, ein Sitzungs-Token nicht.
- Ein Modell, das einen Chat-Client steuert, sieht das Token überhaupt nie – der Client hält es. Wenn Sie Code schreiben, gilt für Sie der vorige Fall.
Fakten, die man leicht verwechselt:
bulk_create_respondentsist auf beiden Wegen auf 100 pro Aufruf begrenzt. REST validiert dieselbe Eingabe, 500 Befragte sind also in beiden Fällen fünf Aufrufe. REST gewinnt bei Roundtrips und Kontext, nie bei der Batch-Größe.- Die Pipeline-Job-Verben
code_open_endsundderive_silvergibt es nur über MCP. Ein REST-Gegenstück müssen Sie nicht suchen. - Datensätze sind nicht MCP-exklusiv.
list_datasets,get_dataset,delete_datasetundexport_datasethaben alle Routen unter/api/v1/datasets, und Auflisten oder Exportieren ist genau die Arbeit mit großen Ergebnissen, für die REST da ist. - Große Inhalte kommen als Link zurück.
export_datasetundget_qml_contentoberhalb von 32 KB liefern eine kurzlebige signiertedownload_url; rufen Sie sie über normales HTTPS ab. - Ein QML-Speichervorgang nennt die Version, auf der er beruht. Lesen Sie mit
get_qml_contentund übergeben Sie dessenversion_idalsbase_version_idansave_qml_fileoderfinalize_upload. Nennen Sie nach dem Speichern dieversion_id, die dieser Speichervorgang zurückgegeben hat. Beioverlaplesen Sie erneut und wenden Ihre Änderung noch einmal an; senden Sie nie denselben Inhalt erneut. Details: Fragebogen-Tools. - Abfragen statt Schleifen. Ohne Code-Sandbox schreiben Sie nicht Hunderte aufeinanderfolgender Tool-Aufrufe von Hand: Starten Sie den Job und fragen Sie
get_task_statusfür eine Task-ID ab oderget_datasetfür eine Datensatzstufe.
Die Tools einer Verbindung eingrenzen
Abschnitt betitelt „Die Tools einer Verbindung eingrenzen“Der vollständige Tool-Umfang umfasst über 120 Tools – mehr, als ein einzelnes Forschungsvorhaben vor sich haben muss. Eine Verbindung kann in der URL die Bereiche nennen, die sie haben möchte:
https://portor.<tenant>.askalot.io/mcp?toolsets=analysis,campaignDie Werte sind kommagetrennte Toolset-Namen. Eine Verbindung, die keine nennt, erhält alles; das ist der Standard und bleibt es.
Neun Toolsets lassen sich auf diese Weise filtern:
| Toolset | Was es enthält |
|---|---|
project |
Projekte und ihre Eigentümerschaft |
questionnaire |
Fragebögen und den QML-Lebenszyklus |
sampling |
Befragte, Pools und Stichprobenstrategien |
campaign |
Kampagnen und ihre Konfiguration |
fielding |
Umfragen, Einladungen, Interviewer, den Antwortablauf |
analysis |
Bundles, Datensätze und die Bronze/Silver/Gold-Pipeline |
documents |
Ihre hochgeladenen Referenzdokumente |
methodology |
Die gemeinsame Bibliothek zur Umfragemethodik |
audit |
Den Audit-Trail |
Acht weitere werden auf jeder Verbindung zugelassen, egal was Sie nennen, denn
ohne sie könnte ein Agent seinen eigenen Kurs nicht korrigieren: Ihre Sitzungs- und
Organisations-Tools, der Gesprächsverlauf, die Berechtigungen, die Dokumentation, das
Tool list_toolsets selbst, der Forschungsbericht, die unten beschriebenen
zusammengesetzten Tools und get_task_status – so lässt sich ein zusammengesetztes Tool,
das Sie auf einer eingegrenzten Verbindung starten, von dort immer abfragen.
Zwei Dinge ist es nicht, und beides sollte klar sein:
- Es ist keine Berechtigungsgrenze. Ihre URL wählen Sie selbst; ein genanntes Toolset sperrt also niemanden irgendwo aus. Was Sie dürfen, entscheiden Ihre Abonnementstufe, Ihre Rolle und die Projekteigentümerschaft – nichts davon ändert sich dadurch. Es grenzt ein, was vor Ihnen liegt, nicht, was Sie dürfen.
- Es ist keine Rolle. Der Parameter akzeptiert diese Toolset-Namen und sonst nichts;
eine Kurzform wie
?toolsets=analystgibt es nicht.
Rufen Sie jederzeit list_toolsets auf, um jedes Toolset zu sehen, welche Tools es enthält,
was Ihre Verbindung genannt hat und welche Namen sie nicht erkannt hat. Rufen Sie ein Tool
auf, das Ihre Verbindung ausgeschlossen hat, nennt die Ablehnung das Toolset, das es enthält,
und den URL-Parameter, der es zulassen würde – eine falsche Vermutung lässt sich also korrigieren,
ohne diese Seite zu lesen.
Um den Umfang zu ändern, verbinden Sie sich neu, da er in der Verbindungs-URL steckt. Das ist eine Funktion des HTTP-Transports; eine stdio-Verbindung hat keine URL und ist immer uneingeschränkt.
Eine ganze Abfolge in einem Aufruf
Abschnitt betitelt „Eine ganze Abfolge in einem Aufruf“Drei häufige Abfolgen gibt es jeweils als einzelnes Tool. Sie sind keine Abkürzungen, die Schritte auslassen – jeder Schritt ist dasselbe Tool, das Sie auch von Hand aufrufen würden, und schreibt dieselben Datensätze und hinterlässt denselben Audit-Trail:
| Ein Aufruf | Was er ausführt |
|---|---|
prepare_campaign_fielding |
Stichprobenstrategie → Befragtenpool → Pool zuweisen → Fragebogenversion veröffentlichen → Umfragen anlegen |
simulate_campaign_responses |
Umfragen anlegen → synthetische Antworten darüber erzeugen |
run_bundle_pipeline |
Bronze-Extraktion → Silver (Codierung + Gewichtung) → Gold |
Drei Dinge sollten Sie vor der Verwendung wissen:
prepare_campaign_fieldinghält an, bevor die Einladungen hinausgehen. Es versendet nie; das bleibt ein separater, bewusster Aufruf vonsend_campaign_invitations, den Sie ausführen, nachdem Sie geprüft haben, was die Kette aufgebaut hat. Eine E-Mail lässt sich nicht zurückholen.- Bricht eine Kette mittendrin ab, bleibt bestehen, was sie bereits aufgebaut hat. Nichts wird rückgängig gemacht.
Die Antwort nennt den Schritt in
stopped_at_step; ein Wert ungleich null bedeutet, dass die Kette nicht fertig wurde, und Sie machen von dort mit den einzelnen Tools weiter.run_bundle_pipelinemeldet einen Abbruch in seinem Umschlag{success: false, error, detail}; die anderen beiden liefern ihr normales Ergebnis mit ausgefülltenerrorunddetailund ohne Schlüsselsuccess. - Eine Kette prüft die gesamte Abfolge vorab. Deckt Ihr Abonnement einen späteren Schritt nicht ab, erfahren Sie das, bevor irgendetwas aufgebaut wird, statt ein halb fertiges Ergebnis zu erhalten.
simulate_campaign_responses und run_bundle_pipeline geben eine Task-ID zurück, die Sie mit get_task_status abfragen.
run_bundle_pipeline meldet den Schritt, den sein Lauf erreicht hat, und nach Abschluss den
Datensatz jeder Stufe; simulate_campaign_responses gibt denselben Fill-Task zurück wie das
einfache Tool mass_fill_surveys, sodass die Abfrage Fortschritt statt
Schritte meldet.
Verfügbare Tools
Abschnitt betitelt „Verfügbare Tools“Die MCP-Schnittstelle stellt nach Funktionsbereichen geordnete Tools bereit.
Sitzung und Organisationen
Abschnitt betitelt „Sitzung und Organisationen“| Tool | Beschreibung |
|---|---|
list_organizations |
Die Organisationen auflisten, in die diese Sitzung wechseln darf; die aktive wird markiert, versiegelte werden gekennzeichnet |
switch_organization |
Die aktive Organisation der Sitzung wechseln – jeder spätere Aufruf wird in ihr aufgelöst |
Projektverwaltung
Abschnitt betitelt „Projektverwaltung“| Tool | Beschreibung |
|---|---|
list_projects |
Alle Ihre Projekte auflisten |
get_project |
Projektdetails abrufen |
create_project |
Ein neues Projekt anlegen |
add_project_owners |
Benutzer als Projekteigentümer hinzufügen (die Zielpersonen müssen Mitglieder der Organisation des Projekts sein) |
remove_project_owners |
Benutzer als Projekteigentümer entfernen (es gilt dieselbe Mitgliedschaftsregel) |
Fragebogen-Operationen
Abschnitt betitelt „Fragebogen-Operationen“| Tool | Beschreibung |
|---|---|
list_questionnaires |
Alle Fragebögen auflisten |
get_questionnaire |
Fragebogendetails abrufen |
create_questionnaire |
Einen neuen Fragebogen aus QML-Inhalt oder aus einer Bibliotheksvorlage anlegen (template, kopiert in language, mit den übrigen Sprachen der Bibliothek als Übersetzungen); mit Inhalt kann es zusätzlich das inventory annehmen, aus dem der Inhalt erzeugt wurde, und speichert es mit Version 1 (ein Inventar, das nicht validiert, lässt das ganze Anlegen scheitern) |
list_questionnaire_templates |
Die Fragebogen-Vorlagenbibliothek in einer ihrer Sprachen auflisten (language; standardmäßig Ihre, Englisch mit language_fallback gekennzeichnet, wenn die Bibliothek Ihre nicht anbietet), nach Kategorie und mit einer Suche über Name und Beschreibung |
rename_questionnaire |
Einen Fragebogen umbenennen (die Adresse bleibt gleich) |
delete_questionnaire |
Einen Fragebogen vorläufig löschen (Soft Delete) |
restore_questionnaire |
Einen kürzlich vorläufig gelöschten Fragebogen wiederherstellen |
list_qml_files |
Die QML-Fragebögen der Organisation auflisten |
inspect_qml_file |
Kurzübersicht über die aktuelle Version eines Fragebogens |
preview_qml_item |
Ein Fragebogenelement so zeigen, wie eine befragte Person es sieht; ein Host, der MCP Apps darstellt, zeigt die echten Steuerelemente in einem schreibgeschützten Bereich |
get_qml_content |
Das aktuelle QML eines Fragebogens und seine version_id abrufen, die Basis, die ein Speichervorgang nennt (oberhalb von 32 KB kommt statt des Inhalts ein kurzlebiger Download-Link) |
validate_qml_file |
Z3-SMT-Validierung auf der aktuellen Version eines Fragebogens ausführen (Erreichbarkeit, Konsistenz) |
qml_quality_report |
Die D2–D8-Scorecard zur Designqualität für die aktuelle Version eines Fragebogens berechnen |
save_qml_file |
QML speichern, das auf einer von Ihnen genannten Version beruht (base_version_id, aus get_qml_content): mit einem neueren Speichervorgang zusammengeführt, wenn andere Zeilen betroffen sind, bei denselben Zeilen als overlap abgelehnt. Blockiert nie wegen fehlerhafter Entwürfe (Inhalt über 32 KB wird abgelehnt; verwenden Sie das Upload-Handle unten) |
request_upload_url / finalize_upload |
Zweistufiges Handle zum Speichern von QML-Inhalt oberhalb der 32-KB-Grenze von save_qml_file; auch finalize_upload nennt base_version_id |
request_import_upload_url |
Einen Einmal-Link erhalten, um einen gedruckten Fragebogen (PDF oder Markdown) zum Import in ein Projekt hochzuladen; laden Sie die Datei per PUT dorthin |
import_questionnaire |
Die hochgeladene Datei als neuen Fragebogenentwurf importieren. Langwierig und kostspielig: Läuft über Ihren eigenen KI-Anbieter und zählt gegen Ihr monatliches Importlimit. Im Quelldokument eingetragene Antworten werden verworfen, und der Upload wird gelöscht. Liefert eine task_id für get_task_status. Erfordert die Rolle Designer oder Manager (oder einen Operator) und Schreibzugriff auf das Projekt |
get_questionnaire_inventory |
Das Inventar lesen, aus dem ein Fragebogen erstellt wurde: die beschriebene Version, jede gedruckte Fragenummer mit ihrer Element-ID und die Prüfungen, die hinzugefügt statt gedruckt wurden (invented), samt Importbericht |
get_questionnaire_import_source |
Die Quelle, die ein PDF-Import gelesen hat, als Markdown lesen: was gefunden und entfernt wurde (Antworten, laufende Kopf- und Fußzeilen, gedruckte Seitenzahlen), dann ganze Seiten ab from_page bis etwa max_chars (Standard 32.000), mit next_page für den nächsten Aufruf. Jede Seite beginnt mit einer Markierung, die ihre Seite in der Datei, die darauf gedruckte Nummer und die Leseart (Text oder Vision) nennt; die Seitenzahlen des Inventars sind die der Datei. Ein Fragebogen, der nicht aus einem PDF importiert wurde, antwortet mit import_source_not_found |
list_qml_translations |
Je Sprache, ob die Übersetzung einer Version vollständig ist, welche Texte unübersetzt sind und ob sie eingefroren oder von Hand bearbeitet ist |
get_qml_translation |
Die Übersetzung einer Version in eine Sprache, mit jedem Quelltext als Vorlage und dem updated_at, das ein Speichervorgang nennt |
save_qml_translation |
Übersetzten Text für eine Sprache speichern (teilweise, über das Gespeicherte zusammengeführt; nennt base_updated_at). Nur Text: unbekannte IDs oder Codes und unvollständige Positionslisten werden abgelehnt |
delete_qml_translation |
Die Übersetzung einer Version in eine Sprache löschen (abgelehnt, sobald eingefroren) |
publish_qml_file |
Einen Fragebogen für eine Kampagne veröffentlichen – validiert formal und pinnt die exakte Version (der einzige Weg, der eine Prüfung erzwingt) |
move_qml_to_project |
Einen Fragebogen in ein anderes Projekt verschieben (der Versionsverlauf bleibt erhalten) |
unpublish_qml_file |
Einen Fragebogen vorläufig löschen, wobei sein Versionsverlauf erhalten bleibt (bei aktiven Kampagnen blockiert) |
Parameterreferenz – Parameter, Rückgabeschemas, QML-Lebenszyklus, Struktur der Z3-Ausgabe
Dokumentensuche
Abschnitt betitelt „Dokumentensuche“| Tool | Beschreibung |
|---|---|
list_indexed_documents |
Alle für die semantische KI-Suche indexierten Dokumente auflisten, jeweils mit ihrem Dokumentschlüssel (zum Beispiel projects/<project-id>/report.pdf) |
get_document_summary |
Die gespeicherte Markdown-Zusammenfassung eines Dokuments abrufen, benannt über seinen document_key |
get_document_chunk |
Einen bestimmten Abschnitt eines indexierten Dokuments abrufen (document_key, chunk_index) |
search_document_chunks_by_keyword |
Indexierte Dokumentabschnitte nach Schlüsselwort durchsuchen, optional auf document_keys beschränkt |
Forschungsbericht
Abschnitt betitelt „Forschungsbericht“| Tool | Beschreibung |
|---|---|
read_paper |
Den Forschungsbericht eines Projekts lesen – die zusammengesetzten Kapitel sowie das aktuelle Bearbeitungstoken jeder Einheit |
edit_paper_unit |
Eine exakte Passage innerhalb einer Einheit des Berichts ersetzen; alles andere bleibt Byte für Byte unverändert |
read_paper_translation |
Die Übersetzungen des Berichts in eine Sprache lesen: ohne Einheit den Zustand jeder Einheit (aktuell, veraltet, fehlend) und die Bearbeitungstokens; mit Einheit deren Quelltext und Übersetzung nebeneinander |
edit_paper_translation |
Die Übersetzung einer Einheit in eine Sprache schreiben, verankert wie bei edit_paper_unit; eine Übersetzung, die auf einer älteren Quelle beruht, wird vollständig ersetzt |
Der Forschungsbericht wird in seiner Quellsprache (Englisch) verfasst. Eine Übersetzung ist ein
separater Text neben jeder Einheit, der Lesern angezeigt wird, die den Forschungsbericht in dieser
Sprache lesen, und wird nie in die Quelleinheit geschrieben. Der Skill translate-paper
des Askalot-Plugins führt einen Agenten durch einen Übersetzungsdurchgang.
Kampagnenverwaltung
Abschnitt betitelt „Kampagnenverwaltung“| Tool | Beschreibung |
|---|---|
list_campaigns |
Kampagnen auflisten (optional nach Projekt) |
get_campaign |
Kampagnendetails abrufen |
create_campaign |
Eine neue Kampagne anlegen |
update_campaign |
Kampagnenfelder ändern (Name, Termine, Status, Zulassung von Freiwilligen, das Angebot des KI-Assistenten und seine Texte) |
delete_campaign |
Eine Kampagne löschen |
add_interviewers_to_campaign |
Interviewer hinzufügen (Benutzer mit Interviewer-Rolle) |
remove_interviewers_from_campaign |
Interviewer aus einer Kampagne entfernen |
update_campaign_questionnaire |
Den einer Kampagne zugewiesenen Fragebogen ändern |
assign_pool_to_campaign |
Einer Kampagne einen Befragtenpool zuweisen |
get_campaign_pool |
Den einer Kampagne zugewiesenen Befragtenpool abrufen |
send_campaign_invitations |
Umfrage-Einladungen per E-Mail an Befragte senden |
Befragte werden einer Kampagne nicht direkt hinzugefügt – weisen Sie mit assign_pool_to_campaign einen Befragtenpool zu; anschließend legt bulk_create_surveys für jede befragte Person im Pool eine Umfrage an.
Parameterreferenz – Parameter, Rückgabeschemas, Batch-Muster, Berechtigung zur Einladung
Verwaltung der Befragten
Abschnitt betitelt „Verwaltung der Befragten“| Tool | Beschreibung |
|---|---|
list_respondents |
Alle Befragten auflisten (die Zielpersonen der Umfragen) |
get_respondent |
Details zu einer befragten Person abrufen |
create_respondent |
Eine neue befragte Person anlegen |
update_respondent |
Angaben zu einer befragten Person ändern |
delete_respondent |
Eine befragte Person entfernen |
bulk_create_respondents |
Mehrere Befragte auf einmal anlegen |
bulk_delete_respondents |
Befragte nach Filter löschen (zweistufiger dry_run-Ablauf) |
generate_survey_access_token |
Ein Magic-Link-Token für die Umfrage einer befragten Person erzeugen |
send_survey_invitation |
Einer befragten Person eine Umfrage-Einladung mit Magic Link per E-Mail senden |
Parameterreferenz – Parameter, Rückgabeschemas, Massenanlage, Demografie
Befragtenpools
Abschnitt betitelt „Befragtenpools“Mit Befragtenpools ordnen Sie Befragte in wiederverwendbaren Gruppen für Kampagnen.
| Tool | Beschreibung |
|---|---|
list_respondent_pools |
Alle Befragtenpools auflisten |
get_respondent_pool |
Pooldetails einschließlich der Liste der Befragten abrufen |
create_respondent_pool |
Einen neuen Befragtenpool anlegen |
add_respondents_to_pool |
Befragte zu einem bestehenden Pool hinzufügen |
remove_respondents_from_pool |
Befragte aus einem Pool entfernen |
generate_pool_from_strategy |
Einen Pool in gewünschter Größe aus einer Stichprobenstrategie ziehen; der Pool speichert seine Ziehungseinstellungen |
preview_pool_generation |
Eine Ziehung in der Vorschau ansehen, ohne den Pool anzulegen |
plan_sample_size |
Nur lesend: eine Ziehung aus den Zielvorgaben eines Projekts bemessen (Fehlermarge oder Power für zwei Gruppen, zweiseitig, Normalapproximation), aus Eignung, Rücklauf und Designeffekt; liefert die benötigten vollständigen Interviews, den Oversampling-Faktor und die Zahl der Einzuladenden, mit der Revision der gespeicherten Zielvorgaben. Auch POST /api/v1/projects/{project_id}/sample-size-plan |
save_sizing_targets |
Die Zielvorgaben aller Ziele im Forschungsbericht des Projekts speichern und dabei die gelesene Revision nennen; eine veraltete Revision ist ein Konflikt (REST 409). Auch PUT /api/v1/projects/{project_id}/sizing-targets |
refresh_pool_from_strategy |
Einen bestehenden Pool mit den gespeicherten Ziehungseinstellungen neu ziehen |
delete_respondent_pool |
Einen Befragtenpool löschen |
Parameterreferenz – Parameter, Rückgabeschemas, Umgang mit Duplikaten, Erzeugung aus Strategien
Stichprobenstrategien
Abschnitt betitelt „Stichprobenstrategien“Stichprobenstrategien legen demografische Zielverteilungen fest, um repräsentative Stichproben von Befragten zu bilden. Eine Strategie enthält keine Größen- oder Auswahleinstellungen – das sind Eingaben jeder einzelnen Poolziehung –, sodass eine Strategie Pools beliebiger Größe speisen kann.
| Tool | Beschreibung |
|---|---|
list_sampling_strategies |
Alle Stichprobenstrategien auflisten |
get_sampling_strategy |
Strategiedetails einschließlich der Faktoren abrufen |
create_sampling_strategy |
Eine Strategie mit eigenen Faktoren für Befragte anlegen |
create_default_strategy |
Eine Strategie mit den Standardfaktoren Geschlecht und Alter anlegen |
update_sampling_strategy |
Eine bestehende Strategie ändern |
delete_sampling_strategy |
Eine Stichprobenstrategie löschen |
Beispiel: Eine eigene Stichprobenstrategie anlegen
AI Assistant: I'll create a sampling strategy targeting your demographics.
→ create_sampling_strategy( name="Urban Millennials", project_id="...", factors=[ {"name": "Gender", "attribute_path": "gender", "target_distribution": {"male": 0.48, "female": 0.50, "other": 0.02}}, {"name": "Age Group", "attribute_path": "age", "target_distribution": {"25-34": 0.60, "35-44": 0.40}} ] )
Strategy created! Now generating a representative pool...→ generate_pool_from_strategy(strategy_id, pool_name="Urban Millennials Pool", requested_size=200)Parameterreferenz – Parameter, Rückgabeschemas, Faktorschema, Validierung der Verteilungen
Benutzerverwaltung
Abschnitt betitelt „Benutzerverwaltung“| Tool | Beschreibung |
|---|---|
list_users |
Benutzer in Ihrer aktiven Organisation auflisten (einschließlich Interviewern) – rufen Sie switch_organization auf, um die Benutzer einer anderen Organisation zu sehen |
get_user |
Benutzerdetails abrufen |
Hinweis: Interviewer sind Benutzer mit der Rolle interviewer. Sie werden als Benutzer verwaltet, nicht als Befragte.
Arbeitslast der Interviewer
Abschnitt betitelt „Arbeitslast der Interviewer“Bei Kampagnen mit Interviewern (Benutzer mit Interviewer-Rolle) steuern Sie die Verteilung der Arbeitslast:
| Tool | Beschreibung |
|---|---|
assign_respondents_to_interviewer |
Befragte einem bestimmten Interviewer (Benutzer) zuweisen |
unassign_respondents_from_interviewer |
Zuweisungen zu Interviewern aufheben |
get_interviewer_workload |
Zugewiesene Befragte und den Abschlussstand ansehen |
get_unassigned_respondents |
Befragte finden, die noch nicht zugewiesen sind |
Durchführung von Umfragen
Abschnitt betitelt „Durchführung von Umfragen“| Tool | Beschreibung |
|---|---|
list_surveys |
Umfragen auflisten (Filter nach Kampagne oder befragter Person) |
create_survey |
Eine neue Umfragesitzung starten |
update_survey |
Status und Ablaufzustand einer Umfrage ändern (gebundene Entitäten sind unveränderlich) |
bulk_create_surveys |
Umfragen für alle Befragten einer Kampagne anlegen |
bulk_delete_surveys |
Umfragen nach Filter löschen (zweistufiger dry_run-Ablauf) |
get_survey_current_item |
Die aktuelle Frage mit eingebetteten Antwortoptionen abrufen |
submit_survey_response |
Eine Antwort übermitteln und weitergehen (der nächste Schritt ist eingebettet) |
finish_survey |
Eine Umfrage ausdrücklich abschließen |
mass_fill_surveys |
Einen asynchronen Hintergrund-Task einreihen, der Umfragen mit synthetischen Testantworten füllt (liefert {task_id, status}) |
get_task_status |
Einen asynchronen Task über task_id abfragen: einen mass_fill_surveys-Lauf, eine simulate_campaign_responses- oder run_bundle_pipeline-Kette oder einen import_questionnaire-Lauf (Codierungsjobs für Datensätze werden stattdessen über get_dataset abgefragt) |
Parameterreferenz – Parameter, Rückgabeschemas, Zustandsautomat, Verteilungsmodi, Personas
Datenanalyse
Abschnitt betitelt „Datenanalyse“Ein Bundle bindet ein Projekt, einen Fragebogen und eine Auswahl von Kampagnen an eine lineare Datensatzkette Bronze → Silver → Gold. Bundle-Tools verwalten diese Bindung und liefern die Qualitätsübersicht des Bundles; Datensatz-Tools führen die einzelnen Bundle-bezogenen Stufen aus – Extraktion, Codierung + Gewichtung, Verfeinerung und Export.
| Tool | Beschreibung |
|---|---|
create_bundle |
Ein Pipeline-Bundle anlegen |
list_bundles |
Bundles auflisten, optional auf ein Projekt gefiltert |
get_bundle |
Bundle-Details, einschließlich der Konfigurationen seiner Stufen (Silver-Kalibrierungsziele, Gold-Operationen) |
clone_bundle |
Die fertigen Datensätze und Konfigurationen eines Bundles tief in eine unabhängige Variante kopieren |
delete_bundle |
Ein Bundle und seine Datensatzkette löschen |
get_bundle_quality |
Die Repräsentativitätsübersicht des Bundles (Auswahl, Feldphase, gewichtet, Verschiebung in der Feldphase, Rücklauf) |
compare_bundle_quality |
Verbesserung von Bronze zu Silver gegenüber der aktuellen Strategie des Bundles |
get_bundle_coding |
Stand der Codierung offener Antworten – die Kandidaten, die das Bronze anbietet, die vom Analysten festgelegte Antwortart für jeden (deskriptiv, nominal oder Kennung; fehlend = nicht klassifiziert), die Fragenauswahl und je Frage die vorgeschlagenen Dimensionen, ihre Kategorien und welche ausgewählt sind |
set_coding_selection |
Festlegen, welche Freitext-Einheiten das Bundle codiert (Manager-Rolle, identifizierter Benutzer erforderlich); lehnt eine nicht klassifizierte oder eine Kennungs-Einheit ab, und kein Tool klassifiziert eine solche |
assign_bundle_strategy |
Die aktuelle Stichprobenstrategie des Bundles zuweisen (oder entfernen) |
set_calibration_targets |
Die Kalibrierungsziele des Bundles bearbeiten – die Gewichtungsspezifikation für Silver –, jedes raked (es wird darauf gewichtet) oder benchmark (nur bewertet); jedes Speichern prüft die Antwortcodes gegen den Fragebogen des Bundles |
preview_calibration_targets_copy |
Vorschau auf das Kopieren der Kalibrierungsziele eines anderen Bundles in dieses: welche passen (mit ihrer Rolle) und welche nicht, mit Begründung; schreibt nichts |
list_datasets |
Datensätze aus der Kette eines Bundles auflisten |
get_dataset |
Datensatzdetails, Kennzahlen und Status abrufen – der schlanke Zugang, den Pipeline-Schritte zum Abfragen nennen |
get_dataset_schema |
Das Spaltenschema eines Datensatzes abrufen oder nur seine Spaltennamen und Steuerelementtypen, optional auf benannte Spalten eingegrenzt |
create_bronze_dataset |
Den Bronze-Datensatz eines Bundles extrahieren |
code_open_ends (Alias derive_silver) |
Offenen Text codieren und dann gegen die Kalibrierungsziele gewichten; das ergibt das Silver des Bundles |
create_gold_dataset |
Das Silver eines Bundles mithilfe des Gold-Operationskatalogs zu seinem Gold verfeinern |
export_dataset |
Einen fertigen Datensatz exportieren (CSV, XLSX, SPSS, Parquet, R, JSON) |
delete_dataset |
Einen Datensatz löschen |
Referenz der Bundle-Tools – Parameter für Bundle-Lebenszyklus und Qualität, Rückgabeschemas
Referenz der Datensatz-Tools – Stufenparameter, Rückgabeschemas, Exportformate
Audit & Compliance
Abschnitt betitelt „Audit & Compliance“| Tool | Beschreibung |
|---|---|
query_audit_events |
Den Audit-Trail mit Filtern durchsuchen |
get_entity_history |
Den vollständigen Verlauf einer beliebigen Entität ansehen |
get_audit_stats |
Ereigniszahlen nach Entitätstyp |
Alle drei lesen nur Ihren Tenant und Ihre aktive Organisation. Um den Audit-Trail einer anderen Organisation zu lesen, wechseln Sie zuerst in sie. Ereignisse, die ohne Organisation erfasst wurden, etwa System- und Service-Aktionen, werden nicht zurückgegeben.
Innerhalb der Organisation hängt das, was Sie sehen, von Ihrer Rolle ab:
| Wer | Was die Audit-Tools zurückgeben |
|---|---|
Administrator (org_admin der Organisation oder ein Askalot-Operator) |
Den Audit-Trail der gesamten Organisation, einschließlich get_audit_stats |
manager |
Ihre eigenen Aktionen sowie den vollständigen Verlauf von Projekten, Fragebögen, Kampagnen und Umfragen in Projekten, die Ihnen gehören |
| Alle anderen | Nur Ihre eigenen Aktionen |
Anfragen nach den Aktionen eines anderen Benutzers oder nach dem Verlauf einer Entität außerhalb Ihrer Reichweite werden abgelehnt. get_audit_stats ist Administratoren vorbehalten, und eine Verbindung, die für keinen Benutzer handelt, liest überhaupt kein Audit. In einer Organisation, in der jedes Mitglied jedes Projekt liest, etwa der öffentlichen Organisation Askalot Demo, ist der Audit-Trail Administratoren vorbehalten: Wer die Forschung lesen darf, darf deshalb noch lange nicht lesen, wer was getan hat, denn Audit-Ereignisse enthalten Details wie IP-Adressen.
Die Audit-Ansicht im Browser wendet dieselben Rollen an, doch ein Askalot-Operator und ein normaler Benutzer sehen dort mehr:
| Wer | Was die Audit-Ansicht im Browser zeigt |
|---|---|
Askalot-Operator (tenant_admin) |
Jedes Ereignis im Tenant, über alle Organisationen hinweg |
Organisationsadministrator (org_admin) |
Jedes Ereignis der aktiven Organisation |
manager |
Innerhalb der aktiven Organisation: Ihre eigenen Aktionen sowie den Verlauf von Projekten, Fragebögen, Kampagnen und Umfragen in Projekten, die Ihnen gehören |
| Alle anderen | Nur Ihre eigenen Aktionen, einschließlich Ihrer Anmeldungen |
Eine Anmeldung wird in der Organisation erfasst, in der die Sitzung startet, eine Abmeldung oder Passwortänderung in der Organisation, in der die Sitzung gerade arbeitet; sie gehören damit wie jede andere Aktion zum Audit-Trail dieser Organisation.
Zugriff auf die Dokumentation
Abschnitt betitelt „Zugriff auf die Dokumentation“| Tool | Beschreibung |
|---|---|
list_documentation |
Verfügbare Dokumentation auflisten |
get_documentation |
Ein bestimmtes Dokument laden |
search_documentation |
Die Dokumentation nach Schlüsselwort durchsuchen |
MCP-Ressourcen
Abschnitt betitelt „MCP-Ressourcen“Ressourcen bieten schreibgeschützten Zugriff auf Plattformdaten:
| Ressourcen-URI | Beschreibung |
|---|---|
repository://overview |
Plattformstatistiken und Zählungen |
repository://schema |
Beziehungen und Struktur der Entitäten |
qml://files |
Die QML-Fragebögen der Organisation |
docs://primer |
Überblick über die Plattform |
docs://qml-syntax |
Referenz der Sprache QML |
docs://getting-started |
Schnellstartanleitung |
Weitere Dokumentationsressourcen spiegeln die Wissensdatenbank (docs://guide, docs://glossary, docs://campaign-management, docs://survey-execution, docs://creating-surveys, docs://data-analysis, docs://quality-metrics).
Beispiel-Workflows
Abschnitt betitelt „Beispiel-Workflows“Eine Umfragekampagne mit KI anlegen
Abschnitt betitelt „Eine Umfragekampagne mit KI anlegen“AI Assistant: I'll help you set up a customer satisfaction survey.
1. First, let me create a project... → create_project("Customer Research 2026", "Annual satisfaction study")
2. Now I'll register your questionnaire... → create_questionnaire("CSAT Survey", qml_content, project_id)
3. Creating the campaign... → create_campaign("Q1 CSAT", project_id, questionnaire_id, admits_volunteers=false, offers_ai_channel=false)
4. Adding your respondent list... → bulk_create_respondents(100, generate_demographics=true) → create_respondent_pool("CSAT Sample", respondent_ids=[...]) → assign_pool_to_campaign(campaign_id, pool_id) → bulk_create_surveys(campaign_id)
Your campaign is ready! 100 respondents have surveys waiting.Einen gedruckten Fragebogen importieren
Abschnitt betitelt „Einen gedruckten Fragebogen importieren“AI Assistant: I'll import your paper questionnaire into the project.
1. Getting an upload link for the PDF... → request_import_upload_url(project_id, "application/pdf") PUT the file to upload_url with Content-Type: application/pdf
2. Starting the import (this takes a few minutes)... → import_questionnaire(project_id, upload_id, "visitor-survey.pdf") → get_task_status(task_id) # until completed or failed
3. Reading what it built... → get_questionnaire_inventory(result.questionnaire_id) Each printed question number maps to its item id; the checks marked invented were added and are worth reviewing before you publish.
4. Checking a question against what the import read (PDF only)... → get_questionnaire_import_source(result.questionnaire_id, from_page=12)Ein abgelehnter Import startet nichts und nennt, was die Ablehnung behebt: unsupported_type
(derzeit werden nur PDF und Markdown gelesen), too_large, invalid_request,
no_ai_slot (verbinden Sie in den Profileinstellungen einen Anthropic-API-Schlüssel oder Amazon Bedrock
und ein Direct-LLM-Modell) oder fair_use_exceeded (das monatliche Importlimit).
Ein abgelehnter Import braucht einen neuen Upload, weil die Datei in jedem Fall gelöscht wird.
Eine repräsentative Stichprobe bilden
Abschnitt betitelt „Eine repräsentative Stichprobe bilden“AI Assistant: I'll create a demographically balanced sample for your study.
1. Creating a sampling strategy with your target demographics... → create_sampling_strategy( name="National Representative", project_id, factors=[ {"name": "Gender", "attribute_path": "gender", "target_distribution": {"male": 0.49, "female": 0.51}}, {"name": "Age", "attribute_path": "age", "target_distribution": {"18-34": 0.30, "35-54": 0.40, "55+": 0.30}} ] )
2. Generating a pool that matches your targets... → generate_pool_from_strategy(strategy_id, pool_name="Q1 Sample Pool", requested_size=500)
3. Assigning the pool to your campaign... → assign_pool_to_campaign(campaign_id, pool_id)
Done! Your campaign now has 500 respondents balanced to matchnational demographics.Eine Umfrage programmatisch durchführen
Abschnitt betitelt „Eine Umfrage programmatisch durchführen“AI Assistant: I'll walk through the survey and show you each question.
→ create_survey(questionnaire_id, respondent_id)→ get_survey_current_item(survey_id)
Question 1: "What is your age?"Type: Integer input (18-100)
User: 35
→ submit_survey_response(survey_id, "q_age", 35)→ get_survey_current_item(survey_id)
Question 2: "How satisfied are you with our service?"Type: Scale (1-5)...Die Arbeitslast der Interviewer steuern
Abschnitt betitelt „Die Arbeitslast der Interviewer steuern“AI Assistant: Let me distribute the 50 respondents among your 5 interviewers (Users with interviewer role).
→ get_unassigned_respondents(campaign_id) Found 50 unassigned respondents
→ assign_respondents_to_interviewer(campaign_id, interviewer_user_1, respondents[0:10])→ assign_respondents_to_interviewer(campaign_id, interviewer_user_2, respondents[10:20])...
→ get_interviewer_workload(campaign_id, interviewer_user_1) Assigned: 10 respondents Completed: 0 In Progress: 0Plattformkonzepte
Abschnitt betitelt „Plattformkonzepte“Wenn Sie das Entitätsmodell kennen, fällt die Arbeit mit der MCP-Schnittstelle leichter:
Entitätshierarchie
Abschnitt betitelt „Entitätshierarchie“Project├── Questionnaire (owns a QML version chain)└── Campaign ├── Respondents (survey targets) ├── Interviewers (Users with interviewer role, optional) └── Surveys (individual sessions)Jeder Fragebogen gehört zu einem Projekt, und jeder Benutzer hat ein Standardprojekt (is_default: true). Nennt eine Anfrage kein Projekt, finden Sie das Standardprojekt mit list_projects und verwenden seine ID.
Befragte und Interviewer
Abschnitt betitelt „Befragte und Interviewer“- Befragte: Zielpersonen der Umfrage mit demografischen Daten. Ihre abgeschlossenen Umfragen bestimmen den Fortschritt der Kampagne. Sie greifen über Magic Links auf Umfragen zu (keine Anmeldung an der Plattform nötig).
- Interviewer (optional): Benutzer mit der Rolle
interviewer, die Umfragen für Befragte durchführen. Sie haben ein Plattformkonto und helfen Befragten beim Ausfüllen, füllen selbst aber keine Umfragen aus.
Interviewer können zugewiesen werden, um Befragten persönlich oder telefonisch zu helfen. Sind Interviewer zugewiesen, halten die Umfragen fest, welcher Interviewer die Umfrage der jeweiligen befragten Person durchgeführt hat.
Befragte und Benutzer
Abschnitt betitelt „Befragte und Benutzer“- Befragte sind Zielpersonen der Umfrage mit demografischen Daten (Alter, Geschlecht, Wohnort). Sie haben kein Konto auf der Plattform.
- Benutzer sind Plattformkonten für Authentifizierung und Verwaltung. Benutzer mit der Rolle
interviewerkönnen Umfragen durchführen. - Befragte und Benutzer sind getrennte Entitäten. Interviewer sind Benutzer, keine Befragten.
Fehlerbehandlung
Abschnitt betitelt „Fehlerbehandlung“MCP-Tools liefern strukturierte Fehlermeldungen. Zwei gelten in jeder Kategorie:
not_found– die Entität befindet sich nicht in der aktiven Organisation der Sitzung. Die Meldung nennt die durchsuchte Organisation; siehe Ihre aktive Organisation.org_sealed– die aktive Organisation ist versiegelt. Lesezugriffe gelingen; diese Ablehnung kommt immer nur von einem Tool, das ihren Forschungsbestand geändert hätte.
Ausführliche Fehlermuster sind je Kategorie dokumentiert:
- Kampagnen-Tools – Batch-Muster (added/skipped/reasons), Berechtigung zur Einladung
- Umfrage-Tools – Zustandsübergänge, Ablauffehler
- Datensatz-Tools – Validierung der Stufen, Formatfehler
- Pool-Tools – Umgang mit Duplikaten, Validierung von Strategien
- Stichproben-Tools – Validierung des Faktorschemas, Schutz der Standardstrategie
- Fragebogen-Tools – Einschränkungen im Lebenszyklus, Prüfung auf aktive Kampagnen
- Befragten-Tools – Fehler bei der Massenanlage