Design quality gate for AI-generated UI: score any URL on 45 deterministic checks, A–F grade.
Scored across 17 tools
The set has many score-oriented tools (score, drift_score, readiness_score, monitor_score, motion_score, tokens_score, a11y_score), but most are scoped to clearly different inputs or artifacts and the descriptions include explicit 'When NOT to use' cross-references. A few names still invite hesitation—especially the generic designesy_score vs. designesy_report and designesy_a11y_score, which does not actually run a scan despite its name.
All tools use a consistent designesy_ prefix and snake_case, with a recognizable _score suffix for scoring tools. The set is not a strict verb_noun pattern, though: some names are resource-like nouns (catalog, contract), one is a verb (compare), and abbreviations like a11y, llms, and md are mixed in.
17 tools is slightly above the typical well-scoped range, but the server genuinely spans several distinct capabilities: contract reference, URL scoring, drift monitoring, token validation, motion validation, accessibility, comparison, guardrails, and discovery documents. Each tool earns a place, though a few reference/export tools could arguably be consolidated.
The surface is broad and covers the major design-system intelligence lifecycle: discovery, contract retrieval, scoring, drift, readiness, monitoring, token and motion validation, comparison, guardrails, and reporting. Minor gaps remain, such as no generic tool to fetch an arbitrary published package by id and no server-side accessibility scan execution, but the core audit and reference workflows are well covered.
Get the Designesy WCAG 2.2 AA accessibility verification framework: 11 conformance checks (a01-a11) plus a ready-to-run Playwright + axe-core 4.13.0 script template targeting your URL. Use this to audit a site for accessibility violations. When NOT to use: for a full design-contract score (not just a11y), use designesy_score. Does NOT run the scan: axe-core needs a real browser DOM. Returns the 11 checks + a Playwright script you execute locally (npm i -D @axe-core/playwright). The score comes from your local run, not from this tool. Returns JSON: { checks[{id (a01-a11), name, status: "PENDING_EXECUTION"}], playwright_script, install_command, run_command }. Pass config (JSON string) to customize axe.configure(), for example with branding overrides or rule disables. Omit for standard WCAG 2.2 AA.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | URL to scan for accessibility. The returned script template will target this URL. | |
| config | No | Brand customization JSON for axe.configure(): branding, checks, rules, disableOtherRules. | |
| ruleset | No | Ruleset tag (default: wcag22aa). Options: wcag2a, wcag2aa, wcag21aa, wcag22aa, best-practice. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safe read-only, idempotent profile, but the description adds critical non-obvious behavior: it does NOT run the scan, axe-core needs a real browser DOM, and the score comes from a local run rather than the tool. It also discloses the install prerequisite (npm i -D @axe-core/playwright) and that returned checks are PENDING_EXECUTION — none of which the annotations convey.
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?
Front-loads the deliverable and constraints effectively, and every sentence carries information. There is mild redundancy in stating twice that the tool returns the checks plus a Playwright script (once in prose, once in the JSON shape), but the structure is otherwise tight and scannable.
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?
With no output schema, the description fully compensates by spelling out the return shape ({checks[{id,name,status}], playwright_script, install_command, run_command}) and the PENDING_EXECUTION status. For a tool whose real execution happens locally, this is complete enough to call 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 coverage is 100%, so the baseline is 3. The description goes further by explaining the purpose of `config` (customizes axe.configure(), e.g. branding overrides or rule disables) and that omitting it yields standard WCAG 2.2 AA, adding practical meaning beyond the schema's field descriptions.
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?
States a specific verb (Get) and resource (WCAG 2.2 AA accessibility verification framework), enumerates the concrete deliverable (11 checks a01-a11 plus a Playwright + axe-core script template targeting the URL), and explicitly contrasts itself with the sibling designesy_score. An agent can distinguish this from the other designesy_* scoring tools without opening any schema.
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?
Gives an explicit when-to-use ('audit a site for accessibility violations') and a when-NOT-to-use with the named alternative ('for a full design-contract score (not just a11y), use designesy_score'). Routing between siblings is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the Designesy agent discovery document (/.well-known/agent.json) as reference data: the org identity, authority, discovery endpoints, package index, machine exports, permission policy, contact, and citation templates. Use this when integrating with or enumerating Designesy and need the canonical discovery manifest rather than one specific contract. When NOT to use: for the package list, use designesy_catalog (lighter); for the contract, use designesy_contract. Read-only: no side effects. Returns JSON: { kind: "published_document", source_url, media_type: "application/json", note, omitted_fields[], document }, where document is the published object (schema, name, identity, authority, topics, discovery, ingest, packages, machine_exports, contact, permission, cite, and the rest) with any field written as steps for an AI agent (such as ingest.steps) removed and its path listed in omitted_fields. No parameters.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, and the description reinforces 'Read-only: no side effects' without contradicting them. It adds a genuinely non-obvious behavioral trait: fields written as agent steps (e.g. ingest.steps) are stripped from the returned document and their paths reported in omitted_fields. That disclosure is beyond what annotations convey.
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?
Front-loaded with purpose and usage before any return detail, and the when-not-to-use clause is placed early where it is most useful. The long enumeration of document fields is verbose but largely earns its place because no output schema exists; a tighter summary of the return shape would read better.
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?
With no output schema, the description carries the return contract itself, naming the output object's fields (kind, source_url, media_type, note, omitted_fields, document) and the shape of the nested document. Combined with the sibling routing guidance, an agent has everything needed to call and interpret this tool.
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 tool takes zero parameters and the description states this explicitly ('No parameters'), which is the correct baseline for a parameterless tool. There is nothing further to disambiguate.
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?
States a concrete verb and resource (get the /.well-known/agent.json discovery manifest) plus its scope (org identity, authority, endpoints, package index, policy, contact, citations). It explicitly contrasts itself with designesy_catalog and designesy_contract, so an agent can route without opening either schema.
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?
Gives both a positive trigger ('when integrating with or enumerating Designesy and need the canonical discovery manifest rather than one specific contract') and an explicit negative trigger with named alternatives for the package list and the contract. Routing is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the 23 published Designesy packages with versions, URLs, and statuses. Use this to discover what Designesy publishes before fetching a specific contract. When NOT to use: if you already know which package you need, skip this and call designesy_contract directly. Read-only: no side effects. Returns JSON: { package_count, packages[{id, kind, title, version, status, human_url, machine_url}], standing_rules[], machine_exports[] }. No parameters: accepts empty input.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The read-only/no-side-effects statement largely duplicates the readOnlyHint and destructiveHint=false annotations, earning no extra credit. What the description does add is non-redundant: the exact cardinality (23 packages) and the full return shape, which matters because no output schema exists. It stops short of describing ordering or whether the list can change over time, so it is strong but not exhaustive.
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?
It is front-loaded with purpose, then usage, then the exclusion rule, then behavior and return shape. Every sentence carries distinct information; the return-shape sentence earns its place precisely because no output schema is defined.
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 parameterless, read-only listing tool with no output schema, the description supplies everything an agent needs: the payload contents, exact count, safety profile, return keys, and the routing rule to the sibling contract tool. Nothing material is missing.
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?
With zero parameters the baseline is 4, and the description confirms this explicitly ('No parameters: accepts empty input'), removing any doubt about whether input is required. There is no further parameter meaning to add.
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 ('List the 23 published Designesy packages') and immediately enumerates the payload fields (versions, URLs, statuses). It also explicitly contrasts itself with the sibling designesy_contract, so an agent can distinguish the discovery tool from the detail-fetch tool without opening either schema.
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 an explicit when-to-use ('discover what Designesy publishes before fetching a specific contract') and an explicit when-NOT-to-use ('if you already know which package you need, skip this and call designesy_contract directly'). The alternative is named, not merely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Diff two design systems from live URLs, using the only URL-scoped design-token diff engine. Fetches both URLs in parallel, extracts their :root custom properties, and produces a structured diff across 8 dimensions: tokens added (in A not B), removed (in B not A), renamed (heuristic Levenshtein ≤ 2), value-changed (same name, different value), scale-stop-changed (spacing/radius/color scale steps), contrast-drift-per-pair (WCAG contrast ratio change for shared color tokens), structure-delta (token count + category distribution), and score-delta (runs /score on both URLs and diffs). Use this to answer "what actually changed between two design systems" or "how does our design system differ from a reference". When NOT to use: for single-site drift detection, use designesy_drift_score; for continuous monitoring, use designesy_monitor_score. Executable: fetches both URLs, extracts CSS + tokens, computes diff. No browser needed. Returns JSON: { ok, urlA, urlB, score (0-100, diff completeness), grade, pass, warn, fail, total, tokensA, tokensB, added[], removed[], renamed[], valueChanged[], scaleDiff, structureDelta, contrastDrift[], scoreDelta, checks[] }. Results cached ~24h per URL pair.
| Name | Required | Description | Default |
|---|---|---|---|
| urlA | Yes | First URL to compare (e.g. your design system). | |
| urlB | Yes | Second URL to compare (e.g. a reference or competitor). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint). The description goes further by disclosing execution mechanics ('fetches both URLs in parallel', 'no browser needed') and a caching window ('~24h per URL pair'), which an agent should know when reasoning about freshness. It does not cover auth/permission requirements, which is the remaining gap.
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?
Front-loaded with verb, resource, and differentiator before the longer enumeration. The output-field listing is long, but with no output schema it is doing real work rather than padding; the 'When NOT to use' routing is also positioned before the return-shape detail. Slightly dense but every sentence carries signal.
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 compensates by enumerating the return shape (ok, urlA/urlB, score, grade, pass/warn/fail, added/removed/renamed, scaleDiff, structureDelta, contrastDrift, scoreDelta, checks). Combined with the eight diff dimensions and the caching note, an agent has everything needed to call and interpret this two-param tool.
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 urlA and urlB are already documented as first/second URL with example framing. The description adds no syntax, format, or validation detail for the parameters themselves (the Levenshtein note refers to the rename heuristic, not an input). Baseline 3 is appropriate when 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?
States a specific verb and resource ('Diff two design systems from live URLs') and immediately differentiates itself with the qualifier 'the only URL-scoped design-token diff engine'. The 'When NOT to use' clause names sibling tools explicitly, so an agent can tell it apart from designesy_drift_score and designesy_monitor_score without opening a schema.
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?
Provides both when-to-use ('what actually changed between two design systems', 'how does our design system differ from a reference') and explicit when-not-to-use with named alternatives (designesy_drift_score for single-site drift, designesy_monitor_score for continuous monitoring). Nothing about tool selection is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the Designesy design-system contract: the canonical tokens, motion, acoustic, takt, cadence, typography, components, and verification rules that define what the Designesy org considers legitimate design. Use this when you need the actual contract values (token names and values, motion timings, accessibility rules) to author, check, or bind a design. When NOT to use: for a pass/fail score of a live site, use designesy_score; for an agent-skill-format export, use designesy_skill_md. Read-only; this server caches the fetched contract for 5 minutes. With no arguments it returns the full contract JSON, about 125 KB (roughly 31k tokens). To return less, pass sections, a list of top-level keys such as ["motion", "colors"]: the result holds id, version, and only those keys. section (one name) is the older form and returns { section, data }. An unknown name returns an error that lists every valid key.
| Name | Required | Description | Default |
|---|---|---|---|
| section | No | Optional, older form: one top-level key; returns { section, data }. Prefer sections. | |
| sections | No | Optional: top-level contract keys to return. The result holds id, version, and only these keys. Omit for the full contract. Valid keys: id, version, status, name, public_url, full_contract_url, machine_url, updated, schema_hints, provenance, colors, surfaces_and_lines, shadows, materials, rounded, layout, motion, interaction, takt, cadence, typography, acoustic, semantic, copywriting, components, accessibility, anti_patterns, implementation, verification, verification_checks, open_tensions, adoption_history, promotion_candidates. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, but the description adds non-obvious operational traits: a 5-minute server-side cache of the fetched contract, the default response size (~125 KB / ~31k tokens), and that unknown names produce an error listing every valid key.
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?
Front-loaded with purpose, then usage, then parameter behavior; each sentence carries information. It is somewhat long and re-enumerates the top-level keys that the schema already lists, but that redundancy is minor.
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?
With no output schema, the description compensates by describing the exact response shape for both parameter forms, the default full-contract payload, and the caching behavior — nothing an agent needs to call this correctly is missing.
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 already 100%, so the baseline is 3, but the description adds return-shape semantics the schema does not: sections yields {id, version, ...keys} while the older section yields {section, data}, plus the error behavior for unknown names.
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?
States a specific verb and resource ('Get the Designesy design-system contract') and then enumerates the contents (tokens, motion, acoustic, takt, typography, components, verification rules), which makes it trivially distinguishable from siblings like designesy_score or designesy_skill_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?
Gives an explicit positive trigger ('when you need the actual contract values ... to author, check, or bind a design') and an explicit negative trigger routed to named alternatives: designesy_score for pass/fail, designesy_skill_md for skill-format export.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the Designesy Design Review rubric for a qualitative design critique: eight dimensions (Purpose, Clarity, Context, Inclusion, System coherence, Durability, Delight, Responsibility), the output format, and the verification checklist, from the published Design Review kit. Use this when you want a structured rubric to critique a design holistically, rather than a numeric compliance score. When NOT to use: for a deterministic numeric score, use designesy_score; this tool gives you a rubric, not a number. Read-only: it returns reference data and does not evaluate the design. Returns JSON: { kind: "review_rubric", source_url, note, inputs (only when passed), kit { id, title, version, status, purpose, quality_bar, permission }, when_to_use[], required_inputs[], dimensions[8] { num, title, desc }, output_format[], verification_checklist[], anti_patterns[], rationalizations[], kit_prompt_url, kit_prompt_note, omitted_fields[] }. The kit's copy-ready agent prompt is not included; kit_prompt_url is the page where a person can read it. Pass artifact, purpose, context, or rules to have them recorded in inputs (rules defaults to the current contract version).
| Name | Required | Description | Default |
|---|---|---|---|
| rules | No | Governing rules or contract version (default: designesy design system v0.4.7). | |
| context | No | Audience, device, environment, and constraints. | |
| purpose | No | What the design is trying to make possible. | |
| artifact | No | URL or description of the artifact to review. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description still adds real value: it clarifies the tool returns reference data and does NOT evaluate the design, and that the kit's copy-ready prompt is deliberately omitted with kit_prompt_url as the human-facing substitute. That discloses scope limits the annotations cannot express.
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?
Front-loaded with purpose, then usage, then the return shape. The inline JSON return sketch is bulky, but with no output schema it earns its place by telling the agent exactly what comes back and which fields are omitted.
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?
No output schema exists, so the description carries return-shape documentation and does so thoroughly (field-by-field), while also covering optional-input behavior and the intentional omission of the agent prompt. An agent has everything needed to call and interpret 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?
Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: the four optional params are merely recorded into an `inputs` echo and do not alter the rubric, and `rules` defaults to the current contract version. That behavioral framing is genuinely informative.
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?
States a specific verb+resource ('Get the Designesy Design Review rubric'), enumerates the eight dimensions, and explicitly contrasts itself with designesy_score. An agent can distinguish it from all 17 siblings without opening a schema.
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?
Gives explicit when-to-use ('structured rubric to critique a design holistically') and a dedicated when-NOT-to-use clause naming the alternative tool (designesy_score) for numeric scoring. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Score a live URL for AI-generated UI drift. Its 12 checks detect the four documented 2026 drift failure modes: token fabrication (var() references with no fallback to custom properties declared nowhere: not in a stylesheet, a block or a style attribute), within-session drift (spacing/color/radius value variance), between-session amnesia (inconsistent font stacks, shadows, transitions), and silent breaking changes (z-index chaos, alias chains that end in an undeclared property). Use this when you need to verify whether a site (especially an AI-generated one) is drifting off its own declared token system. When NOT to use: for a full 45-check design-contract score, use designesy_score; for token-file format validation, use designesy_tokens_score. Executable: fetches the URL server-side, extracts all CSS (inline + linked stylesheets), parses custom property declarations (stylesheets, blocks and style attributes) and var() references, runs 12 drift checks. No browser needed. Returns JSON: { ok, url, scope, score (0-100), grade (A-F), pass, warn, fail, skip, total, tokensExtracted, checks[{id, item, category, status, detail}] }. Results cached ~24h per URL.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | URL to scan for drift. Defaults to https://www.designesy.org/ if not provided. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds genuinely new behavior: server-side fetch, CSS extraction from inline/linked sources, no browser needed, and ~24h per-URL caching. It also discloses the return shape in the absence of an output schema.
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?
Well front-loaded: purpose and drift-mode detail come first, then when-to-use, exclusions, execution model, and return shape. It is dense but each block is informative; the failure-mode parentheticals are slightly verbose for the value they add.
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 complex, zero-required-param analyzer with no output schema, the description supplies everything an agent needs: scope, execution model, caching, and a full inline specification of the returned JSON keys. No material gaps remain.
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% and the single url parameter with its default is fully documented in the schema. The description adds no syntax, format, or constraint detail beyond what the schema already provides, so the 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?
States a specific verb and resource ('Score a live URL for AI-generated UI drift') and enumerates the four failure modes the 12 checks target. It cleanly distinguishes itself from siblings like designesy_score and designesy_tokens_score by scope.
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?
Explicitly names the trigger ('when you need to verify whether a site is drifting off its own declared token system') and provides explicit exclusions routing to designesy_score (45-check contract) and designesy_tokens_score (token-file format). Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a frozen build-contract bundle for AI coding agents from any design system URL (the product layer). Ingests a site, extracts its :root tokens, and emits 6 outputs: (1) DTCG-format token file, (2) Stylelint config generated from token values, (3) AGENTS.md-format rules with token allowlist, (4) component contract with allowed prop patterns, (5) anti-pattern documentation, (6) DESIGN.md file (Google open spec, google-labs-code/design.md), the de-facto AI-readable design-context standard: YAML front matter plus a markdown body. Use this when you need to turn a design system into the file AI agents read and the lint that enforces it. When NOT to use: for design-contract scoring, use designesy_score; for token-file validation, use designesy_tokens_score; for drift detection, use designesy_drift_score. Executable: fetches the URL, extracts CSS + :root custom properties, generates the bundle. No browser needed. The full bundle grows with the number of tokens a site declares: about 7 KB to about 530 KB of JSON on the 26 sites measured (about 110 KB for designesy.org). To trim it, pass parts, a list of bundle file names such as ["designMd"] or ["tokens", "lintConfig"]: the result keeps score, grade, counts and checks, and its bundle holds only those files, in the order asked. Valid parts: tokens, lintConfig, agentRules, componentContract, antiPatterns, designMd. A single part can still be large on a site with many tokens. An unknown name returns an error that lists the valid parts. Returns JSON: { ok, url, score (0-100, emission completeness), grade, pass, warn, fail, total, tokensExtracted, bundle: { tokens, lintConfig, agentRules, componentContract, antiPatterns, designMd }, checks[{id, item, category, status, detail}] }; with parts it adds parts, and bundle holds only the named files. Results cached ~24h per URL.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | URL to generate guardrails for. Defaults to https://www.designesy.org/ if not provided. | |
| parts | No | Optional: the bundle files to return, by name. Omit for the whole bundle. Valid parts: tokens, lintConfig, agentRules, componentContract, antiPatterns, designMd. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds genuinely useful context beyond them: it fetches the URL and extracts CSS/:root properties with no browser, bundle size range (7KB–530KB), ~24h per-URL caching, deterministic ordering of returned parts, and that an unknown part name returns an error listing valid names.
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?
Front-loaded with purpose and the six outputs before the routing guidance, which is the right ordering. However the same six part names are enumerated three times (outputs list, 'Valid parts', and the return JSON), which is noticeable redundancy in an otherwise dense block.
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?
With no output schema, the description fully carries the return-value burden by spelling out the JSON shape (ok, url, score, grade, counts, bundle, checks) and how parts changes it. For a complex multi-file generator, an agent has everything needed to call it correctly and interpret the result.
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 is 3, but the description adds real meaning: the url defaults to designesy.org, parts trims the bundle to named files (preserving score/grade/counts/checks), part order is honored, and bad names produce an informative error. It stops short of restating per-parameter types, hence 4 rather than 5.
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?
States a specific verb+resource ('Generate a frozen build-contract bundle for AI coding agents from any design system URL') and enumerates the six concrete outputs. An agent can distinguish it from every sibling without opening a schema.
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?
Provides explicit when-to-use ('turn a design system into the file AI agents read and the lint that enforces it') and an explicit when-NOT-to-use list routing to designesy_score, designesy_tokens_score, and designesy_drift_score by condition. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the Designesy /llms-full.txt brief as reference data: authority, discovery endpoints, topics, every published package with its links, standing rules, and anti-patterns. Use this for a fuller picture of the Designesy ecosystem when the short brief from designesy_llms_txt is not enough. When NOT to use: for a quick orientation, use designesy_llms_txt (a few thousand characters; this one runs over ten thousand); for the contract itself, use designesy_contract. Read-only: no side effects. Returns JSON: { kind: "published_document", source_url, media_type: "text/plain", note, omitted_sections[], content }, where content is the published text with any section written as steps or a prompt for an AI agent (such as the ingest protocol and the paste-ready agent prompt) replaced by a one-line marker and named in omitted_sections. No parameters.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false, so the restated 'Read-only: no side effects' is redundant. What the description does add is substantive: it discloses the relative payload size (over ten thousand characters vs a few thousand for the sibling) and, critically, that sections written as steps or prompts are replaced by a one-line marker and listed in omitted_sections — a non-obvious transformation of the returned content that no annotation conveys.
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?
It is long, but the front-loaded purpose sentence and the labeled 'When NOT to use' and 'Returns JSON' blocks make it scannable, and each clause carries information. Slight redundancy appears where 'Read-only: no side effects' repeats the annotations, but overall the sentences earn their 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?
There is no output schema, so the description carries the return-value burden, and it discharges it with an explicit JSON shape including field names and the meaning of omitted_sections. Combined with the usage routing and size expectation, an agent has everything needed to select and interpret this tool.
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 tool takes zero parameters, which is the baseline-4 case. The description confirms this explicitly ('No parameters.'), matching the empty input schema with no ambiguity.
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?
States a specific verb and resource ('Get the Designesy /llms-full.txt brief') and enumerates the content scope: authority, discovery endpoints, topics, packages with links, standing rules, anti-patterns. It explicitly differentiates itself from the sibling designesy_llms_txt (short brief) and designesy_contract, so an agent can route without opening any schema.
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 explicit when-to-use ('when the short brief from designesy_llms_txt is not enough') and a labeled 'When NOT to use' section naming two alternatives and the conditions that select them (quick orientation -> designesy_llms_txt; the contract itself -> designesy_contract). Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the Designesy /llms.txt brief as reference data: what Designesy is, canonical links, topics, the published package list, machine exports, standing rules, and contact. Use this first when you don't know what Designesy is; at a few thousand characters it is the cheapest orientation path before pulling heavier artifacts. When NOT to use: for the longer brief, use designesy_llms_full_txt; for the contract itself, use designesy_contract. Read-only: no side effects. Returns JSON: { kind: "published_document", source_url, media_type: "text/plain", note, omitted_sections[], content }, where content is the published text with any section written as steps for an AI agent (such as the ingest steps) replaced by a one-line marker and named in omitted_sections. No parameters.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/idempotent/no-side-effects, so 'Read-only: no side effects' is largely redundant. The genuinely additive disclosure is that agent-step sections (e.g. ingest steps) inside the returned content are replaced by a one-line marker and named in omitted_sections — that is non-obvious behavior an agent must know before relying on the text. It also flags the size/cost profile relative to heavier artifacts.
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?
It is a long single block, but front-loaded (purpose and use-case first, exclusions next, return contract last) and every sentence carries information. The return-shape sentence is dense but necessary since no output schema exists.
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?
With no output schema, the description supplies the full return contract (kind, source_url, media_type, note, omitted_sections[], content) plus the omission rule, and covers selection, cost, and safety. An agent has everything needed to call it and interpret the result.
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 tool takes zero parameters, which the description states plainly ('No parameters.'), matching the empty input schema. Baseline for a 0-param tool; there is nothing further to document.
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?
Specific verb+resource ('Get the Designesy /llms.txt brief as reference data') followed by an enumeration of what the brief contains. It explicitly differentiates itself from siblings by naming designesy_llms_full_txt and designesy_contract as the alternatives for adjacent needs.
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?
Gives an explicit positive condition ('Use this first when you don't know what Designesy is') and an explicit negative one ('When NOT to use') with the two sibling tools that cover those cases. Nothing about tool selection is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Score a URL for continuous design-drift governance, the temporal layer over the drift radar. Re-runs the 12 drift checks (d01-d12) on the URL and computes 10 monitor checks (m01-m10): history supplied, last run fresh, drift delta vs baseline, trend slope (3-run trajectory), new violations since last run, resolved since last run (the healing signal), score degradation threshold, token-set mutation, contract version drift, and alert delivered. Alerts come back in the result as alerts[]. No email is sent: email delivery was retired, so m10 is SKIP on every run and is not scored, and the email argument is deprecated and ignored. Pass a history array of prior snapshots (each call's currentSnapshot) to compute deltas; omit it for a first-run baseline. History is checked for shape and bounds (at most 1000 runs, a request of at most 512 KB). Use this to watch a design system over time: "weekly audits at cents per report" (Into Design Systems 2026). When NOT to use: for a single point-in-time drift check, use designesy_drift_score; for design-contract scoring, use designesy_score. Executable: fetches the URL, extracts CSS + :root tokens, runs checks, computes deltas. No browser needed. Returns JSON: { ok, url, score (0-100, governance health; SKIP is not scored), grade (A-F), pass, warn, fail, total, currentSnapshot, baseline, previous, driftChecks, monitorChecks, alerts }. Results are cached ~24h per URL and history: a repeat call with the same URL and history returns the cached run, with m02 measured again.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | URL to monitor for drift. Defaults to https://www.designesy.org/ if not provided. | |
| No | Deprecated and ignored: email delivery was retired, so no email is sent and the address is not forwarded. Alerts come back in the result as alerts[]. | ||
| history | No | Prior snapshots for delta computation (currentSnapshot from earlier calls). Omit for a first-run baseline. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnly/openWorld/idempotent annotations: it discloses that no email is sent (m10 is SKIP and not scored, email argument deprecated and ignored), that the call is executable and fetches the URL with no browser needed, that history is validated for shape and bounds (1000 runs, 512 KB), and that results are cached ~24h per URL+history with m02 re-measured. These are exactly the traits annotations cannot express.
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?
Purpose and the core history mechanic are front-loaded, and the return-shape summary is compact. The mid-section enumeration of all ten monitor checks (m01–m10) is dense and partly padding, but it does tell the agent what the governance score measures, so it mostly 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 no-output-schema, open-world, network-fetching tool, the description covers execution model, history contract, caching/idempotency caveat, the full return JSON shape and the alert-in-result behavior. An agent has everything needed to call it correctly and interpret the response.
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 is 3, but the description adds real meaning: history should contain prior calls' currentSnapshot objects for delta computation, and omitting it produces a baseline run. It also restates the email deprecation alongside the schema, reinforcing rather than adding. Useful marginal value, though the bounds numbers are largely mirrored in the schema's maxItems.
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?
States a specific verb and resource — scoring a URL for continuous design-drift governance over time — and frames it as 'the temporal layer over the drift radar'. It explicitly names the siblings it supersedes in different cases (designesy_drift_score for point-in-time, designesy_score for contract scoring), so the agent can separate it from 16 siblings without opening a schema.
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?
Gives explicit when-to-use ('watch a design system over time'), explicit when-NOT-to-use with named alternative tools for each case, and operational guidance on the history argument (pass prior currentSnapshot values for deltas, omit for a first-run baseline). Nothing about selection is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate one Lottie animation file against the Designesy motion contract: its ten checks (m01-m10), drawn from the Lottie spec v1.0.1 and the Designesy §16 Ten Non-Negotiable Motion Standards. Each check returns PASS, FAIL, WARN or SKIP under the contract's own name for its id: m01 the schema's top-level animation object (layer contents are not validated, so a clean file returns SKIP, not PASS), m02 the required fields (v, fr, ip, op, w, h, layers), m03 no deprecated 4.x Bodymovin version, m04 a markers array, m05 a meta object, m06 a reduced-motion path (a marker or slot named for it, or a meta note of an external prefers-reduced-motion wrapper), m07 keyframe easing (linear, ease and ease-in curves fail), m08 duration within 300 ms (longer returns WARN, since a justification cannot be read from a file), m09 layout-property animation and m10 keyboard-initiated motion (both SKIP: they concern the page that embeds the file). Use this to check that a motion asset is well formed and carries reduced-motion support. When NOT to use: for the motion CSS of a whole site, use designesy_score. Executable: fetches the URL or parses the inline JSON; 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, lottie_version, layer_count, score (0-100), grade (A-F), pass_count, fail_count, warn_count, skip_count, scoring, checks[{id (m01-m10), name, status (PASS, FAIL, WARN or SKIP), detail}], ten_non_negotiable, provenance, validator_note }. Pass url to fetch a remote Lottie file, or lottie_file to validate an inline JSON string. Provide exactly one.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | URL to a Lottie JSON file. The tool fetches and validates it. | |
| lottie_file | No | Raw Lottie JSON string to validate (alternative to url). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover only the safety profile (readOnly, idempotent, non-destructive, open-world); the description goes well beyond them by disclosing per-check semantics, including which checks return SKIP and why (m01, m09, m10), which return WARN (m08 over 300 ms), and the full scoring formula. It also states the execution model (remote fetch vs. inline parse, no browser), which annotations cannot express.
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 scoping statement, the negative-use guidance, and the input rule are all front-loaded. The dense per-check enumeration is long but each clause carries information the agent needs to interpret statuses, and the return-shape listing substitutes for the absent output schema. Only mild trimming of the check prose would be possible.
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?
With no output schema, the description takes on the full burden and delivers: it enumerates the return fields (score, grade, counts, checks[], provenance), explains the scoring math (PASS=1, WARN=0.5, FAIL=0, SKIP unscored), and defines the contract provenance. Nothing an agent needs to invoke or interpret the tool is missing.
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% and both parameters are documented there, so the baseline is 3. The description adds the crucial constraint the schema omits: pass url or lottie_file, "Provide exactly one" — an important mutual-exclusivity rule not encoded in the schema or in required-parameter metadata (required count is 0).
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 opening sentence states a specific verb and resource (validate one Lottie animation file against the Designesy motion contract) and names the governing check set (m01-m10). It explicitly distinguishes itself from the sibling designesy_score, which handles whole-site motion CSS, so an agent can route correctly without opening a schema.
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 positive use case ("check that a motion asset is well formed and carries reduced-motion support") and an explicit negative one with the named alternative ("When NOT to use: for the motion CSS of a whole site, use designesy_score"). The executable note (fetches the URL or parses inline JSON, no browser needed) further clarifies the operating context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Score a URL for design-system AI readiness, the 6th maturity axis (zeroheight 2026). 10 checks probe the target origin for machine-readable artifacts: DTCG token files, llms.txt, agent.json, MCP endpoint (tools/list), DESIGN.md, token $description, component schemas, sitemap.xml, robots.txt, and Open Graph/Twitter meta. Use this to verify whether a design system is the default context AI tools build from, or whether AI is silently working around it. When NOT to use: for full design-contract scoring, use designesy_score; for AI-drift detection, use designesy_drift_score. Executable: fetches the URL and probes the origin via HEAD/GET for each artifact. No browser needed. Returns JSON: { ok, url, score (0-100), grade (A-F), pass, warn, fail, total, checks[{id, item, category, status, detail}] }. Results cached ~24h per URL.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | URL to score for AI readiness. Defaults to https://www.designesy.org/ if not provided. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial extra context: it is executable, fetches the URL and probes the origin via HEAD/GET, needs no browser, and results are cached ~24h. That caching and network-probing behavior is not derivable from 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?
Front-loaded with purpose, then checks, then exclusions, then execution model and return shape. Dense and mostly earned, though the ten-artifact enumeration and return-object dump make it longer than strictly necessary.
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?
No output schema exists, yet the description spells out the return JSON fields (ok, url, score, grade, pass/warn/fail, checks[]), the execution model, and caching. Nothing material is missing for correct invocation.
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% and the single url parameter is already documented with its default in the schema, so the description needn't add parameter detail. It adds nothing beyond the schema, making the baseline 3 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?
States a specific verb (Score) and resource (a URL for design-system AI readiness) and enumerates the ten artifacts probed, so an agent knows exactly what this does. It also differentiates itself from siblings by naming designesy_score and designesy_drift_score.
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?
Gives an explicit use case (verify whether a design system is the default context AI tools build from) plus an explicit 'When NOT to use' clause routing to designesy_score for contract scoring and designesy_drift_score for drift detection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a unified design-intelligence report for a single URL, the synthesis capstone. Fires /score (45-check audit), /drift (12-check drift radar), and /readiness (10-check AI readiness) in parallel, then computes a weighted composite: score × 0.5 + drift × 0.3 + readiness × 0.2. One input, one output, one composite grade. Use this when you need a single holistic assessment instead of three separate scans, or when sharing a design-intelligence verdict (the report is the most shareable surface). When NOT to use: for just the audit score, use designesy_score; for just drift, use designesy_drift_score; for just AI readiness, use designesy_readiness_score. Executable: fires 3 internal APIs in parallel, each fetches the target URL. No browser needed. The full result is large: about 75 to 100 KB of JSON on the ten sites measured, on the order of 20,000 tokens or more, because it carries each engine's whole result beside the merged check list. To trim it, pass detail "summary": the same keys with fewer rows, about 4 to 31 KB on the same sites. It keeps the composite, the totals, each engine's score, grade and counts, and only the checks and synthesis entries that did not PASS; omitted counts what was left out. detail "full" (the default) returns everything. Returns JSON: { ok, url, compositeScore (0-100), compositeGrade (A-F), score { sub-result }, drift { sub-result }, readiness { sub-result }, totalChecks, totalPass, totalWarn, totalFail, totalSkip, totalManual, checks[] (all checks across all engines, tagged with engine), synthesis[] (8 synthesis checks verifying the report ran correctly), appUrl (standalone interactive dashboard URL) }; with detail "summary" it adds detail and omitted. Results cached ~24h per URL. MCP Apps: hosts that support io.modelcontextprotocol/ui render an interactive dashboard inline; others get the JSON plus an appUrl link.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Public URL to generate a design-intelligence report for. | |
| detail | No | Optional: "full" (the default) returns everything; "summary" returns the composite, the totals, each engine's score, grade and counts, and only the checks that did not PASS. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Rich context beyond annotations: 3 parallel internal API calls, no browser needed, results cached ~24h per URL, and MCP Apps hosts rendering an inline dashboard. Crucially it discloses the practical cost. Annotations already cover the safety profile but not these operational traits, so this adds real 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?
Long but front-loaded: synthesis purpose, weighting formula, when/when-not, cost, and return shape all appear in a deliberate order. Nearly every sentence carries load, though the return-shape enumeration and MCP Apps note push the length toward the upper bound of what is comfortable.
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?
With no output schema, the description fully carries the return contract: the top-level JSON keys, the composite scoring, the checks/synthesis arrays, and how the 'summary' variant differs by adding 'detail' and 'omitted'. An agent has everything needed to call it and interpret the response.
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 is 3. The description goes further, quantifying what each 'detail' value implies (75-100 KB / ~20k tokens for full vs ~4-31 KB for summary, plus the added 'detail' and 'omitted' fields), which the schema's terse enum description does not convey.
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?
States a specific verb and resource: 'Generate a unified design-intelligence report for a single URL, the synthesis capstone,' and immediately explains the mechanism (fires /score, /drift, /readiness in parallel and computes a weighted composite). It names the three sibling tools it supersedes, so an agent can distinguish it without opening any schema.
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?
Gives explicit when-to-use ('a single holistic assessment instead of three separate scans', 'when sharing a design-intelligence verdict') and an explicit 'When NOT to use' block routing to designesy_score, designesy_drift_score, and designesy_readiness_score. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Score a live URL against the Designesy design contract: a deterministic 45-check verification engine that returns a numeric score, letter grade (A-F), and per-check breakdown. Use this to audit whether a website or AI-generated UI complies with a real design contract (tokens, motion, accessibility, cadence, takt, typography, copywriting). When NOT to use: for token-file validation only, use designesy_tokens_score; for a Lottie file, use designesy_motion_score; for a qualitative critique, use designesy_design_review. Executable: fetches the URL server-side, extracts CSS, runs 45 checks. Results cached ~24h per URL. Checks needing a live browser (Core Web Vitals, sound toggle, overflow) return MANUAL (not FAIL); run the full audit (/api/score/audit) to resolve them. Checks that are not applicable to the site (no tokens, no buttons, no DESIGN.md) return SKIP (N/A). The default format returns the engine's JSON: { score (0-100), grade (A-F), pass, warn, fail, skip, manual, total, checks[{id, item, category, status, detail, remediation, weight}], categoryScores, contractVersion, receipt }. Pass format="canonical" for review-findings.json schema, "review" for markdown, or "google" for design.md-compatible output. Pass scope="contract" or "universal" to set the scoring scope instead of auto-detecting it.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | URL to score. Defaults to https://www.designesy.org/ if not provided. | |
| scope | No | Scoring scope. contract: every check counts absence against the site. universal: optional features and Designesy-specific token checks return SKIP when absent. Omit to auto-detect: contract for designesy.org, universal for every other site. | |
| format | No | Output format. designesy (default): the native JSON. canonical: the review-findings.json schema. review: a markdown report. google: the @google/design.md-compatible JSON. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), and the description adds substantial operational context: server-side fetch, ~24h per-URL caching, MANUAL vs SKIP vs FAIL semantics, and the need to run /api/score/audit to resolve browser-dependent checks. Its main weakness is that the caching statement is the only qualifier; no rate limits, auth needs, or failure modes for unreachable URLs are given.
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?
Front-loaded with purpose, then exclusions, then behavior, then output shape — a sensible order with dense, earned sentences. It loses a point for re-describing the format and scope enums that the schema already documents, adding tail 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?
There is no output schema, so the description must (and does) explain the return payload key-by-key (score, grade, pass/warn/fail/skip/manual/total, checks[], categoryScores, receipt) and the alternative shapes for canonical/review/google.
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% and both enums are fully documented in the input schema, so the parameter layer already carries the load; the description's restatement of format and scope values is largely redundant. Setting baseline 3 is correct here — it adds no syntax or semantics the schema lacks.
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?
States a specific verb+resource ('Score a live URL against the Designesy design contract') and quantifies the engine (45 checks, numeric score, letter grade, per-check breakdown). It explicitly names the sibling tools it is not (designesy_tokens_score, designesy_motion_score, designesy_design_review), so the agent can differentiate without opening any schema.
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?
Contains an explicit 'When NOT to use' block routing to three named alternatives with their selection conditions (token-file validation, Lottie file, qualitative critique). Usage is unambiguous and requires no inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the Designesy SKILL.md: the agent-skill-format export of the design-system contract, for a user to save into .agents/skills/ or a system prompt so a coding agent builds UI to the contract (tokens, anti-patterns, rules, verification). Use this when the user wants the contract in that form. When NOT to use: for the raw contract JSON, use designesy_contract; for scoring, use designesy_score. Read-only: no side effects. Returns JSON: { kind: "published_document", source_url, media_type: "text/markdown", note, omitted_sections[], content }, where content is the SKILL.md markdown (tens of thousands of characters) with any section written as steps or a prompt for an AI agent replaced by a one-line marker and named in omitted_sections. No parameters.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/no-destructive, but the description adds context the annotations cannot: it documents that sections written as agent steps or prompts are replaced with one-line markers, names them in omitted_sections, and warns the content runs tens of thousands of characters. That omission behavior is a genuine, non-obvious trait an agent must know before relying on the output.
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?
Front-loaded with the purpose and the when/when-not routing before the return-format detail, so the critical selection information lands first. It is longer than strictly necessary because the inline return-shape description is dense, but every sentence carries actionable information.
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?
With no output schema, the description carries the full burden of documenting the return value and does so precisely (kind, source_url, media_type, note, omitted_sections, content), including the truncation semantics. Combined with the routing guidance, an agent has everything needed to call it and interpret the result.
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 tool takes zero parameters and the schema is empty, so the baseline is 4. The description states 'No parameters' explicitly, which is correct and consistent with the schema, but adds no further parameter meaning to give.
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?
States a specific verb and resource ('Get the Designesy SKILL.md') plus the exact export format ('agent-skill-format export of the design-system contract') and its intended destination (.agents/skills/ or a system prompt). It explicitly distinguishes itself from designesy_contract and designesy_score, so an agent can select it without opening any schema.
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?
Gives an explicit positive trigger ('Use this when the user wants the contract in that form') and an explicit negative trigger ('When NOT to use'), naming the correct alternatives for the excluded cases (designesy_contract for raw JSON, designesy_score for scoring). Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | URL to a DTCG token file (JSON). The tool fetches and validates it. | |
| dtcg_file | No | Raw DTCG token JSON string to validate (alternative to url). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered; the description layers on what the annotations cannot say: it fetches the URL or parses raw JSON server-side, needs no browser, runs exactly 10 checks (t01–t10), and scores PASS=1/WARN=0.5/FAIL=0 with SKIP excluded. It also discloses a non-spec house policy ($schema pointer is a Designesy requirement, not a DTCG one), which an agent needs to interpret WARN/FAIL results correctly.
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?
Front-loading is good — purpose, then output shape, then invocation — but the description is over-long. The adoption statistic ('84% of teams... zeroheight Design Systems Report 2025') and the parenthetical defending the spec's stability are promotional filler that does not help an agent decide or call the tool.
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?
With no output schema, the description carries the full burden and does so: it enumerates the returned JSON fields, the 10-check contract, the scoring formula, and both input modes. Nothing an agent needs to interpret results or select the correct input is missing.
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 individual parameter meanings are already documented and the baseline is 3. The description earns an extra point by adding the mutual-exclusivity rule ('Provide exactly one'), a constraint the flat schema with zero required properties does not express.
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?
States a precise verb+resource: validate a design token file against DTCG 2025.10. It also distinguishes itself from the closest sibling by naming designesy_score as the tool for whole-site scoring, so an agent can route correctly without opening either schema.
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?
Gives explicit when-to-use (verify tokens.json or any DTCG export is structurally correct) and an explicit when-not-to-use with the named alternative (designesy_score for a live site). It also states the invocation constraint: pass exactly one of url or dtcg_file.
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.
designesy_monitor_score18 fields changedInput schema / properties / email / descriptionPrevious value: -"Email address to receive drift alerts. When alerts fire AND this is provided AND the server has email alerts switched on (MONITOR_EMAIL_ENABLED=true, RESEND_API_KEY set), an HTML alert email is sent. Optional: without it, alerts surface in-UI only."New value: +"Deprecated and ignored: email delivery was retired, so no email is sent and the address is not forwarded. Alerts come back in the result as alerts[]."Input schema / properties / history / descriptionPrevious value: -"Prior snapshots for delta computation. Omit for a first-run baseline."New value: +"Prior snapshots for delta computation (currentSnapshot from earlier calls). Omit for a first-run baseline."Input schema / properties / history / items / properties / checks / items / properties / category / maxLengthAdded value: +64Input schema / properties / history / items / properties / checks / items / properties / detail / maxLengthAdded value: +4096Input schema / properties / history / items / properties / checks / items / properties / id / patternAdded value: +"^d(0[1-9]|1[0-2])$"Input schema / properties / history / items / properties / checks / items / properties / item / maxLengthAdded value: +200Input schema / properties / history / items / properties / checks / items / properties / status / enumPrevious value: -[
- "PASS",
- "FAIL",
- "WARN"
-]New value: +[
+ "PASS",
+ "FAIL",
+ "WARN",
+ "SKIP"
+]Input schema / properties / history / items / properties / checks / items / requiredPrevious value: -[
- "id",
- "item",
- "category",
- "status",
- "detail"
-]New value: +[
+ "id",
+ "status"
+]Input schema / properties / history / items / properties / checks / maxItemsAdded value: +12Input schema / properties / history / items / properties / grade / enumAdded value: +[
+ "A",
+ "B",
+ "C",
+ "D",
+ "F"
+]Input schema / properties / history / items / properties / score / maximumAdded value: +100Input schema / properties / history / items / properties / score / minimumAdded value: +0Input schema / properties / history / items / properties / timestamp / maxLengthAdded value: +64Input schema / properties / history / items / properties / tokensExtracted / maximumAdded value: +1000000Input schema / properties / history / items / properties / tokensExtracted / minimumAdded value: +0Input schema / properties / history / items / properties / tokensExtracted / typePrevious value: -"number"New value: +"integer"Input schema / properties / history / items / requiredPrevious value: -[
- "timestamp",
- "score",
- "grade",
- "tokensExtracted",
- "checks"
-]New value: +[
+ "score",
+ "tokensExtracted",
+ "checks"
+]Input schema / properties / history / maxItemsAdded value: +1000designesy_monitor_score1 field changedInput schema / properties / email / descriptionPrevious value: -"Email address to receive drift alerts. When alerts fire AND this is provided AND RESEND_API_KEY is set, an HTML alert email is sent. Optional: without it, alerts surface in-UI only."New value: +"Email address to receive drift alerts. When alerts fire AND this is provided AND the server has email alerts switched on (MONITOR_EMAIL_ENABLED=true, RESEND_API_KEY set), an HTML alert email is sent. Optional: without it, alerts surface in-UI only."designesy_design_review1 field changedInput schema / properties / rules / descriptionPrevious value: -"Governing rules or contract version (default: designesy design system v0.4.6)."New value: +"Governing rules or contract version (default: designesy design system v0.4.7)."designesy_design_review1 field changedInput schema / properties / rules / descriptionPrevious value: -"Governing rules or contract version (default: designesy design system v0.4.5)."New value: +"Governing rules or contract version (default: designesy design system v0.4.6)."designesy_design_review1 field changedInput schema / properties / rules / descriptionPrevious value: -"Governing rules or contract version (default: designesy design system v0.4.4)."New value: +"Governing rules or contract version (default: designesy design system v0.4.5)."designesy_design_review1 field changedInput schema / properties / rules / descriptionPrevious value: -"Governing rules or contract version (default: designesy design system v0.4.3)."New value: +"Governing rules or contract version (default: designesy design system v0.4.4)."designesy_guardrails1 field changedInput schema / properties / partsAdded value: +{
+ "description": "Optional: the bundle files to return, by name. Omit for the whole bundle. Valid parts: tokens, lintConfig, agentRules, componentContract, antiPatterns, designMd.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}designesy_report1 field changedInput schema / properties / detailAdded value: +{
+ "description": "Optional: \"full\" (the default) returns everything; \"summary\" returns the composite, the totals, each engine's score, grade and counts, and only the checks that did not PASS.",
+ "enum": [
+ "summary",
+ "full"
+ ],
+ "type": "string"
+}designesy_contract2 fields changedInput schema / properties / section / descriptionPrevious value: -"Optional: filter to a specific contract section (colors, motion, acoustic, typography, takt, cadence, verification, verification_checks, open_tensions, components, interaction)."New value: +"Optional, older form: one top-level key; returns { section, data }. Prefer sections."Input schema / properties / sectionsAdded value: +{
+ "description": "Optional: top-level contract keys to return. The result holds id, version, and only these keys. Omit for the full contract. Valid keys: id, version, status, name, public_url, full_contract_url, machine_url, updated, schema_hints, provenance, colors, surfaces_and_lines, shadows, materials, rounded, layout, motion, interaction, takt, cadence, typography, acoustic, semantic, copywriting, components, accessibility, anti_patterns, implementation, verification, verification_checks, open_tensions, adoption_history, promotion_candidates.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}designesy_design_review1 field changedInput schema / properties / rules / descriptionPrevious value: -"Governing rules or contract version (default: designesy design system v0.4.2)."New value: +"Governing rules or contract version (default: designesy design system v0.4.3)."designesy_score2 fields changedInput schema / properties / formatAdded value: +{
+ "description": "Output format. designesy (default): the native JSON. canonical: the review-findings.json schema. review: a markdown report. google: the @google/design.md-compatible JSON.",
+ "enum": [
+ "designesy",
+ "canonical",
+ "review",
+ "google"
+ ],
+ "type": "string"
+}Input schema / properties / scopeAdded value: +{
+ "description": "Scoring scope. contract: every check counts absence against the site. universal: optional features and Designesy-specific token checks return SKIP when absent. Omit to auto-detect: contract for designesy.org, universal for every other site.",
+ "enum": [
+ "contract",
+ "universal"
+ ],
+ "type": "string"
+}designesy_contract1 field changedInput schema / properties / section / descriptionPrevious value: -"Optional: filter to a specific contract section (colors, motion, acoustic, typography, takt, cadence, verification, open_tensions, components, interaction)."New value: +"Optional: filter to a specific contract section (colors, motion, acoustic, typography, takt, cadence, verification, verification_checks, open_tensions, components, interaction)."designesy_design_review1 field changedInput schema / properties / rules / descriptionPrevious value: -"Governing rules or contract version (default: designesy design system v0.4.1)."New value: +"Governing rules or contract version (default: designesy design system v0.4.2)."Anti-slop design taste for AI coding agents: art directions, section code, 0-100 page critic.
Checks, prompts and skills for designers working with AI: contrast, a11y, heuristics, critique.
A design harness for AI coding agents: design systems, design principles, icons and UI review.
Website checker for AI coding agents. Measures your site in a real browser, with evidence.
Add one secure layer between your agents and this server.
