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

Annotations (readOnlyHint/idempotent/non-destructive) cover the safety profile and the description is fully consistent with them. Beyond that, it discloses the crucial non-obvious behavior: the tool returns PENDING_EXECUTION checks and a script rather than results, requires a real browser DOM, and needs a local npm install to complete the audit.

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

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

Long, but information-dense and front-loaded: purpose and the 11-check scope come first, then exclusions, then execution caveats, then return shape. A few parentheticals (axe-core version, npm command) could be trimmed, but nearly every sentence carries routing or behavioral value.

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 output schema and no destructive surface, the description is complete: it spells out the return JSON shape, the PENDING_EXECUTION status semantics, the install/run commands, and the sibling tool to use instead. Nothing needed to call or interpret the result 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 real meaning: it explains config's purpose (customizing axe.configure() via branding overrides or rule disables) and the default behavior when omitted ('Omit for standard WCAG 2.2 AA'). It does not discuss the ruleset parameter's tag options, which 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: fetching the Designesy WCAG 2.2 AA verification framework with 11 checks (a01-a11) plus a Playwright + axe-core script template. It explicitly differentiates itself from the sibling designesy_score ('for a full design-contract score (not just a11y)'), so an agent can select it without opening a schema.

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

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

Gives explicit when-to-use ('audit a site for accessibility violations') plus a named when-NOT-to-use case routed to designesy_score. It also clarifies the boundary that this tool does not execute the scan and that the score is produced by the caller's local run.

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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, and the description reinforces 'Read-only: no side effects' without contradicting them. It adds a genuinely non-obvious behavioral trait: fields written as agent steps (e.g. ingest.steps) are stripped from the returned document and their paths reported in omitted_fields. That disclosure is beyond what annotations convey.

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

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

Front-loaded with purpose and usage before any return detail, and the when-not-to-use clause is placed early where it is most useful. The long enumeration of document fields is verbose but largely earns its place because no output schema exists; a tighter summary of the return shape would read better.

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

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

With no output schema, the description carries the return contract itself, naming the output object's fields (kind, source_url, media_type, note, omitted_fields, document) and the shape of the nested document. Combined with the sibling routing guidance, an agent has everything needed to call and interpret this tool.

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

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

The tool takes zero parameters and the description states this explicitly ('No parameters'), which is the correct baseline for a parameterless tool. There is nothing further to disambiguate.

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

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

States a concrete verb and resource (get the /.well-known/agent.json discovery manifest) plus its scope (org identity, authority, endpoints, package index, policy, contact, citations). It explicitly contrasts itself with designesy_catalog and designesy_contract, so an agent can route without opening either schema.

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

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

Gives both a positive trigger ('when integrating with or enumerating Designesy and need the canonical discovery manifest rather than one specific contract') and an explicit negative trigger with named alternatives for the package list and the contract. Routing is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so 'Read-only — no side effects' largely restates structured data. However, because no output schema exists, the description's disclosure of the return shape (package_count, packages[], standing_rules[], machine_exports[]) adds real behavioral context an agent cannot get elsewhere.

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 return shape. Every sentence carries information, though the enumerated return object is somewhat dense; it earns its place given the absence of 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?

For a zero-parameter, read-only listing tool with no output schema, the description supplies exactly what's missing: what it returns, when to call it, and when to skip it. Nothing an agent needs to invoke it correctly is absent.

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 this explicitly ('No parameters — accepts empty input'), which usefully tells the agent no argument construction 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?

States a specific verb (List) and resource (published Designesy packages) with the fields returned (versions, URLs, statuses). It explicitly contrasts itself with the sibling 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 explicit when-to-use ('discover what Designesy publishes before fetching a specific contract') and when-NOT-to-use ('if you already know which package you need, skip this and call designesy_contract directly'), naming the alternative tool by name.

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?

Annotations cover safety (readOnly, idempotent, openWorld, non-destructive), so the bar is lower, yet the description still adds substantive behavioral detail: parallel fetching of both URLs, no browser required, heuristic rename threshold (Levenshtein ≤ 2), and ~24h server-side caching per URL pair. The 'Executable' framing also tells the agent this performs the work rather than just planning it.

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, use cases, exclusions, execution model, and return contract are all front-loaded in that order with no filler sentences. The inline enumeration of the full JSON return shape is lengthy, but with no output schema it is the only place that contract is documented, so it earns its space.

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

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

No output schema exists, so the description carries the return-value burden and does so with an explicit field list (score, grade, added/removed/renamed/valueChanged, scaleDiff, contrastDrift, scoreDelta, checks). Combined with execution semantics, caching, and sibling routing, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100% for both parameters and the schema already explains urlA/urlB semantics, so the baseline is 3. The description reinforces the intent (your design system vs. reference/competitor) and notes both are fetched in parallel, but adds no format, validation, or normalization rules 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?

States a specific verb+resource ('Diff two design systems from live URLs') plus a distinguishing scope claim ('the only URL-scoped design-token diff engine') and enumerates the eight diff dimensions produced. An agent can separate 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?

Gives concrete use-case phrasings ('what actually changed between two design systems', 'how does our design system differ from a reference') and an explicit 'When NOT to use' clause routing single-site drift to designesy_drift_score and continuous monitoring to designesy_monitor_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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds real operational context: a 5-minute server-side cache, the 100 KB / tens-of-thousands-of-tokens size of the default response, and the error behavior for unknown names (returns an error listing all valid keys). It does not cover pagination or truncation semantics for the very large payload, but the added value over annotations is substantial.

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 usage, then the practical size/arg guidance — a sensible order. It is dense with parentheticals and a long enumeration of section names, which adds some bulk, but each sentence carries actionable information and none is 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?

With no output schema, the description must carry the return-shape burden, and it does: default full JSON, the sections-filtered shape, the legacy section shape, the error shape, plus size and caching. For a read-only getter of this complexity, an agent has everything needed to call it correctly and predict the payload.

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 already 100%, so the baseline is 3. The description goes beyond it by framing the relationship between the two parameters ('section (one name) is the older form', 'Prefer sections'), contrasting their return shapes ({id, version, keys} vs {section, data}), and warning that omitting both returns the full large contract — guidance the schema fields only partially state.

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

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

States a precise verb+resource ('Get the Designesy design-system contract') and enumerates the actual contents (tokens, motion, acoustic, takt, cadence, typography, components, verification rules). It explicitly distinguishes itself from sibling tools designesy_score (pass/fail) and designesy_skill_md (export format), 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?

Provides both sides of the decision: 'Use this when you need the actual contract values ... to author, check, or bind a design' and an explicit 'When NOT to use' clause naming the two alternatives and the condition that selects each. This is the textbook 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the 'Read-only' sentence is partly redundant. However, the description adds genuinely new behavioral context: the kit prompt is deliberately NOT included, kit_prompt_url is a human-readable page, omitted_fields is reported, and passing inputs merely records them rather than triggering evaluation. That is real disclosure beyond the annotations.

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

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

Front-loaded with purpose, then exclusion, then behavior, then return shape – a sensible order with no filler sentences. The enumerated return-field list is heavy, but since there is no output schema it earns its place by preventing guesswork about the response.

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

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

With no output schema, the description carries the full burden of describing the return value and does so field-by-field, including which fields may be omitted. Combined with the routing guidance and annotation coverage, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further: it tells the agent that artifact/purpose/context/rules are simply recorded in 'inputs', that all are optional, and that rules defaults to the current contract version. That is semantic value the schema alone does not convey.

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

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

States a specific verb and resource ('Get the Designesy Design Review rubric') and immediately scopes it as a qualitative critique rubric with eight named dimensions. It explicitly differentiates itself from the numeric sibling by noting it is 'a rubric, not a number', so an agent can route correctly 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 ('when you want a structured rubric to critique a design holistically') and a when-NOT-to-use that names the alternative tool ('for a deterministic numeric score, use designesy_score'). This is the full when/when-not/alternative triad.

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?

Annotations already declare readOnly/idempotent/non-destructive/openWorld, and the description adds substantial behavior beyond them: server-side fetch, extraction of inline + linked CSS, custom-property parsing across stylesheets/style blocks/style attributes, no browser required, and ~24h per-URL caching. The caching and no-browser execution model are exactly the operational facts an agent can't get 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 failure modes, usage, exclusions, execution model, and return shape in a logical order. The long parenthetical definitions of each drift failure mode are dense but each earns its place by telling the agent what the score means; slightly longer than strictly necessary.

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

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

With no output schema, the description fully specifies the return JSON shape ({ ok, url, scope, score, grade, pass, warn, fail, skip, total, tokensExtracted, checks[] }) and the execution model, leaving no gap an agent needs before calling or interpreting 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 description coverage is 100% for the single url parameter, including its default, so the schema already carries the semantics. The description only restates that the URL is a live page to scan, adding no format, validation, or edge-case detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

Specific verb ("Score") plus resource ("live URL for AI-generated UI drift") with the exact checks enumerated (12 checks across four named drift failure modes). It explicitly distinguishes itself from siblings by naming designesy_score and 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?

It gives an explicit positive trigger ("Use this when you need to verify whether a site is drifting off its own declared token system"), names "When NOT to use", and routes to two concrete alternatives with the conditions that select them. 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?

Annotations already declare read-only/idempotent/non-destructive, and the description adds substantial context beyond them: it fetches the URL and extracts CSS/:root tokens without a browser, caches results ~24h per URL, reports realistic bundle size ranges (~7 KB to ~530 KB), and specifies that an unknown part name errors with the valid list. No claim conflicts with readOnlyHint=true — generation is local, not a remote mutation.

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, outputs, and exclusions before the operational detail, which is good ordering. It loses a point for redundancy — the valid parts list (tokens, lintConfig, agentRules, componentContract, antiPatterns, designMd) is repeated verbatim twice, and the response-shape sentence is restated with a 'with parts' addendum.

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, and the description compensates fully by spelling out the return shape ({ ok, url, score, grade, pass, warn, fail, total, tokensExtracted, bundle, checks[] }) and the parts-modified variant. Combined with caching, size expectations, and error behavior, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: parts is order-preserving, the response still keeps score/grade/counts/checks while bundle holds only the named files, and omitting parts returns everything. The url default is already in the schema, so this is additive rather than merely restated.

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') and enumerates the six concrete artifacts emitted, so an agent knows exactly what comes back. It also explicitly names the siblings it is not (designesy_score, designesy_tokens_score, designesy_drift_score), making it easy to distinguish from the other 16 designesy 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?

Contains an explicit 'Use this when...' clause plus a dedicated 'When NOT to use' section that routes to three named alternative tools by purpose. It also explains how to narrow output via parts, which is usage guidance for invocation as well.

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false, so the restated 'Read-only: no side effects' is redundant. What the description does add is substantive: it discloses the relative payload size (over ten thousand characters vs a few thousand for the sibling) and, critically, that sections written as steps or prompts are replaced by a one-line marker and listed in omitted_sections — a non-obvious transformation of the returned content that no annotation conveys.

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

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

It is long, but the front-loaded purpose sentence and the labeled 'When NOT to use' and 'Returns JSON' blocks make it scannable, and each clause carries information. Slight redundancy appears where 'Read-only: no side effects' repeats the annotations, but overall the sentences earn their place.

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

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

There is no output schema, so the description carries the return-value burden, and it discharges it with an explicit JSON shape including field names and the meaning of omitted_sections. Combined with the usage routing and size expectation, an agent has everything needed to select and interpret this tool.

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

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

The tool takes zero parameters, which is the baseline-4 case. The description confirms this explicitly ('No parameters.'), matching the empty input schema with no ambiguity.

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

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

States a specific verb and resource ('Get the Designesy /llms-full.txt brief') and enumerates the content scope: authority, discovery endpoints, topics, packages with links, standing rules, anti-patterns. It explicitly differentiates itself from the sibling designesy_llms_txt (short brief) and designesy_contract, so an agent can route without opening any schema.

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

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

It gives explicit when-to-use ('when the short brief from designesy_llms_txt is not enough') and a labeled 'When NOT to use' section naming two alternatives and the conditions that select them (quick orientation -> designesy_llms_txt; the contract itself -> designesy_contract). Nothing is left to inference.

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

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

Annotations already cover readOnly/idempotent/no-side-effects, so 'Read-only: no side effects' is largely redundant. The genuinely additive disclosure is that agent-step sections (e.g. ingest steps) inside the returned content are replaced by a one-line marker and named in omitted_sections — that is non-obvious behavior an agent must know before relying on the text. It also flags the size/cost profile relative to heavier artifacts.

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

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

It is a long single block, but front-loaded (purpose and use-case first, exclusions next, return contract last) and every sentence carries information. The return-shape sentence is dense but necessary since no output schema exists.

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

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

With no output schema, the description supplies the full return contract (kind, source_url, media_type, note, omitted_sections[], content) plus the omission rule, and covers selection, cost, and safety. An agent has everything needed to call it and interpret the result.

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

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

The tool takes zero parameters, which the description states plainly ('No parameters.'), matching the empty input schema. Baseline for a 0-param tool; there is nothing further to document.

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

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

Specific verb+resource ('Get the Designesy /llms.txt brief as reference data') followed by an enumeration of what the brief contains. It explicitly differentiates itself from siblings by naming designesy_llms_full_txt and designesy_contract as the alternatives for adjacent needs.

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

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

Gives an explicit positive condition ('Use this first when you don't know what Designesy is') and an explicit negative one ('When NOT to use') with the two sibling tools that cover those cases. Nothing about tool selection is left to inference.

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

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

Goes well beyond the annotations: it discloses that the tool executes and fetches the URL, extracts CSS and :root tokens, sends an HTML email via Resend only when alerts fire AND email is given AND RESEND_API_KEY is set, requires no browser, and caches results ~24h server-side. These are real behavioral traits (auth dependency, side effect, caching) not derivable from the hints, and readOnlyHint=false / non-idempotent is consistent with a tool that emails and re-scores.

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?

Effectively one dense paragraph but front-loaded: purpose, then mechanics, then when-not-to-use, then return shape. Nearly every clause carries information, though the marketing quote ('weekly audits at cents per report' — Into Design Systems 2026) is decorative padding that could be cut.

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 enumerating the returned JSON keys (ok, url, score, grade, pass/warn/fail/total, snapshots, driftChecks, monitorChecks, alerts, emailAlert) and the server-side caching behavior. An agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds genuine meaning for history ('prior snapshots for delta computation; omit for a first-run baseline') and reinforces the conditional email behavior. It adds usable semantics beyond the schema but does not, for example, explain the expected shape/ordering of the history snapshots.

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?

Opens with a specific verb+resource ('Score a URL for continuous design-drift governance') and immediately frames its scope as 'the temporal layer over the drift radar', distinguishing it from the point-in-time siblings. It enumerates the concrete checks (d01-d12, m01-m10) so an agent knows exactly what work happens.

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 positive guidance ('watch a design system over time', pass history for deltas vs omit for a baseline) plus a dedicated 'When NOT to use' clause naming the alternatives designesy_drift_score and designesy_score with their selecting conditions. This is the textbook routing 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?

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), and the description adds substantial context beyond that: which checks are executable vs. SKIP, why m08 returns WARN instead of FAIL, why m09/m10 skip, the PASS/WARN/FAIL/SKIP scoring formula, and that no browser is needed. It even inlines the full return-object shape, which is unusually generous given no output schema exists.

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

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

Front-loaded with purpose, then checks, then usage boundary, then mechanics — a logical order with zero filler sentences. It is admittedly dense and long, and the m01-m10 list is partly redundant with the checks[] return description, which keeps 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 two-parameter read-only validator with no output schema, the description supplies everything needed: input mode selection, per-check semantics including the non-obvious SKIP/WARN rationale, the scoring formula, and the full response field list. Nothing material is left for the agent to infer.

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 goes beyond the schema by stating the mutual-exclusivity rule ('Provide exactly one') and clarifying that url triggers a fetch while lottie_file parses inline JSON — a constraint the flat schema cannot express on its own.

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 — 'Validate one Lottie animation file against the Designesy motion contract' — and immediately enumerates the ten checks (m01-m10) it runs, so the agent knows exactly what the tool inspects. It also differentiates itself from the sibling designesy_score, which handles site-wide motion CSS rather than a single asset.

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

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

Contains an explicit 'Use this to...' statement plus a 'When NOT to use' clause routing the agent to designesy_score for whole-site motion CSS. It further constrains invocation with 'Pass url..., or lottie_file... Provide exactly one,' leaving no ambiguity about when and how to call it.

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?

Annotations already mark this read-only, idempotent, open-world, non-destructive, but the description adds material context beyond them: it fetches the URL and probes the origin via HEAD/GET, needs no browser, and caches results ~24h server-side. It also enumerates the ten artifact probes performed, telling the agent exactly what side effects and network behavior to expect.

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 core purpose in the first clause, and each subsequent sentence carries distinct payload (exclusions, execution model, return shape, caching). The enumeration of all ten probed artifacts is slightly list-heavy but is genuinely informative rather than 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?

With no output schema present, the description compensates by spelling out the return JSON shape (ok, url, score, grade, pass/warn/fail counts, checks[]), plus execution model, caching behavior, and exclusion routing. Nothing an agent needs to call 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?

Schema description coverage is 100% and the single url parameter's default is already documented in the schema, so the description adds no new syntactic or semantic detail about the argument. Baseline 3 applies when the schema fully carries parameter 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?

States a specific verb+resource (score a URL for design-system AI readiness) and scopes it precisely as the '6th maturity axis'. It explicitly names the sibling tools it is not (designesy_score, designesy_drift_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 both the positive trigger ('verify whether a design system is the default context AI tools build from') and explicit exclusions with named alternatives ('for full design-contract scoring, use designesy_score; for AI-drift detection, use designesy_drift_score'). This is exactly the when/when-not/alternatives 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?

Annotations already declare readOnly=true, idempotent=true, openWorld=true, destructive=false, so the safety profile is covered. The description adds substantial non-annotation behavior: three internal APIs fired in parallel, no browser needed, ~24h per-URL caching, and the 75-100KB / 20k-token payload size. That is real added value, but it never states failure modes (e.g. what happens on an unreachable or non-public URL), which holds it below a 4.

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, then fan-out, formula, routing, cost, and return shape in a logical order, and the return-value sentence is genuinely load-bearing given there is no output schema. It is longer than needed in places — 'One input, one output, one composite grade' and 'the report is the most shareable surface' are rhetorical filler — which keeps it from 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?

With no output schema, the description carries the full return contract and does so thoroughly: the JSON key list, the conditional detail/omitted keys, the composite formula weights, caching, and the MCP Apps dashboard fallback. An agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by quantifying the tradeoff for detail='summary' (4-31KB vs 75-100KB, omitted tracks what was dropped) and confirming 'full' is the default, which is decision-relevant information the enum alone does not convey.

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

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

States a specific verb+resource (generate a unified design-intelligence report for a single URL) and explicitly positions it as the synthesis capstone that fans out to three named engines. It names each sibling it is not (designesy_score, designesy_drift_score, designesy_readiness_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?

Provides explicit when-to-use ('single holistic assessment instead of three separate scans', 'sharing a design-intelligence verdict') and an explicit when-NOT-to-use block that maps each single-engine need to the correct sibling tool. No inference required.

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?

Annotations only cover the safety profile (readOnly, idempotent, non-destructive, openWorld); the description supplies genuinely additive behavior: server-side URL fetch plus CSS extraction, ~24h server-side caching per URL and scope, MANUAL status for browser-dependent checks with the /api/score/audit endpoint that resolves them, SKIP semantics for non-applicable checks, and a 27-of-45-check offline fallback that annotates its own result with engine/scope and degrades the non-default formats to errors.

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

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

Front-loaded with purpose, then exclusions, then behavior and output contracts — a logical order. It is long, and the fallback/format cross-product is explained at a level of detail some agents won't need, but every sentence carries operational information rather than 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?

With no output schema, the description assumes the full burden of describing returns and does so: the designesy JSON field tree (summary, checks, tokens_extracted, note), what each alternate format yields, the manual/skip statuses, and the fallback's added fields. An agent has everything needed to call it and interpret the response.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description goes beyond it: it explains that format changes the returned document structure (native JSON vs review-findings.json vs markdown vs @google/design.md), that scope auto-detects by host (contract for designesy.org, universal otherwise), and that in offline fallback only the default format succeeds while the other three error out. No syntax/size constraints or defaults beyond the schema are added, so it stops short of a 5.

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

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

States a specific verb+resource+mechanism: 'Score a live URL against the Designesy design contract with the deterministic 45-check verification engine.' It names the exact endpoint and enumerates the check categories (tokens, motion, accessibility, cadence, takt, typography, copywriting), so it is unmistakable among the 16 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?

Contains an explicit 'When NOT to use' block that routes to three named siblings by distinct condition (token-file validation → designesy_tokens_score, Lottie file → designesy_motion_score, qualitative critique → designesy_design_review). When-to-use is also stated directly ('audit whether a website or AI-generated UI complies').

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?

Annotations already declare readOnly/idempotent/no-destructive, but the description adds context the annotations cannot: it documents that sections written as agent steps or prompts are replaced with one-line markers, names them in omitted_sections, and warns the content runs tens of thousands of characters. That omission behavior is a genuine, non-obvious trait an agent must know before relying on the output.

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

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

Front-loaded with the purpose and the when/when-not routing before the return-format detail, so the critical selection information lands first. It is longer than strictly necessary because the inline return-shape description is dense, but every sentence carries actionable information.

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

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

With no output schema, the description carries the full burden of documenting the return value and does so precisely (kind, source_url, media_type, note, omitted_sections, content), including the truncation semantics. Combined with the routing guidance, an agent has everything needed to call it and interpret the result.

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

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

The tool takes zero parameters and the schema is empty, so the baseline is 4. The description states 'No parameters' explicitly, which is correct and consistent with the schema, but adds no further parameter meaning to give.

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

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

States a specific verb and resource ('Get the Designesy SKILL.md') plus the exact export format ('agent-skill-format export of the design-system contract') and its intended destination (.agents/skills/ or a system prompt). It explicitly distinguishes itself from designesy_contract and designesy_score, so an agent can select it without opening any schema.

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

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

Gives an explicit positive trigger ('Use this when the user wants the contract in that form') and an explicit negative trigger ('When NOT to use'), naming the correct alternatives for the excluded cases (designesy_contract for raw JSON, designesy_score for scoring). Nothing is left to inference.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description goes well beyond them: it discloses the execution model ('fetches the URL or parses raw JSON you provide, runs 10 checks server-side, no browser needed'), the exact scoring formula, and the SKIP-is-unscored rule. That is substantive behavioral context an agent cannot get from the annotations.

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

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

The purpose and NOT-to-use routing are front-loaded and the return-shape enumeration is valuable given no output schema. But the sentence about '84% of teams ... zeroheight Design Systems Report 2025' is marketing padding that does not help invocation, and the 'Candidate Recommendation and considered stable' clause is redundant with the already-stated 2025.10 Final report.

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

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

With no output schema, the description carries the return contract itself, listing every field (score, grade, checks[{id,status,detail}], etc.) and the scoring math. Combined with the parameter exclusivity rule and the sibling routing note, an agent has everything needed to call and interpret this 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 two parameters are already documented; the description nonetheless adds the mutually-exclusive constraint ('Pass url ... or dtcg_file ... Provide exactly one') that the schema does not encode. It stops short of adding format expectations beyond the schema, so a 4 rather than a 5.

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

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

States a specific verb+resource ('Validate a design token file against the W3C DTCG ... spec') and immediately scopes it as 10 conformance checks on a token file. It explicitly differentiates itself from the sibling designesy_score, so an agent can route without opening either schema.

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

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

Gives an explicit when-to-use ('verify a tokens.json or any DTCG token export is structurally correct') and an explicit when-not-to-use with the named alternative ('for scoring a whole live site, use designesy_score'). Nothing about selection is left to inference.

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