Zum Inhalt springen
Wissensdatenbank

Tools für Stichprobenstrategien — MCP-Tool-Referenz

Die Tools für Stichprobenstrategien legen demografische Zielverteilungen fest, um repräsentative Stichproben von Befragten zu bilden. Eine Strategie beschreibt eine Grundgesamtheit: ihre Faktoren – demografische Dimensionen mit Zielanteilen – und wie die Übereinstimmung damit bewertet wird (quality_metric, aggregation_method). Die Pool-Erzeugung nutzt diese Faktoren, um Befragte auszuwählen, die zu Ihrem Stichprobendesign passen.

Eine Strategie enthält nur Faktoren der Befragten – Attribute, die bekannt sind, bevor jemand antwortet. Ein Ziel für eine Umfrageantwort (zum Beispiel ein Benchmark aus Wahlergebnissen oder einer Volkszählung) gehört in das Bundle, das die Antworten enthält, und zwar als reines Benchmark-Kalibrierungsziel: siehe set_calibration_targets.

Listet alle Stichprobenstrategien 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 id, name, description, project_id, factor_count, quality_metric, created_at.


Ruft eine Stichprobenstrategie anhand ihrer ID ab, einschließlich der vollständigen Faktordefinitionen.

Parameter Typ Erforderlich Standard Beschreibung
strategy_id string Ja — UUID der Strategie

Rückgabe: Das vollständige Strategieobjekt: id, name, description, project_id, factors, quality_metric, aggregation_method, is_default, created_at, modified_at.


Legt eine Stichprobenstrategie mit Faktoren für demografische Verteilungen an.

Parameter Typ Erforderlich Standard Beschreibung
name string Ja — Name der Strategie
project_id string Nein — ID des übergeordneten Projekts
factors object[] Nein — Definitionen der Verteilungsfaktoren (siehe unten)
quality_metric string Nein "rmse" "rmse", "mae", "chi_square" oder "max_deviation"; jeder andere Wert wird abgelehnt, und es wird nichts angelegt
description string Nein — Beschreibung der Strategie

Rückgabe: Das vollständige Strategieobjekt (wie bei get_sampling_strategy).

Jeder Faktor im Array factors definiert eine Dimension der Befragten. Ein Schlüssel, den das folgende Schema nicht aufführt, wird als Validierungsfehler abgelehnt (REST 422). Ein Faktor, der noch das ausgemusterte Feld source trägt, schlägt also fehl, statt stillschweigend verworfen zu werden:

Feld Typ Erforderlich Standard Beschreibung
name string Ja — Anzeigename (z. B. "Gender")
attribute_path string Ja — Attribut der Befragten (z. B. "gender" oder ein benutzerdefiniertes Attribut)
target_distribution object Ja — Zuordnung Kategorie → Anteil. Muss sich zu 1.0 summieren (Toleranz ±0.01)
factor_type string Nein "discrete" "discrete", "bucketed" oder "geographic"
bucket_ranges array Nein — Für den Typ bucketed: Liste von [min, max, label]-Tupeln
weight float Nein 1.0 Gewicht für die Bedeutung dieses Faktors

Beispiel:

{
"name": "Gender",
"attribute_path": "gender",
"target_distribution": {"male": 0.48, "female": 0.50, "other": 0.02},
"factor_type": "discrete",
"weight": 1.0
}

Legt eine Strategie mit den Standardfaktoren für Geschlechts- und Altersverteilung an.

Parameter Typ Erforderlich Standard Beschreibung
name string Ja — Name der Strategie
project_id string Nein — ID des übergeordneten Projekts

Rückgabe: Das vollständige Strategieobjekt (wie bei get_sampling_strategy).

Standardfaktoren:

  • Geschlecht: männlich 48 %, weiblich 50 %, divers 2 %
  • Altersgruppe: 18–24 (15 %), 25–34 (20 %), 35–44 (20 %), 45–54 (18 %), 55–64 (15 %), 65+ (12 %)

Aktualisiert eine bestehende Stichprobenstrategie (partielle Aktualisierung – nur die übergebenen Felder ändern sich).

Parameter Typ Erforderlich Standard Beschreibung
strategy_id string Ja — UUID der Strategie
name string Nein — Neuer Name
description string Nein — Neue Beschreibung
factors object[] Nein — Alle Faktoren ersetzen (nicht zusammenführen)
quality_metric string Nein — Neue Qualitätsmetrik, eine der vier oben genannten; jeder andere Wert wird abgelehnt, und es ändert sich nichts

Rückgabe: Das vollständige Strategieobjekt (wie bei get_sampling_strategy).

Eine Aktualisierung der Strategie ändert nie einen bereits daraus gezogenen Pool: Jeder Pool behält die Ziehungseinstellungen, mit denen er erzeugt wurde, und eine Aktualisierung des Pools zieht anhand der aktuellen Faktoren der Strategie in der Größe neu, die der Pool selbst gespeichert hat.


Löscht eine Stichprobenstrategie. Geschützt, wenn die Strategie die Standardstrategie ist oder verknüpfte Pools hat.

Parameter Typ Erforderlich Standard Beschreibung
strategy_id string Ja — UUID der Strategie

Rückgabe: { strategy_id, deleted }


Situation Antwort
Pflichtfeld fehlt {"error": "Each factor must have 'name', 'attribute_path', and 'target_distribution'"}
Verteilung summiert sich nicht zu 1.0 {"error": "Factor '{name}' target_distribution must sum to 1.0 (got {sum:.3f})"}
Ein Schlüssel, den das Faktorschema nicht deklariert (z. B. source) validation_error (REST 422) mit Nennung des zusätzlichen Felds

Die Validierung der Faktoren gilt sowohl für create_sampling_strategy als auch für update_sampling_strategy.

Situation Antwort
Standardstrategie ändern {"error": "Cannot modify the default sampling strategy"}
Standardstrategie löschen {"error": "Cannot delete the default sampling strategy"}
Situation Antwort
Strategie mit Pools löschen {"error": "Cannot delete strategy: {count} pool(s) are linked to it"}
Situation Antwort
Strategie nicht gefunden {"error": "Strategy {id} not found"}
Kein Eigentümer des Projekts der Strategie {"error": "forbidden", "detail": "caller is not an owner of this project and lacks an admin role"}