Give your agent a real design system: tokens, measured WCAG contrast, and rules to follow.
Scored across 12 tools
Most tools are clearly distinct: search_themes vs list_themes vs get_theme_tokens vs get_design_md each target a different stage (discover, browse, install, design rules). However, decode_url and get_design_md_for_url both read a site's stylesheets and return design information, so an agent could confuse which one to call for a site-to-design-system task.
The set mostly follows a verb_noun pattern: get_design_md, get_theme_tokens, list_themes, search_themes, verify_design_md, decode_site, decode_url. Minor deviations: css_feature and how_to_use are noun/verb-phrase style rather than verb_noun, and get_design_md_for_url is a longer variant but still consistent.
12 tools is well within the ideal range for a design-system server. Each tool maps to a distinct workflow step: discover, decode, generate DESIGN.md, install, verify, and maintain. No tool feels redundant or padding.
The workflow is well covered: search/list themes, decode a site, generate DESIGN.md, fetch tokens, install, and verify. Minor gaps: there is no tool to update or create a theme in the catalogue, and no explicit tool for comparing two decoded sites, but the core agent workflow (discover → decode → design → install → verify) is complete.
Answers two questions about a modern CSS feature with data instead of recall. First, its Baseline status (widely available, newly available, or limited availability), the date, and which core browsers lack it, read from the open web-features dataset at build time. Second, how many of CSS Crème's curated, decoded showcase sites ship it, which ones, how many of them guard it with @supports, and the exact @supports conditions they test. Also returns a fallback note where we have one, any name the feature has shipped under before (an agent that learned the old name will otherwise write it), and the documented limits that catch people out, each cited to the page it was read on. Call it before writing CSS that uses container queries, :has(), anchor positioning, @scope, view transitions, oklch(), color-mix(), light-dark(), subgrid, scroll-driven animations, @property, text-wrap and similar, so the CSS you write is accurate for today rather than for your training date. With no feature given it returns the Ship Gap: features that are safe and mostly ignored, and features that are early and shipped anyway.
| Name | Required | Description | Default |
|---|---|---|---|
| feature | No | A web-features id or a plain name: "container-queries", "has", ":has()", "anchor positioning", "oklch", "subgrid", "@scope". Omit for the whole Ship Gap summary. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive. The description adds substantial context: data is read from a build-time dataset (implying potential staleness), what fields are returned (baseline, adoption, @supports conditions, fallback, prior names, limits), and that each item is cited. This exceeds what annotations alone provide and gives the agent a clear picture of behavior without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph of roughly 150 words. It is front-loaded with the main purpose, but it could be structured (e.g., bullet points) to improve scannability. Every sentence adds information, so it's not wasteful, but it is verbose for a tool with a single optional parameter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one optional parameter and no output schema, the description covers the key behavioral aspects: what it returns, how it sources data, the no-parameter mode, and usage timing. It doesn't specify the output format, but that's not critical for a read-only lookup. The description is sufficiently complete for an agent to know when and how to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the parameter with examples and the omit behavior (100% coverage). The description repeats similar examples but doesn't add new semantic meaning beyond what the schema already conveys. Baseline of 3 applies because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool answers two specific questions about a CSS feature: Baseline status and adoption among showcase sites, with data from specific sources. It lists example features and even mentions the no-parameter Ship Gap mode. This is a precise verb+resource definition, and no sibling tool overlaps with this functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a direct usage instruction: 'Call it before writing CSS that uses...' and lists concrete examples. It also explains the alternative mode (no feature returns Ship Gap). It doesn't mention explicit exclusions, but with no competing tool, this is not a gap. Clear context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a sample of pages from one site (from its sitemap.xml, or the homepage links when there is no sitemap) and report what is CONSISTENT across them: which declared tokens, colours, font stacks, radii and spacing values appear on every page read, and which appear on only some. One page shows what a page uses; a design system is a claim about consistency, and only a sample can test it. Returns counts and the pages actually read, never a score. Use when the user asks whether a site is really on a system, or wants the system rather than one page of it.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Absolute public http(s) URL anywhere on the site. | |
| pages | No | How many pages to read, 2 to 8. Default 5. | |
| maxAge | No | How old a reused read may be, in seconds. Default 600; 0 reads the site now. A reused read keeps its own fetchedAt and says cache.hit: true. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description reveals how the tool behaves: it reads from sitemap.xml or homepage links, samples multiple pages, reports consistency counts, and 'never a score.' This adds real process-level context that annotations alone do not provide, without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences cover method, fallback behavior, what is reported, what is not reported, and the intended use case. No sentence is filler, and the most decision-relevant information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given rich annotations and a fully documented schema, the description still supplies the missing conceptual context: what 'design system' means operationally, how sampling works, and exactly what the output does and does not contain. An agent has enough to decide when to call it and what to expect, even with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all three parameters at 100% coverage, including defaults and cache semantics. The description reinforces the sampling and consistency concepts but does not add parameter-specific meaning beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: 'Read a sample of pages from one site' and 'report what is CONSISTENT across them.' The title and closing contrast with 'not one page' clearly distinguish this from page-level tools like decode_url or get_design_md_for_url, so sibling confusion is unlikely.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit trigger: 'Use when the user asks whether a site is really on a system, or wants the system rather than one page of it.' It does not name specific alternative tools or state when not to use it, but the 'rather than one page' phrasing implies the boundary clearly enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a public site's HTML and stylesheets and return what its CSS declares: named custom properties that look like design tokens, the colours it uses most, its font stacks, border radii, spacing values, and the framework it appears to be built with. Also returns a "drop" report: roughly how many words a web-to-markdown reader would carry away from this page, against the design decisions it would discard, because markdown is defined by throwing the design layer away. It reads CSS and does not render the page, so it reports a confidence ("tokens" when named properties were found, "derived" when only compiled CSS was available) and flags a JavaScript shell rather than pretending every site is equally legible. It obeys the site's robots.txt for CSSCremeBot: a disallowed path is refused with ROBOTS_DENIED, which a retry will not change. A bot challenge, a parked or for-sale domain, or a host's default page is refused with NOT_THE_SITE and the evidence, rather than measured as if it were the site. Every error starts with its code and a retry verdict (never, later, with-changes). A read is reused for up to maxAge seconds (default 600, 0 for fresh), and every result carries work: the requests it made of the site. Use when the user wants to match a site that is not in the catalogue, or has fetched a page as markdown and needs what that markdown lost.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Absolute public http(s) URL of the page to read. | |
| expect | No | Optional brand hex, like #635BFF. The json response then carries `expect`: the nearest value the site declares (a token when it has any, else a literal), its CIE76 distance, and whether that is within the same-colour tolerance, near, or different. A distance, not a grade. | |
| format | No | Default json (the measurement). Or one artefact from the same read: md (DESIGN.md), tokens (W3C DTCG tokens.json with the site's declared names by scope), css (globals.css: shadcn variables, Tailwind v4 @theme, the declared block), tailwind (v4 and v3 shapes), registry (a shadcn registry item: npx shadcn add <url>), agents (an agents.md rules block), aliases (every resolved value mapped back to the declared names that produce it, with scope), figma (a script for Figma's use_figma tool that creates a Variables collection with Light and Dark modes, built from the same mapper the CSS Crème plugin runs). | |
| maxAge | No | How old a reused read may be, in seconds. Default 600; 0 reads the site now. A reused read keeps its own fetchedAt and says cache.hit: true. | |
| expectSpec | No | Optional brand spec to check field by field, for example {"primary":"#635BFF","bg":"#FFFFFF","font":"Inter","heading":"Sohne","radius":"8px","base":"16px","spacing":"4px","darkMode":true,"tokens":{"--brand":"#635BFF"}}. The json response then carries `compliance`: per field a verdict (match, near, different, not-declared), what it was compared against, and the value found. not-declared means the site gives nothing to compare; it is never filled with the nearest guess. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds substantial behavioral detail beyond those: it reads CSS without rendering, reports confidence levels, obeys robots.txt with ROBOTS_DENIED, refuses bot challenges and parked domains with NOT_THE_SITE, returns retry verdicts, reuses reads up to maxAge, and reports the requests made. This is far more than the annotations alone provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but information-dense: every sentence introduces a distinct behavior or constraint, from robots.txt handling to retry verdicts to cache reuse. It is front-loaded with the core purpose, though the single-paragraph format with many semicolon-separated clauses makes it harder to scan than it could be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries the burden of explaining what the tool returns. It covers the measured design properties, the drop report, confidence levels, error codes and retry verdicts, cache behavior, the 'work' field, and the available format artifacts. This is sufficient for an agent to understand the tool's behavior and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents url, expect, format, maxAge, and expectSpec in detail. The description adds context about caching and the 'work' field, but it does not materially enrich parameter meaning beyond what the input schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Fetch a public site's HTML and stylesheets and return what its CSS declares,' followed by concrete outputs like custom properties, colors, font stacks, border radii, spacing, and framework. It clearly describes what the tool does, but it does not explicitly name or contrast sibling tools, so differentiation is left mostly to the reader.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description ends with an explicit use case: 'Use when the user wants to match a site that is not in the catalogue, or has fetched a page as markdown and needs what that markdown lost.' This gives clear context for when to invoke it, but it does not state when not to use it or name alternatives such as decode_site or get_design_md_for_url.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a short standing-instructions block that makes every future session read DESIGN.md before touching UI. Paste it whole into CLAUDE.md, AGENTS.md or .cursor/rules/design.mdc. It points at the DESIGN.md rather than restating it, and carries the token fingerprint so drift is detectable.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Theme or template id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior; the description adds useful output behavior by noting that the block points at DESIGN.md rather than restating it and includes a token fingerprint for drift detection. There is no contradiction with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact sentences deliver the purpose, usage, and unique output traits with no filler. The most important information about what the tool returns is front-loaded, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, read-only tool with no output schema, the description covers the return value's purpose, content strategy, and installation targets. The id meaning is covered by the schema, and sibling tools provide discovery context for valid themes or templates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single id parameter has 100% schema description coverage, so the baseline is 3. The description does not add additional meaning about valid id values or how the id affects the generated rules block, leaving the schema's 'Theme or template id' as the only guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return') and names the exact resource: a short standing-instructions block for agent config files. It also states the block's function (forcing DESIGN.md reads before UI changes) and its drift-detection trait, making it distinguishable from siblings like get_design_md or verify_design_md.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit placement guidance ('Paste it whole into CLAUDE.md, AGENTS.md or .cursor/rules/design.mdc') and frames the intended context for use. It does not enumerate when to prefer this over get_design_md or verify_design_md, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the full DESIGN.md for one theme: semantic colour roles, the complete shadcn token set in light and dark, typography, radius, spacing, MEASURED WCAG contrast ratios, and numbered rules the generated UI must follow. Read this before writing any UI. Save it at the repo root as DESIGN.md so it applies to every session.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Theme or template id, e.g. "deep-ocean". Get ids from search_themes or list_themes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the practical behavior of saving the fetched content to the repo root, and clarifies the fetched artifact is a full DESIGN.md. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, then the content inventory and a direct usage directive. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-only fetch tool, the description is complete: it states what is returned, what to do with it, and when to call it. No output schema is required because the content is described in prose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter `id` is fully documented in the schema (coverage 100%) with an example and source for valid IDs. The description only reinforces that the tool is per-theme, without adding new parameter semantics, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Statement 'Fetch the full DESIGN.md for one theme' names a specific action and resource, and the content list (semantic colors, shadcn tokens, typography, contrast ratios, rules) distinguishes it from sibling tools like get_theme_tokens and get_design_md_for_url, which serve different retrieval scopes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit call to action: 'Read this before writing any UI,' and explains the persistence step ('Save it at the repo root as DESIGN.md so it applies to every session'). It does not explicitly name alternatives or when not to use it, so it stops short of full alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the stylesheets of a public site and return a full DESIGN.md: semantic roles with the token each came from, measured WCAG contrast pairs, the tokens the site itself declares (framework internals counted separately), font families, the type scale with the ratio between steps, colour frequency, gradients, corner radii, spacing, an elevation ladder of shadows, breakpoints, the z-index ladder, interaction-state rule counts, motion, and whether a dark theme is declared. This is the artefact to hand a coding agent before it writes UI that should match a site. It reads declared CSS and does not execute JavaScript, so it reports what the stylesheets say rather than what the page renders.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Absolute public http(s) URL of the page to read. | |
| maxAge | No | How old a reused read may be, in seconds. Default 600; 0 reads the site now. A reused read keeps its own fetchedAt and says cache.hit: true. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context: it reads declared CSS, does not execute JavaScript, and reports what stylesheets say rather than what the page renders. This goes beyond annotations, though it could disclose failure modes like unreachable URLs or non-CSS sites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph that front-loads the core action and lists the output contents. Every sentence earns its place, but the long enumeration could be more scannable with bullet points or short labeled sections. It is appropriately sized given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich description and full schema coverage, the tool is well specified. With no output schema, the description explains return values in detail by listing DESIGN.md contents. The only gaps are edge-case behaviors such as failure modes for unreachable URLs or pages that require JavaScript, which an agent might need to handle.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already fully documented in the schema. The description reinforces the URL semantics and mentions cache behavior for maxAge, but it does not add substantial meaning beyond the structured schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a precise verb+resource ('Read the stylesheets of a public site and return a full DESIGN.md') and enumerates the artifact's contents in detail. It clearly distinguishes itself from siblings by specifying the full-design-md scope and the 'any public URL' target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use this tool: 'This is the artefact to hand a coding agent before it writes UI that should match a site.' It also contrasts with JavaScript rendering behavior, implying when this tool is not sufficient. Sibling names like get_design_md, get_theme_tokens, and verify_design_md provide additional context for choosing alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the exact npx shadcn@latest add <url> command that installs one theme into a shadcn/ui project, plus the registry URL it reads. Use when the user says "install it" and you already know the id.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Theme or template id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that the tool also reads a registry URL, which is extra behavioral context beyond the annotations, and it does not contradict them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste: the first states exactly what is returned, the second gives the usage condition. The core function is front-loaded, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers what it returns (command + registry URL) and when to use it. It does not discuss error cases or format details, but given the tool's simplicity and annotation coverage, this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the `id` parameter is described as 'Theme or template id.'). The description adds no further semantic detail about the parameter beyond repeating that the id must be known, so it stays at the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Return') and resource (the `npx shadcn@latest add <url>` install command) and even gives the exact command format. It clearly distinguishes itself from siblings like `list_themes` or `get_theme_tokens` by focusing solely on producing the install command.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides an explicit trigger condition: 'Use when the user says "install it" and you already know the id.' This is clear context but does not mention alternatives or when not to use it, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the shadcn/ui registry item (OKLCH tokens, light and dark) plus the paste-ready CSS variables for one theme, and the one-line command that installs it for real. Use after get_design_md when you are ready to write the tokens into globals.css.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Theme or template id. | |
| format | No | Default both. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds real contextual value by detailing the output contents (OKLCH tokens, light/dark, paste-ready CSS, install command). It does not contradict the annotations and requires no additional side-effect warnings.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with what the tool returns and ending with when to use it. There is no filler or repetition of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with a simple schema, the description sufficiently explains the returned artifacts despite no output schema. The only gap is not disambiguating its included install command from the sibling get_install_command.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline applies; id and format are already documented, including enum and default. The description reinforces that results are for a single theme but does not add param-level details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('get') and names the exact resource: shadcn/ui registry item, OKLCH tokens light/dark, CSS variables, and install command for one theme. It disambiguates from list/search siblings by emphasizing 'one theme' and from get_design_md by indicating it is the follow-up token-writing step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to use after get_design_md and precisely when ('when you are ready to write the tokens into globals.css'). It does not, however, contrast with get_install_command or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explains where a DESIGN.md belongs for a given coding agent (Claude Code, Cursor, v0, Codex, Lovable) so the design rules apply to every session rather than one message.
| Name | Required | Description | Default |
|---|---|---|---|
| tool | No | claude-code | cursor | v0 | codex | lovable |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about the specific agents and the benefit of session-wide persistence, but does not add new behavioral details beyond confirming it is an explanation. This is consistent with annotations and adds modest value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence, front-loaded with the verb 'Explains' and the object. Every phrase earns its place: the agent list and the session-vs-message contrast are directly useful. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple instructional tool with one parameter, no output schema, and annotations that already convey idempotency and read-only behavior, the description is fully adequate. An agent can understand what it does, who it applies to, and why it matters without needing more information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema doc for the 'tool' parameter is complete (100% coverage) and already enlists the five possible values. The description repeats that same list without adding further detail on syntax, defaults, or usage, so it does not go beyond the schema. Per the rubric, baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'Explains' and names the exact resource ('where a DESIGN.md belongs for a given coding agent'), with a specific list of agents (Claude Code, Cursor, v0, Codex, Lovable). It clearly differentiates itself from sibling tools like get_design_md or get_agent_rules by focusing on placement/installation rather than retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly communicates its purpose and scope (which agents it covers and the outcome of applying design rules across sessions), which gives strong context for when to use it. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5 but is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Browse the full catalogue of curated themes and templates. Use when the user wants to see options rather than search for one.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| mode | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds that this is a browsing/catalogue operation, but it does not explain important behaviors like the fact that results can be filtered by kind or mode, or what the returned catalogue contains. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The action is front-loaded ('Browse the full catalogue'), followed by a crisp usage condition. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with optional parameters and no required fields, the description covers the core intent. However, it does not explain how the parameters affect results, that both are optional, or what the output looks like. Given the absence of an output schema and parameter descriptions, this is an adequate but incomplete definition.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not mention the parameters at all. The enum values like 'theme', 'template', 'light', and 'dark' give some self-evident meaning, but the description should clarify that kind and mode are optional filters. The description fails to compensate for the lack of parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the resource and action: 'Browse the full catalogue of curated themes and templates.' It distinguishes itself from searching by saying it is for when the user wants to 'see options rather than search for one.' The title and description align well enough with the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage context: 'Use when the user wants to see options rather than search for one.' This implies the alternative of searching, but does not explicitly name search_themes or provide any when-not-to-use guidance. It is clear but lacks an explicit alternative reference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find a design system by describing what you are building ("dark developer tool", "calm fintech dashboard", "playful consumer app"). Returns matching themes with their DESIGN.md URL and shadcn install command. Call this first when the user has no design system defined.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Curated palette theme, full page template, or either. Default any. | |
| mode | No | Preferred light or dark. Default any. | |
| limit | No | Max results, 1-25. Default 8. | |
| query | Yes | Free text: mood, industry, colour, or use case. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, non-mutating operation. The description adds value by specifying the return payload (matching themes with DESIGN.md URL and install command), which is not implied by the annotations. This covers what an agent needs to know about behavior without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The first sentence establishes purpose and gives examples; the second explains the return value and the optimal usage scenario. Every clause earns its place, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool with one required parameter and full schema coverage, the description covers all essentials: what it does, how to phrase the query, what it returns, and when to use it. The output schema is absent, but the description states the return format sufficiently. No critical information is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all four parameters (query, kind, mode, limit) with meanings and defaults. The description adds concrete examples ('dark developer tool', 'calm fintech dashboard') that illustrate how to phrase the query, which goes beyond the schema's 'Free text: mood, industry, colour, or use case.' This added context helps the agent construct effective queries.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Find') and resource ('design system') and clarifies how to use it ('by describing what you are building'). It also mentions what it returns (matching themes with DESIGN.md URL and shadcn install command), which distinguishes it from siblings like list_themes and get_design_md. The phrase 'Call this first' implies a distinct role among the tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'Call this first when the user has no design system defined.' This gives a clear condition and implies when not to use it (when a design system is already defined). It doesn't name a specific alternative tool, but the sibling list includes list_themes, which would be the natural fallback, so the guidance is sufficient though not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every DESIGN.md carries a Fingerprint line. Pass the id and that fingerprint; the server answers whether the copy matches the current token set, and if not, returns the current tokens so the agent can update the file instead of following a stale one. Call this at the start of a session when a DESIGN.md is already in the repo.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Theme or template id from the DESIGN.md Source line. | |
| fingerprint | Yes | The value from the DESIGN.md Fingerprint line, e.g. "fnv1a-9c2a41d7". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it explains that if the fingerprint does not match, the server returns the current tokens so the agent can update the file, and it clarifies the matching mechanism. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each earning its place: it explains the fingerprint mechanism, states what the server returns, and gives the usage trigger. Information is front-loaded and there is no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple verification tool with two well-documented parameters, no output schema, and supportive annotations, the description is complete. It explains the input source, the behavior (match/stale), the return value (current tokens when stale), and the recommended usage time. An agent has everything needed to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters well-documented (id from Source line, fingerprint from Fingerprint line with example). The description reinforces the parameter roles but does not add meaning beyond what the schema already provides. According to calibration, baseline 3 is appropriate when the schema carries the semantic load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to verify whether a DESIGN.md copy is current by checking its fingerprint against the server's current token set. It uses a specific verb ('verify') and resource ('DESIGN.md copy'), and it is easily distinguishable from siblings like get_design_md (which likely fetches) and get_theme_tokens (which retrieves tokens directly).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit trigger condition: 'Call this at the start of a session when a DESIGN.md is already in the repo.' This gives clear context for when to use the tool, though it does not explicitly name alternative tools or state when not to use it. The guidance is adequate for correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
decode_site1 field changedInput schema / properties / maxAgeAdded value: +{
+ "description": "How old a reused read may be, in seconds. Default 600; 0 reads the site now. A reused read keeps its own fetchedAt and says cache.hit: true.",
+ "maximum": 3600,
+ "minimum": 0,
+ "type": "integer"
+}decode_url2 fields changedInput schema / properties / expectSpecAdded value: +{
+ "description": "Optional brand spec to check field by field, for example {\"primary\":\"#635BFF\",\"bg\":\"#FFFFFF\",\"font\":\"Inter\",\"heading\":\"Sohne\",\"radius\":\"8px\",\"base\":\"16px\",\"spacing\":\"4px\",\"darkMode\":true,\"tokens\":{\"--brand\":\"#635BFF\"}}. The json response then carries `compliance`: per field a verdict (match, near, different, not-declared), what it was compared against, and the value found. not-declared means the site gives nothing to compare; it is never filled with the nearest guess.",
+ "type": "object"
+}Input schema / properties / maxAgeAdded value: +{
+ "description": "How old a reused read may be, in seconds. Default 600; 0 reads the site now. A reused read keeps its own fetchedAt and says cache.hit: true.",
+ "maximum": 3600,
+ "minimum": 0,
+ "type": "integer"
+}get_design_md_for_url1 field changedInput schema / properties / maxAgeAdded value: +{
+ "description": "How old a reused read may be, in seconds. Default 600; 0 reads the site now. A reused read keeps its own fetchedAt and says cache.hit: true.",
+ "maximum": 3600,
+ "minimum": 0,
+ "type": "integer"
+}css_featuredecode_sitedecode_urlget_agent_rulesget_design_mdget_design_md_for_urlget_install_commandget_theme_tokenshow_to_uselist_themessearch_themesverify_design_mdServes your design system and coding standards to coding agents, so they stop guessing.
Build and manage your design system with AI: tokens, themes, components, icons, Figma and code.
Live React design-system APIs, patterns, and code validation so AI agents build real UI, not slop.
Hand-crafted UI components and design systems for agents, so builds don't look like AI slop.
Add one secure layer between your agents and this server.
