Tool-Referenz

Der Server stellt die folgenden Tools bereit. Jedes Tool erfordert den angegebenen OAuth-Scope: Eine Verbindung mit reinem scorecards:read-Zugriff kann keine mit scorecards:write gekennzeichneten Tools ausführen.

Destruktive Tools überschreiben oder löschen vorhandene Daten. Die meisten Clients fordern vor der Ausführung eine Bestätigung an.

scorecard_design_guide

Lesen Sie diesen Leitfaden vor dem Erstellen oder grundlegenden Bearbeiten einer Scorecard. Er erläutert Vorabfragen, manipulationssichere Formulierungen, werthaltige Stufeneinblicke und die Theme-Auswahl.

Scope: scorecards:read · idempotent

Argument	Typ	Erforderlich	Beschreibung
topics	Array von Strings	nein	Einzugrenzende Abschnitte (z. B. “themes”, “questions”). Standardmäßig alle.

list_scorecards

Listet alle Scorecards des Kontos mit Slug, Veröffentlichungsstatus, Einreichungsanzahl und Embed-Freigaben auf.

Scope: scorecards:read · idempotent

Argument	Typ	Erforderlich	Beschreibung
status	all | published | draft	nein	Filter nach Veröffentlichungsstatus. Standard: all.

get_scorecard

Liest eine Scorecard vollständig aus: Konfiguration, Dimensionen, Fragen, Antwortoptionen und Bewertungsstufen.

Scope: scorecards:read · idempotent

Argument	Typ	Erforderlich	Beschreibung
slug	String	ja	Der Slug der Scorecard laut list_scorecards.

create_scorecard

Erstellt einen neuen Entwurf mit optionalen Einstellungen für Darstellung, Branding, Scoring-Stufen, Einbettung und Kontakterfassung.

Scope: scorecards:write

Argument	Typ	Erforderlich	Beschreibung
title	String	ja	Titel der Scorecard für Teilnehmer.
subtitle	String	nein	Untertitel mit Zielgruppe und Zeitbedarf.
slug	String	nein	Eindeutiger URL-Slug. Wird bei Auslassung aus dem Titel erzeugt.
idempotencyKey	String	nein	Schlüssel zur Verhinderung von Mehrfacherstellungen bei Wiederholungsversuchen.
ctaText	String	nein	Beschriftung des Start-Buttons.
version	String	nein	Interne Versionsnummer (z. B. “1.0”).
theme	default | playground | obsidian | brutalist	nein	Visuelles Theme.
overallTierStrategy	weakest | average	nein	Berechnungslogik für das Gesamtergebnis: weakest (schlechteste Dimension) oder average (Durchschnitt).
tiers	Array von Objekten	nein	Gesamtstufen-Definition.
emailCaptureBeforeQuestions	Boolean	nein	E-Mail-Abfrage vor (true) statt nach (false) den Fragen. Standard: false.
privacyPolicyUrl	String oder null	nein	URL der Datenschutzerklärung.
termsUrl	String oder null	nein	URL der Nutzungsbedingungen.
embed	Objekt	nein	Einstellungen für die iframe-Einbettung.
branding	Objekt	nein	Logo, Palette und Handlungsaufforderungen.
emailCapture	Objekt	nein	Texte und Felder der Kontakterfassung.
detail	summary | full	nein	Detailgrad der Rückgabe. Standard: summary.

update_scorecard_config

Aktualisiert die Einstellungen einer bestehenden Scorecard, ohne Dimensionen, Fragen oder Antworten zu verändern.

Scope: scorecards:write · destruktiv

Argument	Typ	Erforderlich	Beschreibung
slug	String	ja	Aktueller Slug der zu bearbeitenden Scorecard.
newSlug	String	nein	Neuer Slug. Achtung: Es wird keine Weiterleitung eingerichtet.
title	String	nein	Neuer Titel.
subtitle	String	nein	Neuer Untertitel.
ctaText	String	nein	Neuer Start-Button-Text.
version	String	nein	Neue interne Versionsbezeichnung.
theme	default | playground | obsidian | brutalist	nein	Neues Theme.
overallTierStrategy	weakest | average	nein	Auswertungsstrategie für das Gesamtergebnis.
tiers	Array von Objekten	nein	Neue Gesamtstufen.
emailCaptureBeforeQuestions	Boolean	nein	Zeitpunkt der Kontakterfassung.
privacyPolicyUrl	String oder null	nein	URL der Datenschutzerklärung.
termsUrl	String oder null	nein	URL der Nutzungsbedingungen.
embed	Objekt	nein	Einbettungseinstellungen.
branding	Objekt	nein	Branding- und Farbkonfiguration.
emailCapture	Objekt	nein	Kontaktmaskenkonfiguration.
detail	summary | full	nein	Detailgrad der Rückgabe.

add_dimension

Fügt einer Scorecard eine Auswertungsdimension hinzu.

Scope: scorecards:write

Argument	Typ	Erforderlich	Beschreibung
slug	String	ja	Der Scorecard-Slug.
label	String	ja	Name der Dimension (z. B. „Klarheit im Projektumfang“).
shortLabel	String	nein	Kurzbezeichnung für Diagrammachsen.
key	String	nein	Stabiler Identifikator der Dimension.
detail	summary | full	nein	Detailgrad der Rückgabe.

add_questions

Fügt alle Fragen einer Dimension in einem einzigen Aufruf hinzu. Antwortoptionen müssen geordnet (von der schlechtesten zur besten) und bepunktet sein. Die Stufenbereiche werden automatisch berechnet.

Scope: scorecards:write

Argument	Typ	Erforderlich	Beschreibung
slug	String	ja	Der Scorecard-Slug.
dimensionKey	String	ja	Schlüssel der zugehörigen Dimension.
questions	Array von Objekten	ja	Fragen in Anzeigereihenfolge (empfohlen: 3–5).
detail	summary | full	nein	Detailgrad der Rückgabe.

add_question

Fügt einer Dimension eine einzelne Frage hinzu.

Scope: scorecards:write

Argument	Typ	Erforderlich	Beschreibung
slug	String	ja	Der Scorecard-Slug.
dimensionKey	String	ja	Dimensionsschlüssel.
text	String	ja	Fragentext.
answers	Array von Objekten	nein	Bepunktete Antwortoptionen.
detail	summary | full	nein	Detailgrad der Rückgabe.

set_dimension_tiers

Definiert die Ergebnisstufen für eine Dimension (Bezeichnung und Erkenntnistext) von der schwächsten zur stärksten Stufe. Punktebereiche werden automatisch berechnet.

Scope: scorecards:write · destruktiv, idempotent

Argument	Typ	Erforderlich	Beschreibung
slug	String	ja	Der Scorecard-Slug.
dimensionKey	String	ja	Dimensionsschlüssel.
tiers	Array von Objekten	ja	Stufen (üblicherweise drei), aufsteigend sortiert.
detail	summary | full	nein	Detailgrad der Rückgabe.

update_dimension

Ändert Bezeichnung, Kurzbezeichnung, Gewichtung oder Position einer Dimension. Der Dimensionsschlüssel bleibt unverändert.

Scope: scorecards:write · destruktiv, idempotent

Argument	Typ	Erforderlich	Beschreibung
slug	String	ja	Der Scorecard-Slug.
dimensionKey	String	ja	Dimensionsschlüssel.
label	String	nein	Neue Bezeichnung.
shortLabel	String	nein	Neue Kurzbezeichnung.
weight	Integer	nein	Gewichtung bei der Gesamtauswertung.
position	Integer	nein	Neue Position (0-basiert).
detail	summary | full	nein	Detailgrad der Rückgabe.

update_question

Ändert Formulierung, Antwortoptionen oder Reihenfolge einer Frage. Bestehende Einreichungen behalten ihren damaligen Stand.

Scope: scorecards:write · destruktiv, idempotent

Argument	Typ	Erforderlich	Beschreibung
slug	String	ja	Der Scorecard-Slug.
questionId	String	ja	ID der Frage.
text	String	nein	Neuer Fragentext.
answers	Array von Objekten	nein	Neue Antwortoptionen.
position	Integer	nein	Neue Position in der Dimension.
detail	summary | full	nein	Detailgrad der Rückgabe.

remove_question

Löscht eine Frage aus ihrer Dimension. Stufenbereiche werden automatisch angepasst.

Scope: scorecards:write · destruktiv

Argument	Typ	Erforderlich	Beschreibung
slug	String	ja	Der Scorecard-Slug.
questionId	String	ja	ID der zu löschenden Frage.
detail	summary | full	nein	Detailgrad der Rückgabe.

remove_dimension

Löscht eine Dimension mitsamt allen enthaltenen Fragen.

Scope: scorecards:write · destruktiv

Argument	Typ	Erforderlich	Beschreibung
slug	String	ja	Der Scorecard-Slug.
dimensionKey	String	ja	Schlüssel der zu löschenden Dimension.
detail	summary | full	nein	Detailgrad der Rückgabe.

check_scorecard

Prüft, ob eine Scorecard veröffentlichungsbereit ist und weist auf Schwachstellen hin.

Scope: scorecards:read · idempotent

Argument	Typ	Erforderlich	Beschreibung
slug	String	ja	Der Scorecard-Slug.

publish_scorecard

Schaltet eine Scorecard öffentlich oder setzt sie auf Entwurf zurück.

Scope: scorecards:write · destruktiv, idempotent

Argument	Typ	Erforderlich	Beschreibung
slug	String	ja	Der Scorecard-Slug.
published	Boolean	nein	true für Veröffentlichung, false für Entwurf. Standard: true.
detail	summary | full	nein	Detailgrad der Rückgabe.

list_submissions

Listet Einreichungen sortiert nach Aktualität auf, mit Filterfunktionen nach Scorecard, Status, Stufe und Zeitraum.

Scope: scorecards:read · idempotent

Argument	Typ	Erforderlich	Beschreibung
slug	String	nein	Auf bestimmte Scorecard eingrenzen.
status	all | completed | partial	nein	Vollständige oder abgebrochene Einreichungen. Standard: completed.
tier	String	nein	Filter nach Ergebnisstufe.
dimension	String	nein	Filter nach schwächster Dimension.
since	String	nein	Ab Datum (YYYY-MM-DD).
until	String	nein	Bis Datum (YYYY-MM-DD).
search	String	nein	Suchbegriff für Name, E-Mail oder Unternehmen.
limit	Integer	nein	Anzahl der Zeilen (Standard: 25).

get_submission

Liest eine vollständige Einreichung mit Kontaktdaten, Gesamtergebnis, Dimensionsergebnissen und Originalantworten aus.

Scope: scorecards:read · idempotent

Argument	Typ	Erforderlich	Beschreibung
submissionId	String	ja	Die ID der Einreichung laut list_submissions.