Designesy

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

No annotations exist, so the description carries the full burden and does: it discloses that the tool does NOT execute the scan ('axe-core needs a real browser DOM'), that the score comes from a local run, the required install step (npm i -D @axe-core/playwright), and the exact return shape including status values of PENDING_EXECUTION. This is exactly the kind of non-obvious behavior an agent needs.

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 exclusion, then the critical non-execution caveat. Slightly padded by both an inline 'Returns JSON: {...}' block and separate sentences covering install_command/run_command, which partially restate each other, but no sentence is truly wasted.

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 three-parameter tool with no annotations and no output schema, the description covers purpose, exclusions, the non-obvious non-execution model, the prerequisite install command, and the full response structure. Nothing an agent needs to invoke or interpret the tool 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 100%, so the baseline is 3; the description adds genuine meaning on top by explaining the purpose of config ('customize axe.configure(), for example with branding overrides or rule disables') and the default behavior when omitted ('Omit for standard WCAG 2.2 AA'). It does not add anything for ruleset beyond what the schema already enumerates.

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 WCAG 2.2 AA accessibility verification framework'), quantifies the deliverable (11 checks a01-a11 plus a Playwright + axe-core script template), and names the sibling it differs from (designesy_score). An agent can distinguish it from designesy_score, designesy_drift_score, and designesy_contract 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?

Explicit both ways: 'Use this to audit a site for accessibility violations' and 'When NOT to use: for a full design-contract score (not just a11y), use designesy_score.' It also pre-empts the most likely misfire by stating the tool does not run the scan, so an agent cannot expect results from this call alone.

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

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 disclose 'Read-only: no side effects' plus the exact return shape and keys. It stops short of stating auth requirements, caching, or rate limits, so it is not exhaustive, but it covers the key behavioral facts for a zero-parameter GET.

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 the purpose, then usage, exclusion, side effects, and return shape in a logical order. There is mild redundancy: the payload keys listed in the opening sentence are repeated verbatim in the 'Returns' sentence, which costs a little length without adding 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?

For a single zero-param read endpoint with no output schema, the description supplies the canonical path, the full set of returned keys, the read-only guarantee, and sibling routing. An agent has everything needed to select and call 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 takes no parameters, which is the baseline-4 case; the description confirms 'No parameters.' Nothing further is needed, and no meaning is missing.

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 agent discovery document (/.well-known/agent.json)') and enumerates the payload contents. It distinguishes itself from siblings by naming designesy_catalog and designesy_contract as the alternatives for narrower 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?

Explicitly gives the use condition ('when you are integrating with or enumerating Designesy as a machine agent and need the canonical discovery/manifest endpoint rather than one specific contract') and an explicit 'When NOT to use' clause routing to designesy_catalog for the package list and designesy_contract for the contract.

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

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 disclose the key traits: read-only, no side effects, no parameters accepted, and the exact JSON response shape. It stops short of things like rate limits or pagination/caching behavior, but for a static catalog listing the safety and output profile 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?

Front-loaded with purpose, then usage, then exclusions, safety, and return shape. Each sentence adds distinct information with no restatement of the name or filler.

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 compensates by enumerating the response fields (package_count, packages[], standing_rules[], machine_exports[]). Combined with the sibling routing and safety disclosure, nothing needed to call this tool 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?

Zero parameters, so the baseline is 4; the description confirms 'No parameters: accepts empty input,' which removes any ambiguity about whether an empty call is valid.

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 ('List the 23 published Designesy packages') and enumerates the returned fields (versions, URLs, statuses), which distinguishes it cleanly from the many scoring/report siblings and from designesy_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?

Gives explicit when-to-use ('discover what Designesy publishes before fetching a specific contract') and an explicit when-NOT-to-use with the named alternative ('if you already know which package you need, skip this and call designesy_contract directly'). This is textbook routing guidance.

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

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

With no annotations, the description carries the full burden and does well: it discloses parallel fetching of both URLs, :root custom-property extraction, the Levenshtein <= 2 rename heuristic, no-browser execution, and ~24h per-URL-pair caching. It stops short of stating auth requirements, rate limits, or failure behavior when a URL is unreachable, 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?

Content is front-loaded with the core purpose before the dimensions, alternatives, and return shape. The long inline JSON return listing is verbose, but since no output schema exists it earns most of its space; a few clauses could still be trimmed.

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 takes on the job of enumerating return fields (score, grade, added[], renamed[], contrastDrift[], etc.), and it does so thoroughly alongside scope, exclusions, and caching semantics. Nothing an agent needs to invoke and 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?

Schema description coverage is 100% and both parameters already carry their own descriptions with examples ('your design system' / 'reference or competitor'), so the baseline is 3. The prose adds role framing ('live URLs') but no format or constraint detail beyond what the schema 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 opens with a specific verb+resource ('Diff two design systems from live URLs') and immediately differentiates itself by naming the mechanism ('URL-scoped design-token diff engine') and enumerating the 8 diff dimensions. An agent can distinguish this from designesy_drift_score and designesy_monitor_score 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 trigger phrasings ('what actually changed between two design systems') and an explicit 'When NOT to use' clause that routes single-site drift to designesy_drift_score and continuous monitoring to designesy_monitor_score. This is the full when/when-not/alternative pattern.

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

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

With no annotations, the description carries the full burden and discloses key traits: read-only, cached ~24h server-side, and the return shape (full contract JSON or a single section). It does not mention auth/permission requirements or rate limits beyond caching, so it falls short of exhaustive disclosure.

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, exclusions, behavior, and return semantics in a logical order. Every sentence earns its place; the section-parameter advice directly informs invocation.

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 correctly covers the return format itself (full contract JSON or a single section). Combined with usage routing and caching notes, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% so the schema already documents the section parameter, giving a baseline of 3. The description adds genuine value beyond the schema by explaining the motivation ('saves tokens when you only need one dimension') and giving a concrete example ('motion' for just the motion tokens).

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 enumerates what it contains (tokens, motion, acoustic, takt, cadence, typography, components, verification rules). It explicitly names sibling tools it is not (designesy_score, designesy_skill_md), so an agent can distinguish it without opening other schemas.

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 ('when you need the actual contract values ... to author, check, or bind a design') and when-NOT-to-use with named alternatives for each condition. Nothing is left to inference for tool selection.

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

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

No annotations are supplied, so the description carries the full behavioral burden and mostly meets it: it declares the operation read-only, states the return payload, and crucially warns that the tool does not evaluate the design itself — the calling agent performs the critique. It also states the default for `rules` (design system v0.4.1). It stops short of covering error behavior or any failure modes, keeping it just under full marks.

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 resource definition, then when-to-use, when-not-to-use, behavior, return shape, and parameter effect — a logical funnel with no filler sentences. The only minor redundancy is restating the rubric-vs-number distinction across two sentences, which could be tightened.

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 correctly compensates by naming the exact return fields ({ rubric, dimensions[8], agent_prompt, output_format, verification_checklist }) and by clarifying the essential non-obvious point that the tool returns scaffolding rather than performing the critique. Nothing an agent needs in order 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 description coverage is 100%, so the baseline is 3, but the description adds real semantics the schema cannot express: that passing artifact/purpose/context/rules yields a pre-filled critique prompt while omitting all four returns the blank framework, clarifying the optional-parameter interaction. It stops short of describing how each field shapes the resulting prompt.

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 Review framework') and enumerates its concrete contents: an 8-dimension rubric with all eight named dimensions, plus agent prompt, output format, and verification checklist. It explicitly contrasts itself with the sibling designesy_score, so the agent can distinguish rubric-delivery from numeric scoring 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 an explicit when-to-use ('when you want a structured rubric to critique a design holistically') and an explicit when-not-to-use naming the alternative tool and the selecting condition ('for a deterministic numeric score, use designesy_score'). Nothing about tool choice 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.

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

With no annotations, the description carries the full burden and does so well: it discloses that execution is server-side, that CSS is extracted from inline and linked stylesheets, that :root custom properties and var() references are parsed, that no browser is needed, and that results are cached ~24h. It does not mention authentication or rate limits, but the behavioral surface is otherwise 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?

Front-loads the purpose, then checks, then usage routing, then execution mechanics, then return shape, then caching. Sentences are information-dense and every one earns its place, including the specific parentheticals defining each failure mode.

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?

Covers everything an agent needs despite having no output schema: it inlines the full return JSON shape (score, grade, pass/warn/fail, checks array), explains execution semantics, and notes the 24h cache. Complete for a single-param scoring 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 single url param (with its default) is already fully documented in the schema. The description adds no syntax or format detail beyond it, 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+resource+scope ('Score a live URL for AI-generated UI drift') and immediately enumerates the 12 checks and the four failure modes it detects. It explicitly names the siblings it is not (designesy_score, designesy_tokens_score), 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?

Gives an explicit when-to-use condition ('verify whether a site is drifting off its own declared token system') and a when-NOT-to-use block that names two alternatives with the exact conditions selecting them (full 42-check contract vs token-file format validation). 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.

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

With no annotations, the description carries the full burden and does so: it discloses that it is executable, fetches the URL, extracts CSS and :root custom properties, produces six specific outputs, requires no browser, returns a detailed JSON shape, and caches results ~24h per URL. This is genuinely rich behavioral context beyond any structured field.

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 outputs before the routing and behavioral details, and each block (outputs, when-to-use, when-not-to-use, execution, return shape) is functional. The return-JSON blob is dense, but it usefully substitutes for the absent output schema rather than being filler.

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 multi-output ingestion tool with no output schema, the description specifies the artifact list, execution model, caching, and full return payload including the score/grade/checks breakdown. Nothing essential to invoking or interpreting it 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 description coverage is 100% and there is only one optional parameter, so the schema already documents the url and its default. The description adds only that ingestion is from 'any design system URL,' which is marginal beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource (generate a frozen build-contract bundle) plus scope (from any design system URL) and enumerates the six concrete artifacts it emits. It also names the sibling tools it is not (designesy_score, designesy_tokens_score, designesy_drift_score), 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?

Explicitly gives the selection condition ('when you need to turn a design system into the file AI agents read and the lint that enforces it') and a full when-NOT-to-use section routing to three named sibling tools by task. 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.

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

With no annotations, the description carries the full burden and largely discharges it: it declares read-only behavior, no side effects, no parameters, and the return format and size (text/plain, ~3000 tokens). It does not mention auth requirements or rate limits, but for a static text fetch that is a minor omission.

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 what the tool fetches, then routes to the alternative, then the behavioral facts. Every sentence adds distinct value with no redundancy, despite the definition being fairly dense.

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, and the description compensates by stating the media type and approximate token size and flagging the embedded agent prompt. For a parameterless static-text tool, nothing an agent needs to call it 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?

There are zero parameters, so the baseline is 4; the description reinforces this with an explicit 'No parameters' statement. No further parameter meaning is possible or 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?

States a specific verb and resource (get the Designesy /llms-full.txt) and enumerates its contents (ingest protocol, discovery endpoints, packages, rules, anti-patterns, agent prompt). It explicitly distinguishes itself from the sibling designesy_llms_txt, so an agent can select 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 ('comprehensive onboarding when the short /llms.txt is not enough') and when-NOT-to-use ('for a quick orientation, use designesy_llms_txt first'), with a quantified cost comparison (~500 vs ~3000 tokens). This is exactly the routing guidance an agent needs.

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

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

With no annotations, the description carries the full burden and does so: it declares the operation read-only with no side effects, states the return medium and size (text/plain, ~500 tokens), and confirms the absence of parameters. Cost/size disclosure and safety profile are both present, leaving no behavioral surprises.

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 payload contents, then the use/when-not-to-use routing, then the operational facts; every clause is informative. The trailing fragment 'No parameters.' is minor redundancy against an already-empty schema, keeping it just short of maximum.

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, side-effect-free fetch with no output schema, the description covers what it returns, its approximate size, its safety profile, and how it relates to sibling artifacts. Nothing an agent needs to invoke it 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?

The tool takes zero parameters, which the rubric sets at a baseline of 4. The description reinforces this with 'No parameters', consistent with the empty schema and 100% coverage, though it adds no further semantic value beyond confirming 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?

States a specific verb ('Get') and resource ('the Designesy /llms.txt') and enumerates the payload (canonical reference, topic index, ingest steps, package list, contact). It also names the sibling tools it must not be confused with (designesy_llms_full_txt, designesy_contract), 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 an explicit use-first rule ('Use this first when you don't know what Designesy is'), a rationale ('cheapest orientation path before pulling heavier artifacts'), and an explicit when-NOT-to-use section that routes to the full brief and the contract tool. Both the selection and exclusion conditions are spelled out.

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

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

With no annotations, the description carries the full burden and meets it: it discloses that an HTML alert email is sent via Resend (requiring RESEND_API_KEY), that it is executable (fetches URL, extracts CSS + :root tokens, computes deltas, no browser), that results are cached ~24h per URL, and it lists the return JSON fields. Effects, dependencies, and side effects are all surfaced.

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 definition is dense and long, but it is front-loaded with the core purpose and the check inventory before routing rules and return shape. The 'when NOT to use' and return JSON are separated into clear segments. Slightly over-packed with check IDs and marketing quote, but every segment 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 3-param, no-annotation, no-output-schema executable tool with external dependencies, the description is complete: it covers inputs, execution model, alert side effects, caching, and the return field list, which substitutes for the missing output schema. An agent has everything needed to call it correctly or route elsewhere.

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

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

Schema description coverage is 100%, so the schema already documents all three params, giving a baseline of 3. The description adds genuine meaning beyond the schema: it explains the history array as prior snapshots for delta computation and the omit-for-baseline behavior, and clarifies the email/alert trigger chain (alerts fire AND email provided AND RESEND_API_KEY set). This is useful semantics layered on top of complete schema docs.

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 URL for continuous design-drift governance') and frames the tool's role as 'the temporal layer over the drift radar.' It enumerates the concrete work (12 drift checks d01-d12, 10 monitor checks m01-m10) and names the exact sibling alternatives, so an agent can distinguish it from designesy_drift_score and designesy_score 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?

Provides explicit when-to-use ('watch a design system over time'), an operational rule for the history param ('Pass a history array ... omit it for a first-run baseline'), and an explicit 'When NOT to use' clause naming two alternatives by name with the condition that selects each. 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.

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

With no annotations, the description must carry the full burden, and it does well: it discloses the execution model (fetches the URL or parses raw JSON, runs checks server-side, no browser needed) and enumerates what is actually checked. It does not mention auth, rate limits, or failure modes on an unreachable URL, so it stops short of a 5.

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

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

Front-loads the core purpose and return shape, which is good, but it spends several sentences on positioning ('fills this gap', 'the only validator that checks both') and DTCG background that inform the agent less than the operational facts. It is longer than it needs to be for a two-parameter validator.

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?

Although no output schema exists, the description supplies the return structure ({ checks[{id, name, status, detail}], valid, score }), the check count/range, and the input mode selection. Combined with the usage guidance, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds a genuine constraint beyond the schema: the mutual exclusivity of url and lottie_file ('Provide exactly one'). That resolves an ambiguity the schema alone leaves open.

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 (validate) and resource (Lottie animation file) with concrete scope (Lottie spec v1.0.1 plus Designesy §16 Motion Standards, returning checks m01-m10). It explicitly differentiates itself from the sibling designesy_score by naming it in the 'When NOT to use' clause.

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 an explicit when-to-use case ('verify a motion/animation asset is well-formed AND accessible') and a when-NOT-to-use case that names the alternative tool ('for full-site motion scoring ... use designesy_score'). This is exactly the routing guidance an agent needs.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the execution model ('fetches the URL and probes the origin via HEAD/GET for each artifact'), that no browser is needed, and a caching policy ('~24h per URL'). These are non-obvious operational traits an agent cannot infer 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?

Front-loaded with purpose, then probes, exclusions, execution, and return shape in a logical order; every sentence earns its place. It is dense but not padded, though the full inline return-shape listing is the only slightly heavy element.

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 annotations and no output schema, the description fully compensates by explaining the JSON return contract (ok, url, score, grade, pass/warn/fail/total, checks[]), the execution model, and caching. An agent has everything needed to call and interpret this tool without opening anything else.

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 fully documented in the schema, including its default. The description adds no format constraints, validation rules, or edge-case meaning beyond what the schema already states, 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 ('Score') and resource ('a URL for design-system AI readiness'), and enumerates the exact 10 artifacts probed, so an agent knows precisely what the tool evaluates. It also positions itself within the designesy family ('the 6th maturity axis') and the sibling set, distinguishing it clearly from adjacent scoring 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?

Provides explicit when-to-use ('verify whether a design system is the default context AI tools build from') and an explicit 'When NOT to use' clause routing to designesy_score for design-contract scoring and designesy_drift_score for AI-drift detection. Nothing is left to inference about tool selection.

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

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

With no annotations supplied, the description carries the full burden and meets it: it discloses that three internal APIs fire in parallel, that each fetches the target URL, that no browser is required, that results are cached ~24h per URL, and that an appUrl/dashboard is produced for io.modelcontextprotocol/ui hosts versus JSON for others.

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, formula, usage, execution, and return shape in a logical order with no filler prose. It runs long, and the full JSON key enumeration plus the 'One input, one output, one composite grade' restatement of the formula are slightly redundant, keeping it short of 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?

For a tool with no output schema and no annotations, the description fully compensates, spelling out the composite formula, the agents it orchestrates, the composite and sub-result return shape, check tallies, and caching/render behavior. 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% for the single 'url' parameter, so the schema already documents it fully. The description adds only the notion that the URL is fetched by each internal API, which is marginal beyond the schema's own description.

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) and frames it as the 'synthesis capstone' of a family. It explicitly distinguishes itself from designesy_score, designesy_drift_score, and designesy_readiness_score by naming each sibling.

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 conditions (need a single holistic assessment instead of three scans, or sharing a verdict) and an explicit 'When NOT to use' block that routes to the correct alternative for each sub-scan. 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.

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

No annotations are provided, so the description carries the full burden and meets it: it discloses server-side fetching, ~24h caching per URL, the MANUAL status for browser-dependent checks and the /api/score/audit escape hatch, and the SKIP (N/A) semantics for inapplicable checks. These are non-obvious behaviors an agent could not infer 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?

Front-loaded with purpose, then exclusions, then execution behavior, then return shape; every section earns its place. The parenthetical category list and status explanations add length that is mostly justified for a 42-check engine, though the format sentence is wasted given it is not a real parameter.

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

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

With no output schema and no annotations, the description steps in with a full return JSON sketch (url, score, grade, pass_count, fail_count, checks[]), status semantics, and caching behavior. The only gap is the phantom 'format' parameter, which makes the tool look richer than its schema allows.

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% for the single 'url' parameter, so the baseline is 3. The description corroborates the default URL behavior but then instructs 'Pass format="canonical"' — a parameter that does not exist in the input schema, which risks an agent emitting an invalid call.

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 against the Designesy design contract'), quantifies the engine (42-check deterministic) and enumerates what it audits (tokens, motion, accessibility, cadence, takt, typography, copywriting). It also names the sibling tools it is not, so an agent can route without opening schemas.

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 'When NOT to use' block with three named alternatives and the condition selecting each (designesy_tokens_score for token files, designesy_motion_score for Lottie, designesy_design_review for qualitative critique). This is exactly the routing guidance the dimension rewards.

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

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

With no annotations, the description carries full burden and does disclose 'Read-only: no side effects' plus the return format (markdown text in SKILL.md format). It does not mention error behavior or limits, but for a zero-param read-only export tool this is nearly complete.

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 tool's identity and purpose, then the when/when-not guidance. Slight redundancy: the '.agents/skills/ or system prompt' destination is stated twice in near-identical wording, which could be trimmed.

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 export with no output schema, the description states what is returned (markdown SKILL.md text) and how to use it. An agent has everything needed to call and consume it.

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

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

The tool has zero parameters, so the baseline is 4. The description confirms 'No parameters,' consistent with the empty 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?

States a specific verb+resource ('Get the Designesy SKILL.md') and defines exactly what the resource is: the agent-skill-format export of the design-system contract. It explicitly differentiates from siblings 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?

Provides an explicit 'Use this when' condition (steering how an agent builds UI) and an explicit 'When NOT to use' clause routing to designesy_contract and designesy_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.

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

With no annotations, the description carries the full burden and largely meets it: it discloses that the tool fetches a URL or parses inline JSON, runs checks server-side, needs no browser, and returns a defined JSON shape. It stops short of permission/auth or rate-limit behavior, but for a read-only validator this 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?

Purpose and the not-use case are front-loaded, which is good, but the description is padded with promotional copy ('84% of teams now using design tokens... every adopting team needs a validator') and a hedged spec-history sentence ('published Oct 28 2025 as a Candidate Recommendation and considered stable') that do not help an agent invoke the tool. Roughly two sentences of pure sales pitch.

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?

Covers purpose, usage, exclusion, execution model, and the return shape (checks with id/name/status/detail, valid, score) even though no output schema exists. Nothing an agent needs to select and call this tool 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 100% so the baseline is 3, but the description adds a constraint not present in the schema: 'Pass url to fetch a remote token file, or dtcg_file to validate an inline JSON string. Provide exactly one.' This mutual-exclusivity rule is genuine added meaning beyond the two property 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?

Specific verb (Validate) plus a precise resource (design token file) against a named standard (W3C DTCG 2025.10). It explicitly distinguishes itself from the sibling designesy_score by scoping to a token file rather than a whole live site.

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 a positive trigger (verify a tokens.json or any DTCG export is structurally correct) and an explicit exclusion ('When NOT to use: for scoring a whole live site... use designesy_score'). The alternative is named with the condition that selects it.

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