Designesy

Validate DTCG tokens

designesy_tokens_score

Read-onlyIdempotent

Validate a design token file against the W3C Design Tokens Community Group (DTCG) 2025.10 Final Community Group Report (the spec's first stable version, published Oct 28 2025 as a Candidate Recommendation and considered stable). Returns 10 conformance checks (t01-t10) with PASS, FAIL, WARN or SKIP. Use this to verify a tokens.json (or any DTCG token export) is structurally correct: $type (direct or inherited) present, one $value or $ref per token (a JSON Pointer $ref must resolve), structured colors (colorSpace + components rather than bare hex), dimensions in the 2025.10 { value, unit } form, and a $schema pointer to designtokens.org (a Designesy policy: DTCG does not require $schema). With 84% of teams now using design tokens (zeroheight Design Systems Report 2025, up from 56% in 2024) and the spec finally stable, every adopting team needs a validator. When NOT to use: for scoring a whole live site (not just its token file), use designesy_score. Executable: fetches the URL or parses the raw JSON you provide, runs 10 checks server-side. No browser needed. Score: PASS=1, WARN=0.5, FAIL=0, SKIP is not scored; points / scored checks x 100. Returns JSON: { contract_id, contract_version, contract_status, url, total_tokens, score (0-100), grade (A-F), pass_count, fail_count, warn_count, skip_count, scoring, checks[{id (t01-t10), name, status (PASS, FAIL, WARN or SKIP), detail}], provenance, validator_note }. Pass url to fetch a remote token file, or dtcg_file to validate an inline JSON string. Provide exactly one.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "designesy_tokens_score"
  }
}

Input Schema

Name	Required	Description	Default
`url`	No	URL to a DTCG token file (JSON) of up to 4 MiB. The tool fetches and validates it; a longer file fails with an error that names the limit.
`dtcg_file`	No	Raw DTCG token JSON string to validate (alternative to url).

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 26, 2026

changedInput schema / properties / url / description

Previous value: -"URL to a DTCG token file (JSON). The tool fetches and validates it."New value: +"URL to a DTCG token file (JSON) of up to 4 MiB. The tool fetches and validates it; a longer file fails with an error that names the limit."

Changed2 schema fields changedAug 3, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

removedInput schema / additionalProperties
```
Removed value: -false
```

First observedJul 29, 2026

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes beyond the readOnly/idempotent/openWorld annotations by disclosing the execution model ('fetches the URL or parses the raw JSON you provide, runs 10 checks server-side. No browser needed'), the scoring rules (PASS=1, WARN=0.5, FAIL=0, SKIP unscored), and the designtokens.org $schema policy quirk. It does not mention failure modes beyond the 4 MiB case already in the schema, so it stops short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded and the when-NOT-to-use clause is well placed, but the opening is padded with spec history and a self-contradicting gloss ('Final Community Group Report ... as a Candidate Recommendation'), and the '84% of teams' adoption statistic earns no place in a tool definition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by enumerating the return object fields (score, grade, checks[], provenance) and the scoring formula. For a validator returning a 10-check array, an agent has everything needed to interpret results without guessing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds a constraint the schema does not encode: the two parameters are mutually exclusive and exactly one must be supplied. The schema itself permits both or neither, so this sentence carries real semantic weight.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Validate a design token file against the W3C DTCG 2025.10 spec') and explicitly distinguishes itself from the sibling that handles live sites, designesy_score. An agent can identify the tool and its scope without reading the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a positive use case ('Use this to verify a tokens.json is structurally correct'), an explicit exclusion with a named alternative ('When NOT to use: for scoring a whole live site, use designesy_score'), and the calling constraint 'Pass url ... or dtcg_file ... Provide exactly one.'

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Designesy tools Inspect

Try in Browser

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.