Tool-referentie

De server stelt de onderstaande tools beschikbaar. Elke tool vermeldt de vereiste OAuth-scope: een verbinding met alleen scorecards:read kan geen tools aanroepen die scorecards:write vereisen.

Als destructief aangemerkte tools overschrijven of verwijderen bestaande data. De meeste clients vragen om bevestiging alvorens deze uit te voeren.

scorecard_design_guide

Raadpleeg deze handleiding vóór het bouwen of grondig aanpassen van een scorekaart. Behandelt de intake, het formuleren van niet-manipuleerbare vragen, niveau-inzichten en themakeuzes.

Scope: scorecards:read · idempotent

Parameter	Type	Verplicht	Toelichting
topics	array van strings	nee	Specifieke secties (bijv. “themes”, “questions”). Standaard alle.

list_scorecards

Geeft een overzicht van de scorekaarten op het account, inclusief slug, publicatiestatus, aantal inzendingen en goedgekeurde insluitdomeinen.

Scope: scorecards:read · idempotent

Parameter	Type	Verplicht	Toelichting
status	all | published | draft	nee	Filteren op publicatiestatus. Standaard all.

get_scorecard

Haalt een scorekaart volledig op: weergaveopties, dimensies, vragen, antwoordkeuzen en niveaubereiken.

Scope: scorecards:read · idempotent

Parameter	Type	Verplicht	Toelichting
slug	string	ja	De unieke slug van de scorekaart.

create_scorecard

Maakt een nieuw concept aan met optionele instellingen voor presentatie, branding, totaalbeoordeling, insluiten en e-mailregistratie.

Scope: scorecards:write

Parameter	Type	Verplicht	Toelichting
title	string	ja	Titel van de scorekaart zoals getoond aan deelnemers.
subtitle	string	nee	Ondertitel met doelgroep en tijdsindicatie.
slug	string	nee	Unieke URL-slug. Wordt afgeleid van de titel indien weggelaten.
idempotencyKey	string	nee	Unieke sleutel ter voorkoming van dubbele aanmaak bij herhalingen.
ctaText	string	nee	Tekst op de startknop.
version	string	nee	Interne versieaanduiding (bijv. “1.0”).
theme	default | playground | obsidian | brutalist	nee	Visueel thema.
overallTierStrategy	weakest | average	nee	Berekeningswijze van het eindresultaat: weakest (laagste dimensie) of average (gemiddelde).
tiers	array van objecten	nee	Definitie van de algemene niveaus.
emailCaptureBeforeQuestions	boolean	nee	E-mailregistratie vóór (true) of na (false) de vragen.
privacyPolicyUrl	string of null	nee	URL van het privacybeleid.
termsUrl	string of null	nee	URL van de algemene voorwaarden.
embed	object	nee	Insluitinstellingen voor iframes.
branding	object	nee	Kleurenpalet, logo en afsluitende actieknop.
emailCapture	object	nee	Instellingen van het contactformulier.
detail	summary | full	nee	Detailniveau van het antwoord (standaard summary).

update_scorecard_config

Past de algemene instellingen van een scorekaart aan zonder dimensies, vragen of antwoorden te wijzigen.

Scope: scorecards:write · destructief

Parameter	Type	Verplicht	Toelichting
slug	string	ja	Huidige slug van de te bewerken scorekaart.
newSlug	string	nee	Nieuwe slug (maakt geen doorverwijzing aan vanaf de oude URL).
title	string	nee	Nieuwe titel.
subtitle	string	nee	Nieuwe ondertitel.
ctaText	string	nee	Nieuwe tekst voor de startknop.
version	string	nee	Nieuwe versieaanduiding.
theme	default | playground | obsidian | brutalist	nee	Nieuw visueel thema.
overallTierStrategy	weakest | average	nee	Nieuwe strategie voor de totaalscore.
tiers	array van objecten	nee	Nieuwe algemene niveaus.
emailCaptureBeforeQuestions	boolean	nee	Moment van e-mailregistratie.
privacyPolicyUrl	string of null	nee	Nieuwe privacy-URL.
termsUrl	string of null	nee	Nieuwe voorwaarden-URL.
embed	object	nee	Gewijzigde insluitinstellingen.
branding	object	nee	Gewijzigde merkkleuren.
emailCapture	object	nee	Gewijzigde contactvelden.
detail	summary | full	nee	Detailniveau van het antwoord.

add_dimension

Voegt een beoordelingsdimensie toe aan de scorekaart.

Scope: scorecards:write

Parameter	Type	Verplicht	Toelichting
slug	string	ja	De slug van de scorekaart.
label	string	ja	Naam van de dimensie.
shortLabel	string	nee	Verkorte aanduiding voor grafiekassen.
key	string	nee	Permanente unieke sleutel van de dimensie.
detail	summary | full	nee	Detailniveau van het antwoord.

add_questions

Voegt alle vragen van een dimensie in één handeling toe. Antwoordkeuzen moeten gescoord zijn en geordend van slecht naar goed.

Scope: scorecards:write

Parameter	Type	Verplicht	Toelichting
slug	string	ja	De slug van de scorekaart.
dimensionKey	string	ja	Sleutel van de bijbehorende dimensie.
questions	array van objecten	ja	Geordende lijst met vragen (advies: 3 tot 5).
detail	summary | full	nee	Detailniveau van het antwoord.

add_question

Voegt een enkele vraag toe aan een bestaande dimensie.

Scope: scorecards:write

Parameter	Type	Verplicht	Toelichting
slug	string	ja	De slug van de scorekaart.
dimensionKey	string	ja	Sleutel van de dimensie.
text	string	ja	Vraagstelling.
answers	array van objecten	nee	Gescoorde antwoordopties.
detail	summary | full	nee	Detailniveau van het antwoord.

set_dimension_tiers

Stelt de niveaus in voor een specifieke dimensie (benaming en inzichttekst), van laag naar hoog.

Scope: scorecards:write · destructief, idempotent

Parameter	Type	Verplicht	Toelichting
slug	string	ja	De slug van de scorekaart.
dimensionKey	string	ja	Sleutel van de dimensie.
tiers	array van objecten	ja	Oplopend geordende niveaus (meestal drie).
detail	summary | full	nee	Detailniveau van het antwoord.

update_dimension

Wijzigt de naam, korte naam, weging of volgorde van een dimensie. De unieke sleutel blijft onveranderd.

Scope: scorecards:write · destructief, idempotent

Parameter	Type	Verplicht	Toelichting
slug	string	ja	De slug van de scorekaart.
dimensionKey	string	ja	Sleutel van de te bewerken dimensie.
label	string	nee	Nieuwe volledige naam.
shortLabel	string	nee	Nieuwe korte naam.
weight	integer	nee	Relatieve weging bij de totaalscore.
position	integer	nee	Nieuwe positie (startend bij 0).
detail	summary | full	nee	Detailniveau van het antwoord.

update_question

Past de formulering, antwoordkeuzen of volgorde van een vraag aan.

Scope: scorecards:write · destructief, idempotent

Parameter	Type	Verplicht	Toelichting
slug	string	ja	De slug van de scorekaart.
questionId	string	ja	Uniek ID van de vraag.
text	string	nee	Nieuwe vraagstelling.
answers	array van objecten	nee	Nieuwe antwoordopties en scores.
position	integer	nee	Nieuwe positie binnen de dimensie.
detail	summary | full	nee	Detailniveau van het antwoord.

remove_question

Verwijdert een vraag uit een dimensie en herberekent automatisch de niveaubereiken.

Scope: scorecards:write · destructief

Parameter	Type	Verplicht	Toelichting
slug	string	ja	De slug van de scorekaart.
questionId	string	ja	ID van de te verwijderen vraag.
detail	summary | full	nee	Detailniveau van het antwoord.

remove_dimension

Verwijdert een complete dimensie en alle daaronder vallende vragen.

Scope: scorecards:write · destructief

Parameter	Type	Verplicht	Toelichting
slug	string	ja	De slug van de scorekaart.
dimensionKey	string	ja	Sleutel van de te verwijderen dimensie.
detail	summary | full	nee	Detailniveau van het antwoord.

check_scorecard

Controleert of een scorekaart voldoet aan alle publicatievoorwaarden en rapporteert verbeterpunten.

Scope: scorecards:read · idempotent

Parameter	Type	Verplicht	Toelichting
slug	string	ja	De slug van de scorekaart.

publish_scorecard

Zet een scorekaart live of haalt deze terug naar conceptstatus.

Scope: scorecards:write · destructief, idempotent

Parameter	Type	Verplicht	Toelichting
slug	string	ja	De slug van de scorekaart.
published	boolean	nee	true voor publiceren, false voor concept.
detail	summary | full	nee	Detailniveau van het antwoord.

list_submissions

Toont inzendingen gesorteerd op datum, met filters voor scorekaart, afrondingsstatus, niveau of periode.

Scope: scorecards:read · idempotent

Parameter	Type	Verplicht	Toelichting
slug	string	nee	Beperken tot een specifieke scorekaart.
status	all | completed | partial	nee	Voltooide of afgebroken inzendingen.
tier	string	nee	Filteren op behaald totaalniveau.
dimension	string	nee	Filteren op zwakste dimensie.
since	string	nee	Vanaf datum (JJJJ-MM-DD).
until	string	nee	Tot datum (JJJJ-MM-DD).
search	string	nee	Zoeken op naam, e-mail of bedrijfsnaam.
limit	integer	nee	Aantal regels (standaard 25).

get_submission

Haalt een inzending integraal op: contactgegevens, totaalresultaat, scores per as en de exacte antwoorden zoals destijds ingevuld.

Scope: scorecards:read · idempotent

Parameter	Type	Verplicht	Toelichting
submissionId	string	ja	Uniek ID van de inzending.