Score any URL against a real design contract — 42 checks, A-F grade, token + motion validation.
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() — e.g. branding overrides, 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?
With no annotations supplied, the description carries the full burden and does so excellently: it states 'Does NOT run the scan', explains why ('axe-core needs a real browser DOM'), and clarifies 'The score comes from your local run, not from this tool.' It also documents the PENDING_EXECUTION status, making the tool's non-executing behavior completely explicit.
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 contributes either purpose, exclusion, execution caveat, return contract, or configuration guidance. The core caveat ('Does NOT run the scan') is front-loaded near the top, and the return shape is given precisely.
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?
Since there is no output schema, the description must and does specify the returned JSON shape, including the checks array, status values, playwright_script, install_command, and run_command. It also covers local execution dependencies and the config param, so an agent has enough to invoke and interpret the result 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 baseline is 3. The description adds only marginal detail beyond the schema: it clarifies config is a JSON string for axe.configure() and that omitting it means standard WCAG 2.2 AA. URL and ruleset semantics are already fully covered by the schema, so the description adds little new parameter-level meaning.
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 identifies a specific verb ('Get'), a specific resource ('Designesy WCAG 2.2 AA accessibility verification framework'), enumerates the 11 checks, and notes the output is a Playwright + axe-core script template. It also names the sibling tool (designesy_score) for the alternative use case, so it is distinguished from siblings.
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 'Use this to audit a site for accessibility violations' and gives a concrete 'When NOT to use' case with an alternative tool. The local execution requirement is also stated, so an agent knows this tool only returns a script rather than performing the audit.
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) — the org identity, authority, ingest protocol, package index, machine-export list, permission policy, and citation templates. Use this when you are integrating with or enumerating Designesy as a machine agent and need the canonical discovery/manifest endpoint 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 the /.well-known/agent.json object: { identity, authority, ingest_protocol, package_index, permission_policy, citation_templates }. No parameters.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explicitly states 'Read-only — no side effects' and describes the returned object structure, which is more than sufficient for a simple discovery endpoint.
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?
Although slightly long, every sentence adds value: purpose, usage scenario, exclusions, read-only note, return shape, and parameter confirmation. The core action is front-loaded, making the structure effective.
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 detailing the return object fields. It also covers usage context, exclusions, and behavior, making it complete for a zero-parameter discovery 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 has zero parameters, and the description confirms 'No parameters.' Per the baseline rule for zero-parameter tools, a score of 4 is appropriate since there is nothing else 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?
The description clearly states the tool's purpose: 'Get the Designesy agent discovery document' and enumerates its contents (identity, authority, ingest protocol, etc.). It distinguishes this tool from siblings by positioning it as the canonical discovery/manifest endpoint rather than a specific contract.
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?
Explicit usage guidance is provided: 'Use this when you are integrating with or enumerating Designesy as a machine agent and need the canonical discovery/manifest endpoint.' It also gives clear exclusions: 'for the package list, use designesy_catalog (lighter); for the contract, use designesy_contract.'
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states 'Read-only — no side effects' and discloses the exact JSON return shape, which is especially valuable given there is no 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?
The description is compact and front-loaded with the core purpose. Every sentence adds value: purpose, usage guidance, side-effect disclosure, return format, and parameter confirmation. No filler 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 zero-parameter read-only catalog tool with no annotations and no output schema, the description covers everything an agent needs: what it lists, what it returns, whether it has side effects, and how to choose between this and designesy_contract. It is complete for correct invocation and interpretation.
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 has zero parameters and the schema already shows an empty properties object, so the baseline is 4. The description reinforces with 'No parameters — accepts empty input,' which is helpful but adds little semantic meaning 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 states a specific verb ('List') and resource ('the 23 published Designesy packages') with the exact fields returned. It also distinguishes itself from the sibling designesy_contract by framing itself as the discovery step before fetching a specific contract.
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 tells the agent when to use the tool ('Use this to discover what Designesy publishes before fetching a specific contract') and when not to use it ('if you already know which package you need, skip this and call designesy_contract directly'). This gives clear routing guidance relative to a relevant sibling.
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 — 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?
With no annotations provided, the description transparently discloses key behaviors: fetches both URLs in parallel, extracts :root custom properties, computes a structured diff, runs /score on both URLs, does not require a browser, and caches results for ~24h. This goes well beyond the tool name and 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?
The description is dense but well-organized: purpose first, then dimensions, use cases, alternatives, execution details, and return shape. Every sentence adds concrete information, with no fluff or repetition of the schema.
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 no output schema, the description includes the full JSON return structure and enumerates all computed diff categories. It also covers practical aspects like caching and that no browser is needed, making it highly complete for an AI agent to invoke and interpret results.
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 already provides descriptions for both urlA and urlB, giving 100% coverage. The description enhances these by clarifying the directional meaning of A and B in the diff (e.g., 'added (in A not B), removed (in B not A)') and noting caching per URL pair, adding value over 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?
Description opens with 'Diff two design systems from live URLs', using a specific verb and resource. It further differentiates from siblings by calling itself 'the only URL-scoped design-token diff engine' and details the 8 diff dimensions, making the tool's scope unmistakable.
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 use cases: 'what actually changed between two design systems' or 'how does our design system differ from a reference'. Also gives clear when-not-to-use guidance, pointing to designesy_drift_score for single-site drift and designesy_monitor_score for continuous monitoring.
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 — cached ~24h server-side. Returns the full contract JSON, or a single section when "section" is provided. Pass section to get one slice (e.g. "motion" for just the motion tokens) instead of the full contract — saves tokens when you only need one dimension.
| Name | Required | Description | Default |
|---|---|---|---|
| section | No | Optional: filter to a specific contract section (colors, motion, acoustic, typography, takt, cadence, verification, open_tensions, components, interaction). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full transparency burden. It clearly states 'Read-only — cached ~24h server-side,' disclosing the operation's safety profile and caching behavior. It further explains the return behavior: 'Returns the full contract JSON, or a single section when section is provided,' and notes the token-saving benefit of using the section parameter. While not exhaustive (e.g., error handling isn't mentioned), the description provides substantial behavioral context.
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 front-loaded with the core purpose and then systematically covers usage, exclusions, read-only status, return behavior, and parameter guidance. Each of the five sentences provides distinct value without redundancy. The structure is logical and easy to parse, even at length.
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?
The tool is simple (one optional parameter, no output schema), and the description fully covers the essential context: purpose, contents, usage, alternatives, safety (read-only, caching), and return format. It also enumerates the available sections in the schema. Given the tool's low complexity, the description is complete and leaves no major gaps.
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 provides 100% coverage with a description for the 'section' property listing valid values. The description adds practical meaning by giving an example ('e.g. motion for just the motion tokens') and explaining the trade-off ('saves tokens when you only need one dimension'). This goes beyond the schema doc and helps the agent decide when to use the parameter.
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 specific verb 'Get' and identifies a clear resource: 'the Designesy design-system contract.' It lists the contract's contents (tokens, motion, acoustic, takt, cadence, typography, components, verification rules) and distinguishes it from siblings by naming designesy_score and designesy_skill_md as alternatives. This makes it unambiguous what the tool does.
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: 'when you need the actual contract values... to author, check, or bind a design.' It also provides when-not-to-use scenarios with named alternatives: 'for a pass/fail score of a live site, use designesy_score; for an agent-skill-format export, use designesy_skill_md.' This is exemplary usage guidance.
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 framework — an 8-dimension rubric (Purpose, Clarity, Context, Inclusion, System coherence, Durability, Delight, Responsibility) plus the agent prompt, output format, and verification checklist for a qualitative design critique. 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 — returns the rubric + prompt. The calling agent performs the actual critique (this tool does not evaluate the design for you). Returns JSON: { rubric, dimensions[8], agent_prompt, output_format, verification_checklist }. Pass artifact/purpose/context/rules to get a pre-filled critique prompt; omit all four to get the blank framework.
| Name | Required | Description | Default |
|---|---|---|---|
| rules | No | Governing rules or contract version (default: designesy design system v0.4.0). | |
| 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?
With no annotations provided, the description carries the full burden. It discloses read-only status, the fact that it returns a rubric + prompt rather than performing evaluation, and the exact JSON return shape. This goes beyond basic expectations and prevents misuse.
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 dense but every sentence serves a purpose: component list, use case, exclusion, read-only note, return format, and parameter behavior. It is front-loaded with the essential 'what' before diving into details, with no redundant phrasing.
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?
The tool returns a framework, and the description covers its composition, usage, parameter behavior, and output schema (via textual keys) since no formal output schema exists. For a read-only retrieval tool, this is effectively complete.
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%, but the description adds aggregate behavior: passing artifact/purpose/context/rules pre-fills the critique prompt, while omitting them yields the blank framework. This enhances the schema's individual parameter descriptions by explaining their joint effect.
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 begins with a specific verb and resource: 'Get the Designesy Design Review framework' followed by an explicit 8-dimension breakdown. It clearly distinguishes from siblings by naming designesy_score as the numeric alternative, making the tool's qualitative role unambiguous.
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 ('when you want a structured rubric to critique a design holistically') and when not to ('for a deterministic numeric score, use designesy_score'). It also clarifies that the calling agent performs the critique, setting appropriate expectations for the tool's role.
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 — 12 checks detect the four documented 2026 drift failure modes: token fabrication (var() to undeclared custom properties), within-session drift (spacing/color/radius value variance), between-session amnesia (inconsistent font stacks, shadows, transitions), and silent breaking changes (z-index chaos, dangling alias chains). 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 42-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 :root custom properties and var() references, runs 12 drift checks. No browser needed. Returns JSON: { ok, url, score (0-100), grade (A-F), pass, warn, fail, 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?
With no annotations provided, the description carries the full disclosure burden and meets it thoroughly. It reveals that the tool is executable, fetches the URL server-side, extracts and parses CSS, runs 12 checks, requires no browser, returns a structured JSON payload, and caches results ~24h per URL. This gives the agent a realistic model of side effects and behavior.
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 dense but every sentence earns its place: it defines the core purpose, enumerates failure modes, gives usage and exclusion guidance, explains execution behavior, and specifies the return shape. It is front-loaded with the most decision-relevant information and remains easy to scan despite its length.
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 only one optional parameter, no annotations, and no output schema, the description is remarkably complete. It covers what the tool does, how it works, when to avoid it, what the JSON response contains, and even a caching caveat. An agent has enough context to select and invoke the tool correctly without further documentation.
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 the single 'url' parameter with 100% coverage, so the baseline is 3. The description adds only the default value, which is also present in the schema, so it does not significantly expand parameter semantics beyond what structured metadata already provides.
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 clear, specific action: 'Score a live URL for AI-generated UI drift' and enumerates the 12 checks and four drift failure modes it detects. It clearly differentiates this tool from its siblings by naming the distinct scope and the exact classes of problems it addresses.
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 says when to use the tool ('Use this when you need to verify whether a site... is drifting') and when not to, naming the alternatives designesy_score and designesy_tokens_score. This gives an agent unambiguous routing guidance beyond what the tool name alone conveys.
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) — YAML front matter + markdown body, the de-facto AI-readable design-context standard. 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. 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}] }. 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It clearly discloses execution behavior ('fetches the URL, extracts CSS + :root custom properties'), notes 'No browser needed', and describes the return JSON structure plus caching behavior. It does not mention auth or rate limits, but covers key operational traits.
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 every sentence earns its place: it lists outputs, gives usage guidance, explains behavior, and specifies the return format. It is front-loaded with the core purpose and structured with numbered lists and clear sections, making it easy to parse.
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's complexity (six outputs, checks array, no output schema), the description is remarkably complete. It enumerates all bundle components, defines the JSON response fields, and notes the 24-hour cache — enough for an agent to invoke correctly without additional documentation.
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 schema already describes the url parameter with a default. The description reinforces the URL's role but adds no new parameter details beyond what the schema provides, so a 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 opens with 'Generate a frozen build-contract bundle for AI coding agents' — a specific verb, resource, and scope. It enumerates the six distinct outputs and explicitly differentiates from sibling tools by naming alternatives for scoring, validation, and drift detection.
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 directly states when to use ('Use this when you need to turn a design system into the file AI agents read and the lint that enforces it') and provides explicit when-not-to-use guidance with named alternatives: designesy_score, designesy_tokens_score, and designesy_drift_score.
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 — the complete agent-facing brief: ingest protocol, discovery endpoints, every package, standing rules, anti-patterns, and a paste-ready agent prompt. Use this for comprehensive onboarding to the Designesy ecosystem when the short /llms.txt is not enough. When NOT to use: for a quick orientation, use designesy_llms_txt first (~500 tokens vs ~3000). Read-only — no side effects. Returns text/plain (~3000 tokens, includes a paste-ready agent prompt). No parameters.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses read-only status with 'no side effects', describes return format as 'text/plain', and mentions estimated token count and included paste-ready prompt. This fully covers behavioral expectations for a zero-parameter read tool.
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 compact yet information-dense: purpose, contents, usage guidance, alternative, safety note, return type, and token estimate all fit in three sentences. It is front-loaded with the primary action and never wastes words.
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?
Despite having no output schema, the description explicitly states the return type and content details. It also provides usage context distinguishing it from the sibling tool. For a simple read-only fetch with no parameters, this is fully complete.
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 has zero parameters, which is already visible in the schema. The description adds 'No parameters' for confirmatory clarity. Per calibration, a baseline of 4 is appropriate for zero-parameter tools, and no further semantic explanation is needed.
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 gets the Designesy /llms-full.txt, described as the complete agent-facing brief. It explicitly distinguishes from the sibling tool designesy_llms_txt by noting the short version is for quick orientation.
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 guidance: 'when the short /llms.txt is not enough' for comprehensive onboarding. Also gives a direct when-not-to-use with an alternative tool and token comparison (~500 tokens vs ~3000), making the decision context very clear.
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 — a short agent-facing brief with the canonical reference, topic index, ingest steps, package list, and contact. Use this first when you don't know what Designesy is — it's the cheapest orientation path before pulling heavier artifacts. When NOT to use: for the full expanded brief, use designesy_llms_full_txt; for the contract itself, use designesy_contract. Read-only — no side effects. Returns text/plain (~500 tokens). No parameters.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though no annotations are present, the description explicitly states 'Read-only — no side effects' and discloses the return format ('Returns text/plain (~500 tokens)'). It also describes what content the response includes, giving the agent a clear behavioral model despite having no structured safety hints.
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 well-structured: it opens with the action and resource, provides a concise content list, then delivers usage guidance, exclusions, safety, and return format in a compact sequence. Every sentence contributes critical information without redundancy, making it efficiently 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?
For a zero-parameter tool that returns a simple text artifact, this description is fully complete. It covers the tool's purpose, what the output contains, when to use it vs alternatives, safety behavior, and output format. No additional context is needed for an agent to select 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?
The tool has zero parameters, so the schema fully covers parameter semantics by having none. The description reinforces this with 'No parameters,' and the baseline for 0-param tools is 4. There are no undocumented parameters to explain, so it meets the expected standard.
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 starts with a specific verb 'Get' and names the exact resource '/llms.txt', then lists its key contents (canonical reference, topic index, ingest steps, package list, contact). It explicitly distinguishes this tool from siblings by naming designesy_llms_full_txt and designesy_contract, making its purpose unmistakable.
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 clear when-to-use guidance: 'Use this first when you don't know what Designesy is' and frames it as the 'cheapest orientation path before pulling heavier artifacts.' It also gives explicit when-not-to-use instructions with named alternatives (designesy_llms_full_txt for full brief, designesy_contract for the contract), which is exemplary.
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): schedule registered, 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. When alerts fire and an email address is provided, sends an HTML drift-alert email via Resend (requires RESEND_API_KEY env var). Pass a history array of prior snapshots to compute deltas; omit it for a first-run baseline. 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), grade (A-F), pass, warn, fail, total, currentSnapshot, baseline, previous, driftChecks, monitorChecks, alerts, emailAlert }. Results cached ~24h per URL.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | URL to monitor for drift. Defaults to https://www.designesy.org/ if not provided. | |
| No | 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. | ||
| history | No | Prior snapshots for delta computation. Omit for a first-run baseline. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite having no annotations, the description discloses execution behavior: it fetches the URL, extracts CSS tokens, runs checks, and computes deltas; requires RESEND_API_KEY for email alerts; caches results for 24h; and sends emails as a side effect when conditions are met. This fully carries the transparency burden.
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 lengthy but front-loaded with the core purpose, then details checks, side effects, and alternatives. While it contains a marketing quote and a long enumeration of monitor checks, the detail is warranted for a complex tool, though slightly verbose.
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?
The description is highly complete: it explains the JSON return shape (compensating for no output schema), covers prerequisites, side effects, caching, and usage distinctions. No significant contextual gaps remain for the complexity level.
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 covers all 3 parameters with rich descriptions (100% coverage), including defaults and conditional email sending. The description adds marginal meaning by restating the history parameter's purpose, so it doesn't improve upon the schema baseline.
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 scores a URL for continuous design-drift governance, explicitly distinguishing it from single-point-in-time drift checks (designesy_drift_score) and design-contract scoring (designesy_score). This provides a specific verb, resource, and temporal 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?
It explicitly states when to use (watch a design system over time) and when not to use, naming exact alternative tools for point-in-time drift checks and contract scoring. This is exemplary usage guidance that leaves no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a Lottie animation file against the Lottie spec v1.0.1 and the Designesy §16 Ten Non-Negotiable Motion Standards, returning 10 checks (m01-m10) with PASS/FAIL/WARN. The DTCG 2025.10 spec leaves motion tokens as a second-class citizen — there is no standard for motion token structure, reduced-motion markers, or animation accessibility. Designesy's motion validator fills this gap: it checks required fields (v, fr, ip, op, w, h, layers), $version, a markers array for reduced-motion compliance, and no deprecated version. Use this to verify a motion/animation asset is well-formed AND accessible — the only validator that checks both. When NOT to use: for full-site motion scoring (not a single Lottie file), use designesy_score. Executable — fetches the URL or parses the raw Lottie JSON, runs 10 checks server-side. No browser needed. Returns JSON: { checks[{id (m01–m10), name, status (PASS/FAIL/WARN), detail}], valid, score }. 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that the tool is 'Executable — fetches the URL or parses the raw Lottie JSON, runs 10 checks server-side. No browser needed.' It also discloses the exact return JSON structure and the meaning of valid/score. It does not cover possible error conditions (e.g., invalid URL, timeouts) or authentication, but for a validation tool with read-only behavior, the core transparency is strong.
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 longer than typical, but every sentence contributes value: purpose, standards, check details, rationale for the validator's existence, usage, when-not-to-use, execution model, return format, and parameter guidance. It is front-loaded with the core purpose and structured logically. While it could be trimmed slightly, the length is justified by the complexity of the tool and the absence of annotations or an output schema.
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 that there is no output schema and no annotations, the description fully compensates by defining the return shape ({ checks[{id, name, status, detail}], valid, score }), the specific checks (m01-m10), and the standards involved. It also explains why the validator exists (DTCG spec gap) and how it differs from designesy_score. This is a complete and self-contained description for an agent to select and 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?
The schema already documents both parameters (url and lottie_file) with descriptions, so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains that url is for fetching a remote Lottie file, lottie_file is for an inline JSON string, and critically, 'Provide exactly one.' This clarifies the mutual exclusivity, which is not enforced by the schema (required is empty). This additional guidance lifts the score above baseline.
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 starts with a specific verb ('Validate') and resource ('a Lottie animation file'), and clearly states the two standards it validates against (Lottie spec v1.0.1 and Designesy motion standards). It explicitly mentions returning 10 checks (m01-m10) with PASS/FAIL/WARN, and distinguishes itself from sibling tools by noting it validates a single Lottie file rather than full-site scoring (which designesy_score handles).
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 explicit when-to-use guidance: 'Use this to verify a motion/animation asset is well-formed AND accessible — the only validator that checks both.' It also gives a clear when-not-to-use condition and names the alternative: 'When NOT to use: for full-site motion scoring (not a single Lottie file), use designesy_score.' Additionally, it instructs the caller to 'Provide exactly one' of url or lottie_file, which is critical operational guidance.
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?
No annotations are provided, so the description carries full burden. It discloses that the tool is executable, fetches the URL, probes via HEAD/GET, requires no browser, and caches results for ~24h. These are significant behavioral traits beyond the basic scoring purpose.
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 dense yet well-organized. Each sentence serves a purpose: purpose, checks list, usage context, exclusions, execution details, and return format. No redundant text; information is front-loaded and easy to scan.
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 tool with no annotations and no output schema, the description is exceptionally complete. It covers what it does, the specific checks, execution behavior, cache policy, and the full JSON return structure, leaving no major gaps.
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 covers the 'url' parameter with a basic description, but the tool description adds meaning by specifying the default URL (https://www.designesy.org/) and clarifying that the URL is the target origin for the 10 checks. This exceeds the schema's baseline value.
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 the tool's exact function: 'Score a URL for design-system AI readiness' and lists the 10 specific checks it performs. It differentiates from siblings by explicitly naming alternatives: 'for full design-contract scoring, use designesy_score; for AI-drift detection, use 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?
It provides explicit when-to-use context: 'verify whether a design system is the default context AI tools build from, or whether AI is silently working around it.' It also gives clear exclusions with named sibling tools, making the usage guidance unambiguous.
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 of the Designesy dynasty. Fires /score (42-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. Returns JSON: { ok, url, compositeScore (0-100), compositeGrade (A-F), score { sub-result }, drift { sub-result }, readiness { sub-result }, totalChecks, totalPass, totalWarn, totalFail, totalSkip, checks[] (all checks across all engines, tagged with engine), synthesis[] (8 synthesis checks verifying the report ran correctly), appUrl (standalone interactive dashboard URL) }. 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full disclosure burden and fully delivers. It reveals several important behaviors beyond the obvious 'generate a report': it is executable and fires three internal APIs in parallel, each fetching the target URL, no browser is needed, results are cached approximately 24 hours per URL, and the output can trigger an interactive dashboard on supporting hosts. These details materially affect invocation expectations and are not inferable from the 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?
The description is long, but nearly every sentence adds distinct value: composite weighting, parallel execution, cache behavior, excluded siblings, return contract, and rendering behavior are all functionally important. The use of 'When NOT to use' and 'Executable' serve as explicit structural signposts, and the riskiest information (side effects and alternatives) appears early. Slight verbosity around the internal endpoint spellings is the minor cost of that transparency.
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 tool with no output schema, the description provides an unusually complete response contract: it enumerates every top-level field, explains the composite formula, describes sub-result structure, identifies total counts, and even notes the checks array engine tags and synthesis checks. It also covers execution semantics, caching, and rendering behavior. Nothing needed to invoke or interpret this 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?
The schema already describes the single 'url' parameter with 100% coverage, so the parameter semantics are fully documented there. The description adds only that the URL should be public, which is a modest but useful clarification. Per the rubric, baseline 3 applies when schema coverage is high and the description need not repeat parameter details.
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: 'Generate a unified design-intelligence report for a single URL.' It clearly distinguishes itself from sibling tools by naming the three sub-scans it combines and positioning itself as the shared, synthesis capstone of the Designesy family. The explicit exclusion of the separate score/drift/readiness tools removes ambiguity.
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 ('when you need a single holistic assessment instead of three separate scans') and includes a dedicated 'When NOT to use' section naming designesy_score, designesy_drift_score, and designesy_readiness_score as the alternatives. This gives an agent direct routing instructions without requiring comparison of schema or sibling names.
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 42-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 42 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). Returns JSON: { url, score (0–100), grade (A–F), pass_count, fail_count, checks[{id, name, status, weight, category}] }. Pass format="canonical" for review-findings.json schema, "review" for markdown, or "google" for design.md-compatible output.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | URL to score. Defaults to https://www.designesy.org/ if not provided. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral disclosure and does so thoroughly. It states the executable server-side fetching behavior, 24-hour caching, MANUAL status for live-browser-dependent checks, SKIP for non-applicable checks, and the available output formats — all beyond what the schema could 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?
The description is dense and well-organized, front-loading purpose and output while using a clear logical progression: contract, usage, exclusions, execution behavior, statuses, return shape, and format options. It is longer than minimal, but each clause earns its place; only a slight redundancy between the opening 'returns a numeric score' and the later 'Returns JSON' prevents a 5.
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?
Despite having no output schema, the description fully enumerates the response structure, status semantics, caching behavior, and format switches. It even points to the full audit path for resolving MANUAL checks, leaving no critical knowledge gap for an agent to correctly invoke and interpret the 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%, and the URL parameter is already clearly documented in the schema. The description adds only the default URL behavior and the format options, which are useful but not essential for understanding the single parameter. This meets the baseline for full schema coverage without adding significant new meaning.
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 precise verb and resource: 'Score a live URL against the Designesy design contract,' and explains the verification engine's 42-check nature and output. It explicitly distinguishes itself from siblings by naming designesy_tokens_score, designesy_motion_score, and designesy_design_review, so an agent can select it correctly even among 16 related 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 gives direct usage context ('Use this to audit whether a website or AI-generated UI complies with a real design contract') and a dedicated 'When NOT to use' section naming the exact alternative for token files, Lottie files, and qualitative reviews. This makes both selection and exclusion criteria explicit.
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, written as behavioral rules an AI coding agent can drop into .agents/skills/ or a system prompt. Use this when you want the contract in a form that steers how an agent builds UI (tokens, anti-patterns, behavioral rules, verification). When NOT to use: for the raw contract JSON, use designesy_contract; for scoring, use designesy_score. Read-only — no side effects. Returns markdown text (SKILL.md format) — drop into .agents/skills/ or paste into a system prompt. No parameters.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so effectively. It explicitly states 'Read-only — no side effects' and describes the return value ('Returns markdown text (SKILL.md format)'). This covers the key behavioral aspects for an agent selecting the tool.
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 mostly concise and front-loaded with the primary purpose, but it repeats the 'drop into .agents/skills/ or a system prompt' detail in both the first and last sentences. This slight redundancy prevents a perfect score.
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?
Despite the tool's simplicity (no parameters, no output schema), the description provides all necessary context: what the tool returns, the format, read-only behavior, and when to use it versus alternatives. The context is complete for selection and 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?
The tool has zero parameters and the description notes 'No parameters.' Since there are no parameters, the schema covers 100% of the (empty) set, and the description doesn't need to add parameter semantics. Baseline of 4 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 clearly identifies the tool's function: retrieving the Designesy SKILL.md, an agent-skill-format export of the design-system contract. It uses a specific verb ('Get') and resource, and explicitly distinguishes it from siblings like designesy_contract (raw JSON) and designesy_score (scoring).
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 usage context: 'Use this when you want the contract in a form that steers how an agent builds UI.' It also provides clear exclusions with named alternatives: 'When NOT to use: for the raw contract JSON, use designesy_contract; for scoring, use designesy_score.'
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 — Candidate Recommendation, considered stable). Returns 10 conformance checks (t01-t10) with PASS/FAIL/WARN. Use this to verify a tokens.json (or any DTCG token export) is structurally correct — $type/$value/$description present, structured colors (colorSpace + components rather than bare hex), a valid $schema pointer to designtokens.org, and correct dimension units. 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. Returns JSON: { checks[{id (t01–t10), name, status (PASS/FAIL/WARN), detail}], valid, score }. 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?
With no annotations provided, the description carries the full behavioral burden. It discloses that the tool is executable, fetches a URL or parses inline JSON, runs 10 checks server-side, requires no browser, and returns a specific JSON structure. It could add more about side effects or error behavior, but the core behavior is well covered.
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 front-loaded and well organized, but it contains significant filler, especially the '84% of teams now using design tokens' marketing sentence and the repetitive spec-status framing. Several sentences could be cut without losing instructional value, so it is not appropriately sized for such a simple two-parameter 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?
Despite having no output schema and no annotations, the description is complete enough for an agent to invoke the tool correctly. It covers purpose, input selection rules, execution behavior, and the exact JSON return contract. An agent knows what to pass, what will happen, and what shape the response will take.
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 documents both parameters, and the description adds valuable nuance: url is for remote token files, dtcg_file is for inline JSON strings, and exactly one must be provided. This exclusivity and remote-vs-inline distinction goes beyond the schema's basic parameter 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?
The description opens with a specific verb and resource: 'Validate a design token file against the W3C DTCG specification.' It further clarifies the concrete deliverable — 10 conformance checks (t01-t10) with PASS/FAIL/WARN — and explicitly distinguishes itself from the sibling designesy_score by stating that live-site scoring is not this 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?
It gives clear when-to-use guidance: verify a tokens.json or DTCG token export for structural correctness. It also gives when-not-to-use guidance with a named alternative: 'for scoring a whole live site, use designesy_score.' The instruction to 'Provide exactly one' input source further guides invocation.
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. Dates show when Glama detected each change.
designesy_monitor_score1 field changedInput schema / properties / emailAdded value: +{
+ "description": "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.",
+ "type": "string"
+}designesy_a11y_score2 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesRemoved value: -falsedesignesy_agent_json1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"designesy_catalog1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"designesy_compare2 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesRemoved value: -falsedesignesy_contract2 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesRemoved value: -falsedesignesy_design_review2 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesRemoved value: -falsedesignesy_drift_score2 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesRemoved value: -falsedesignesy_guardrails2 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesRemoved value: -falsedesignesy_llms_full_txt1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"designesy_llms_txt1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"designesy_monitor_score4 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesRemoved value: -falseInput schema / properties / history / items / additionalPropertiesRemoved value: -falseInput schema / properties / history / items / properties / checks / items / additionalPropertiesRemoved value: -falsedesignesy_motion_score2 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesRemoved value: -falsedesignesy_readiness_score2 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesRemoved value: -falsedesignesy_report2 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesRemoved value: -falsedesignesy_score2 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesRemoved value: -falsedesignesy_skill_md1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"designesy_tokens_score2 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesRemoved value: -falsedesignesy_reportdesignesy_comparedesignesy_monitor_scoredesignesy_drift_scoredesignesy_guardrailsdesignesy_readiness_scoredesignesy_design_review1 field changedInput schema / properties / rules / descriptionPrevious value: -"Governing rules or contract version (default: designesy design system v0.3.0)."New value: +"Governing rules or contract version (default: designesy design system v0.4.0)."designesy_a11y_scoredesignesy_agent_jsondesignesy_catalogdesignesy_contractdesignesy_design_reviewdesignesy_llms_full_txtdesignesy_llms_txtdesignesy_motion_scoredesignesy_scoredesignesy_skill_mddesignesy_tokens_scoreClaiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user, then choose Claim with GitHub. An organization namespace such as io.github.acme/server also needs that organization to have installed the Glama AI GitHub App and approved its permissions, because GitHub discloses organization membership only to apps it has installed. Use HTTP or DNS when it has not.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Turn any live website into brand colors, fonts, design tokens, SVGs, Lottie and paste-ready code.
On-demand drift checks: declared CSS color, radius, spacing & type vs your own tokens or a pack
Scores any public website on how usable it is by AI agents, with per-check evidence.
Validate HTML/CSS, audit SEO and JSON-LD, check links, and capture responsive screenshots.
Add one secure layer between your agents and this server.
Each tool has a clearly scoped purpose, and the extensive 'When NOT to use' notices cleanly separate the many scoring variants (e.g., score, drift, readiness, monitor, tokens, motion, a11y). Even similar informational endpoints (contract, skill, llms) are differentiated by format and use case. No two tools appear to do the same thing.
All tools follow a consistent 'designesy_' prefix, and scoring tools uniformly append '_score' (e.g., drift_score, tokens_score, monitor_score). Non-score tools use descriptive noun suffixes (catalog, contract, report, guardrails). The pattern is predictable and uniform throughout.
At 17 tools, the set is slightly above the ideal 3-15 range, but the breadth of the design-system intelligence domain justifies the count. Each scoring variant targets a different artifact (live URL, token file, Lottie, temporal drift) and the informational endpoints serve distinct formats. The tool count is heavy but not bloated.
The toolset covers the full assessment lifecycle: full audit (score), drift and temporal governance (drift_score, monitor_score), AI readiness (readiness_score), token and motion validation (tokens_score, motion_score), accessibility framework (a11y_score), diff (compare), composite report (report), guardrails generation, and multiple discovery formats (catalog, contract, skill_md, llms). No obvious dead ends exist; each tool leads to a usable artifact or clear next step.
