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 · read-only, 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, and how many people have submitted. Use the slug from this list to address any other tool.

Scope: scorecards:read · read-only, 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 · read-only, 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 dimensions and questions next, then publish.

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
theme	default | playground | obsidian | brutalist	no
overallTierStrategy	weakest | average	no
tiers	array of object	no	The overall result-tier presentation. Supplying this replaces the complete tier palette.
emailCaptureBeforeQuestions	boolean	no
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.
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.

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
subtitle	string	no
ctaText	string	no	Button text shown before the questionnaire starts.
version	string	no
theme	default | playground | obsidian | brutalist	no
overallTierStrategy	weakest | average	no
tiers	array of object	no	The overall result-tier presentation. Supplying this replaces the complete tier palette.
emailCaptureBeforeQuestions	boolean	no
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.
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. Answers must be distinct, scored 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.

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. Answers must be distinct, scored options ordered from worst to best; four options is the house style. Tier bands for the dimension are recalculated automatically, so never set them by hand after this.

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.
answers	array of object	no	Scored answer options. Omit 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, its 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.
answers	array of object	no	Replacement answer options, worst to best. 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 anything. 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 · read-only, 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 · read-only, 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.

Scope: scorecards:read · read-only, idempotent

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