Tool reference

The server exposes the tools below. Each one names the OAuth scope it needs: a connection granted only scorecards:read cannot call a tool marked scorecards:write.

Destructive tools overwrite or remove something that already exists. Most clients ask you to confirm before running one.

scorecard_design_guide

Read this before building or substantially editing a scorecard. It covers what to ask the user before starting, how to write questions nobody can game, how to write tier insights worth reading, and how to choose between the visual themes. Ask for a single topic when you only need one — “themes” for the look, “questions” for phrasing.

Scope: scorecards:read · idempotent

Argument	Type	Required	Description
topics	array of string	no	Which sections to return. Omit for all of them.

list_scorecards

List the scorecards on this account, with their slug, publication status, how many people have submitted, and where each one is allowed to be embedded. Use the slug from this list to address any other tool.

Scope: scorecards:read · idempotent

Argument	Type	Required	Description
status	all | published | draft	no	Filter by publication status. Defaults to all.

get_scorecard

Read one scorecard in full: its presentation/configuration, dimensions, questions, answer options, and tier bands. Use this before editing or to copy supported configuration into another scorecard.

Scope: scorecards:read · idempotent

Argument	Type	Required	Description
slug	string	yes	The scorecard slug, as returned by list_scorecards.

create_scorecard

Create a new draft with optional presentation, branding, scoring-tier, embed, legal, and email-capture configuration. Omitted settings keep sensible defaults. Content starts empty: add each dimension with add_dimension, its questions in one add_questions call, then its bands with set_dimension_tiers, then check_scorecard and publish_scorecard. Read scorecard_design_guide first if you have not.

Scope: scorecards:write

Argument	Type	Required	Description
title	string	yes	The scorecard title shown to respondents, e.g. “How CLEAR Is Your Technical Leadership?”.
subtitle	string	no	One line explaining who it is for and how long it takes.
slug	string	no	Optional unique lowercase URL slug. Derived from the title and suffixed if omitted; an explicitly supplied slug must be available.
idempotencyKey	string	no	Optional caller-chosen key that makes this call safe to retry. Repeating a create with the same key within 24 hours returns the scorecard the first call made instead of creating a second one. Use it whenever a retry is possible.
ctaText	string	no	Button text shown before the questionnaire starts.
version	string	no	Your own version label for this scorecard, such as “1.0”. Not shown to respondents.
theme	default | playground | obsidian | brutalist	no	The visual personality: typography, corner radius, shadow, texture and motion. “default” is neutral and sits quietly inside an existing site; “playground” is bubbly and candy-coloured for consumer audiences; “obsidian” is editorial and premium for executive and high-ticket B2B; “brutalist” is raw monospace for developer and security audiences. This is independent of branding.colors, which sets the palette. Plans gate which themes an account may use. Call scorecard_design_guide with topics: [“themes”] for what each one signals and which are available here, and ask the user rather than choosing for them.
overallTierStrategy	weakest | average	no	How the headline result is derived from the per-dimension bands. “weakest” reports the lowest band the respondent landed in, which suits diagnostics where the bottleneck is the story; “average” reports the mean, which suits maturity models where the overall level is.
tiers	array of object	no	The overall result-tier presentation. Supplying this replaces the complete tier palette.
emailCaptureBeforeQuestions	boolean	no	Whether the email gate comes before the questions instead of after. After (false) is the default and converts better, because the respondent has already invested effort.
privacyPolicyUrl	string or null	no	A full HTTP(S) URL, or null to clear the current value.
termsUrl	string or null	no	A full HTTP(S) URL, or null to clear the current value.
embed	object	no	Third-party iframe settings. Omitted members remain unchanged. addOrigin appends one origin and keeps every origin already on the list; allowedOrigins replaces the list.
branding	object	no	Results CTA, logo, email note, and palette. Omitted members remain unchanged; logo null clears it.
emailCapture	object	no	Contact screen copy and fields. Supplying fields replaces the complete field list.
detail	summary | full	no	How much of the scorecard to return. “summary” (the default) gives counts and the dimension touched; “full” adds every dimension. Prefer the default while building — the whole tree is rarely needed and costs tokens on every step.

update_scorecard_config

Patch an existing draft or published scorecard without changing its dimensions, questions, answers, dimension tiers, or submissions. Omitted fields remain unchanged. privacyPolicyUrl, termsUrl, and branding.logo accept null to clear them. A newSlug rename does not create a redirect: the former public URL stops resolving. embed.addOrigin appends one origin and keeps the rest; embed.allowedOrigins replaces the list. The result is a summary — call get_scorecard for the full document.

Scope: scorecards:write · destructive

Argument	Type	Required	Description
slug	string	yes	Current slug of the scorecard to edit.
newSlug	string	no	Optional new unique slug. No redirect is created; the former public URL stops resolving.
title	string	no	The scorecard title shown to respondents.
subtitle	string	no	One line under the title saying who this is for and how long it takes.
ctaText	string	no	Button text shown before the questionnaire starts.
version	string	no	Your own version label for this scorecard, such as “1.0”. Not shown to respondents.
theme	default | playground | obsidian | brutalist	no	The visual personality: typography, corner radius, shadow, texture and motion. “default” is neutral and sits quietly inside an existing site; “playground” is bubbly and candy-coloured for consumer audiences; “obsidian” is editorial and premium for executive and high-ticket B2B; “brutalist” is raw monospace for developer and security audiences. This is independent of branding.colors, which sets the palette. Plans gate which themes an account may use. Call scorecard_design_guide with topics: [“themes”] for what each one signals and which are available here, and ask the user rather than choosing for them.
overallTierStrategy	weakest | average	no	How the headline result is derived from the per-dimension bands. “weakest” reports the lowest band the respondent landed in, which suits diagnostics where the bottleneck is the story; “average” reports the mean, which suits maturity models where the overall level is.
tiers	array of object	no	The overall result-tier presentation. Supplying this replaces the complete tier palette.
emailCaptureBeforeQuestions	boolean	no	Whether the email gate comes before the questions instead of after. After (false) is the default and converts better, because the respondent has already invested effort.
privacyPolicyUrl	string or null	no	A full HTTP(S) URL, or null to clear the current value.
termsUrl	string or null	no	A full HTTP(S) URL, or null to clear the current value.
embed	object	no	Third-party iframe settings. Omitted members remain unchanged. addOrigin appends one origin and keeps every origin already on the list; allowedOrigins replaces the list.
branding	object	no	Results CTA, logo, email note, and palette. Omitted members remain unchanged; logo null clears it.
emailCapture	object	no	Contact screen copy and fields. Supplying fields replaces the complete field list.
detail	summary | full	no	How much of the scorecard to return. “summary” (the default) gives counts and the dimension touched; “full” adds every dimension. Prefer the default while building — the whole tree is rarely needed and costs tokens on every step.

add_dimension

Add a scoring dimension to a scorecard. Each dimension is scored independently and gets its own tier bands. Create the dimension first, then add its questions.

Scope: scorecards:write

Argument	Type	Required	Description
slug	string	yes	The scorecard slug.
label	string	yes	The dimension name, e.g. “Clarity on Scope”.
shortLabel	string	no	A short form used on the results chart, e.g. “Clarity”. Derived from the label when omitted.
key	string	no	Optional stable key. Derived from the label when omitted, and suffixed if already taken.
detail	summary | full	no	How much of the scorecard to return. “summary” (the default) gives counts and the dimension touched; “full” adds every dimension. Prefer the default while building — the whole tree is rarely needed and costs tokens on every step.

add_questions

Add every question for one dimension in a single call. This is the normal way to build a dimension; add_question exists for adding one to a dimension already built. By default a question is scored: answers must be distinct options ordered from worst to best, and four options is the house style. Tier bands are recalculated automatically, so never set them by hand after this. Set a question’s type to “open” for a free-text question instead — it takes no answers and is excluded from scoring.

Scope: scorecards:write

Argument	Type	Required	Description
slug	string	yes	The scorecard slug.
dimensionKey	string	yes	Which dimension the questions belong to, as returned by add_dimension or get_scorecard.
questions	array of object	yes	The questions, in the order respondents will see them. Three to five per dimension.
detail	summary | full	no	How much of the scorecard to return. “summary” (the default) gives counts and the dimension touched; “full” adds every dimension. Prefer the default while building — the whole tree is rarely needed and costs tokens on every step.

add_question

Add a question to a dimension. By default a question is scored: answers must be distinct options ordered from worst to best, and four options is the house style. Tier bands for the dimension are recalculated automatically, so never set them by hand after this. Set type to “open” for a free-text question instead — it takes no answers, is excluded from scoring, and the respondent’s own words are stored with the submission.

Scope: scorecards:write

Argument	Type	Required	Description
slug	string	yes	The scorecard slug.
dimensionKey	string	yes	Which dimension the question belongs to, as returned by add_dimension or get_scorecard.
text	string	yes	The question, phrased so every answer option is a plausible thing to admit.
type	scored | open	no	Defaults to “scored”. Use “open” for a free-text question with no answer options — it is excluded from scoring, and answers must then be omitted.
required	boolean	no	Defaults to true. Set false to let a respondent leave this question blank and still submit — for a closing “anything else?” question, for instance.
answers	array of object	no	Scored answer options; omit for an open question. Omit for a scored one to use a generic 1-4 scale, which you should then rewrite to be specific to the question.
detail	summary | full	no	How much of the scorecard to return. “summary” (the default) gives counts and the dimension touched; “full” adds every dimension. Prefer the default while building — the whole tree is rarely needed and costs tokens on every step.

set_dimension_tiers

Set the result bands for a dimension: a label and an insight for each, ordered from the weakest band to the strongest. Score ranges are derived from the dimension’s questions and are calculated for you — do not supply them.

Scope: scorecards:write · destructive, idempotent

Argument	Type	Required	Description
slug	string	yes	The scorecard slug.
dimensionKey	string	yes	Which dimension to set bands for.
tiers	array of object	yes	Bands from weakest to strongest, usually three.
detail	summary | full	no	How much of the scorecard to return. “summary” (the default) gives counts and the dimension touched; “full” adds every dimension. Prefer the default while building — the whole tree is rarely needed and costs tokens on every step.

update_dimension

Change a dimension’s label, short label, weight, or position in the scorecard. Only the fields you send are changed. The dimension key cannot be changed - it is what its questions and recorded scores are filed under. Use set_dimension_tiers for tier labels and insights.

Scope: scorecards:write · destructive, idempotent

Argument	Type	Required	Description
slug	string	yes	The scorecard slug.
dimensionKey	string	yes	The dimension to edit, as returned by get_scorecard.
label	string	no	New full label. Omit to leave it alone.
shortLabel	string	no	New short label, used where space is tight such as chart axes.
weight	integer	no	Relative weight when combining dimensions into an overall result.
position	integer	no	New zero-based position among the scorecard’s dimensions. Out-of-range values move it to the end.
detail	summary | full	no	How much of the scorecard to return. “summary” (the default) gives counts and the dimension touched; “full” adds every dimension. Prefer the default while building — the whole tree is rarely needed and costs tokens on every step.

update_question

Change a question’s wording, type, whether it’s required, answer options, or its position within its dimension. Only the fields you send are changed. Safe on a published scorecard: submissions already recorded keep the wording and scores they were given. A question id cannot be changed - remove and re-add if you need a different one.

Scope: scorecards:write · destructive, idempotent

Argument	Type	Required	Description
slug	string	yes	The scorecard slug.
questionId	string	yes	The question to edit, as returned by get_scorecard. Ids are unique across the whole scorecard, so no dimension is needed.
text	string	no	New wording. Omit to leave it alone.
type	scored | open	no	Omit to leave it alone. Switching to “open” clears any existing answers — an answers sent in the same call is ignored, since an open question has none. Switching to “scored” without sending answers restores the generic 1-4 scale.
required	boolean	no	Omit to leave it alone. false lets a respondent leave this question blank and still submit; true (or omitting it on a question that was never marked optional) requires an answer.
answers	array of object	no	Replacement answer options, worst to best. Ignored if the question is (or is becoming) open. Omit to leave them alone. Changing scores moves the dimension’s achievable span, so its tier bands are recalculated automatically.
position	integer	no	New zero-based position among its dimension’s questions. Out-of-range values move it to the end.
detail	summary | full	no	How much of the scorecard to return. “summary” (the default) gives counts and the dimension touched; “full” adds every dimension. Prefer the default while building — the whole tree is rarely needed and costs tokens on every step.

remove_question

Delete a question from its dimension. The dimension’s tier bands are recalculated, since removing a question lowers the highest score anyone can reach. Submissions already recorded keep the answers they gave to it.

Scope: scorecards:write · destructive

Argument	Type	Required	Description
slug	string	yes	The scorecard slug.
questionId	string	yes	The question to remove, as returned by get_scorecard.
detail	summary | full	no	How much of the scorecard to return. “summary” (the default) gives counts and the dimension touched; “full” adds every dimension. Prefer the default while building — the whole tree is rarely needed and costs tokens on every step.

remove_dimension

Delete a dimension and every question in it. This is the widest destructive edit available - confirm the dimension key with get_scorecard first. Submissions already recorded keep the answers and scores they were given.

Scope: scorecards:write · destructive

Argument	Type	Required	Description
slug	string	yes	The scorecard slug.
dimensionKey	string	yes	The dimension to remove, as returned by get_scorecard.
detail	summary | full	no	How much of the scorecard to return. “summary” (the default) gives counts and the dimension touched; “full” adds every dimension. Prefer the default while building — the whole tree is rarely needed and costs tokens on every step.

check_scorecard

Report whether a scorecard is ready to publish, and what is weak about it, without changing the scorecard; a usage event is recorded. Problems block publication; warnings do not, but each one is something a respondent would notice. Run this before publish_scorecard rather than discovering problems through a failed publish.

Scope: scorecards:read · idempotent

Argument	Type	Required	Description
slug	string	yes	The scorecard slug.

publish_scorecard

Make a scorecard publicly reachable, or take it back to draft. Publishing runs the full validity check: every dimension needs at least one question and a complete set of tier bands, so this is the step that tells you what is still missing.

Scope: scorecards:write · destructive, idempotent

Argument	Type	Required	Description
slug	string	yes	The scorecard slug.
published	boolean	no	True to publish, false to return it to draft. Defaults to true.
detail	summary | full	no	How much of the scorecard to return. “summary” (the default) gives counts and the dimension touched; “full” adds every dimension. Prefer the default while building — the whole tree is rarely needed and costs tokens on every step.

list_submissions

List people who have filled in your scorecards, newest first, with their overall result and per-dimension scores. Filter by scorecard, completion status, result tier, date, or a search over name, email, and company. Returns a breakdown of the matching set alongside the rows, so this answers “how are people scoring” as well as “who submitted”.

Scope: scorecards:read · idempotent

Argument	Type	Required	Description
slug	string	no	Limit to one scorecard. Omit to search across every scorecard on the account.
status	all | completed | partial	no	Partial submissions are people who started and dropped out before finishing. Defaults to completed.
tier	string	no	Only submissions whose overall result is this tier, e.g. “Firefighting”. Case-insensitive.
dimension	string	no	Only submissions whose weakest dimension is this one, given as the dimension label.
since	string	no	Only submissions on or after this date (YYYY-MM-DD).
until	string	no	Only submissions on or before this date (YYYY-MM-DD).
search	string	no	Case-insensitive substring match over email, first name, and company.
limit	integer	no	How many rows to return. Defaults to 25.

get_submission

Read one submission in full: the contact details captured, the overall result, per-dimension scores, and the exact question-and-answer the person gave, grouped by dimension. Answers are the wording shown at the time they submitted, so this stays accurate even if the scorecard has been edited since. Also returns the recorded source origin/domain and all captured contact fields, including custom fields.

Scope: scorecards:read · idempotent

Argument	Type	Required	Description
submissionId	string	yes	The submission id, as returned by list_submissions.