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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful context beyond that: the checks are deterministic, run at design time, and return 'exact ratios, pass/fail, and fixes' instead of just an audit result. No contradiction with annotations.

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

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

Two dense sentences that front-load the tool's purpose and scope, then provide the alternative. Every clause adds information; there is no fluff or repetition of the schema.

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

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

Although there is no output schema, the description explains what the tool returns: exact ratios, pass/fail, and fixes. Combined with comprehensive parameter schemas, clear scope boundaries, and an explicit pointer to the alternative tool, this is complete for safe invocation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds meaningful context by specifying platform thresholds (iOS 44pt, Android 48dp, web 24px/44px) and the WCAG 2.2 contrast rules, which directly inform how tap_targets and contrast_pairs are evaluated.

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: 'Deterministic design-time accessibility checks' for WCAG 2.2 contrast and tap/target sizes. It clearly separates this tool from other design audits and explicitly routes non-mechanical a11y checks elsewhere, making it easy to tell apart from siblings.

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

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

The description explicitly defines when to use this tool: the 'machine-verifiable slice of a11y you can run before code.' It also names the alternative for keyboard/screen-reader/Dynamic Type checks with get_design_doc('accessibility'), giving clear exclusion criteria.

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?

Beyond the read-only and idempotent annotations, the description discloses that it builds nothing, starts no emulator, takes no screenshot, and cannot produce rendered-output, contrast, TalkBack, or Play review findings. It also explains that silence can mean the Android-project gate rather than a passing result and that the report exposes notVisible items derived from the run.

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

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

The description is long but front-loaded with the purpose and then proceeds logically through configuration, Compose signals, behavioral limits, output shape, error handling, and companion docs. It earns its length for a complex tool, though there is minor redundancy around snippet mode and configuration being the backbone that 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?

For a tool with high complexity, the description covers the input contract, platform inference, configuration-sensitive rules, output format, notVisible semantics, error behavior, and related documentation. There is no critical missing context an agent would need to select and invoke this tool correctly.

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

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

The schema already documents both parameters at 100% coverage, so the baseline is 3. The description adds meaning by clarifying that path refers to a project or module directory, that absolute paths are preferred, that code is rejected rather than ignored, and that missing paths or file paths produce an error result rather than an empty audit.

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 action and target: 'Audit an Android app's UI against Material 3 and android-app-design' and explains the mechanism by reading AndroidManifest.xml, resource XML, and Kotlin. This clearly distinguishes the tool from sibling audits like audit_apple_ui and audit_generic_design by platform and audit basis.

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

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

It gives clear invocation context: point it at a project or module directory, directory-only, no snippet mode, a code argument is rejected, and a missing path or file path returns an error. It also suggests pairing with get_design_doc for rule guidance, but it does not explicitly name sibling alternatives or state when-not-to-use conditions beyond the snippet limitation.

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, and the description adds substantial behavioral detail: it builds nothing, runs no simulator, takes no screenshot, reports platform inference, and returns a notVisible list of unchecked items. No contradiction exists between description and annotations.

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

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

The description is front-loaded with purpose and information-dense, but it is a lengthy block with redundancy ('no snippet mode' appears multiple times) and a long enumeration of rules and output fields. It earns its place for a complex tool, but could be tighter and better structured.

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

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

The description covers purpose, input requirements, surfaces read, rule categories, platform inference, output structure, error handling, and complementary tools. An output schema exists, but the description still explains what the findings contain, making the tool well-specified for an agent to call correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning by clarifying that a path must be a directory, that missing/file paths return error results rather than empty audits, and why code is rejected. This goes slightly beyond the schema's parameter descriptions.

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

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

The opening sentence states a specific verb and resource: 'Audit an iOS or macOS app's UI against Apple's own documentation.' It further specifies the project surfaces read and lists the eight rules, making the tool unmistakably distinct from siblings like audit_android_ui, audit_accessibility, and generic design audits.

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

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

The description gives clear context: point it at the project directory, directory only, no snippet mode, and code/missing path/file are errors. It also suggests pairing with get_design_doc calls. However, it does not explicitly name sibling alternatives (e.g., 'use audit_android_ui for Android projects') to provide when-not-to-use guidance against specific alternatives.

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 the tool read-only, idempotent, and non-destructive; the description reinforces this with 'Deterministic static analysis' and 'paste source,' implying no side effects and no external repo access. It adds context about the return value, including a consolidation plan, though it does not mention limits like input size or exact response structure.

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

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

Three dense sentences cover what the tool measures, when to use it, and how it relates to a sibling tool, with no filler. The output metrics are front-loaded, making the core purpose immediately clear before the use cases and comparison.

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

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

For a one-parameter, read-only analysis tool, this is nearly complete: input format, output highlights, use cases, and sibling differentiation are all covered. Since there is no output schema, a bit more detail on exact return shape or constraints would make it fully complete, but the description is still sufficient for correct tool selection.

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

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

The single code parameter already has a clear schema description, including concatenating multiple files, so schema coverage is 100%. The tool description adds value beyond the schema by naming accepted formats: 'CSS / SCSS / Tailwind / JSX source,' which helps an agent know exactly what input 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?

The description states a specific verb and resource: 'Measure how systematic an existing UI really is' and enumerates concrete outputs like consistency score, color/spacing/token sprawl, near-duplicates, and off-grid values. It also distinguishes itself from design_lint by explicitly contrasting a 'whole-codebase view' with 'per-line anti-patterns.'

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 scenarios: 'Use it before a redesign, on an inherited codebase, or to prove a design system is (or isn't) being followed.' It also names the relevant alternative tool, design_lint, and explains how the two complement each other, giving an agent clear 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?

Beyond the annotations' readOnly/idempotent hints, the description discloses concrete behavioral boundaries: no checkout is completed, no countdown is timed, no warehouse is queried, and no consent banner is clicked. It also states that findings are not verdicts on the business, which is critical context for interpreting results.

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

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

The description is detailed yet tightly organized: purpose first, then behavioral caveats, then return contents, then usage pairing. Every sentence earns its place; the explicit 'not doing' list prevents harmful assumptions without being padded.

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 one required parameter, an output schema, and detailed annotations, the description still adds valuable context: the exact patterns checked, the return shape including the notVisible list, and the limitation that nothing is actually measured. Agents have everything needed to invoke and interpret the tool correctly.

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

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

Schema description coverage is 100%, so the code parameter is already well documented. The description adds marginal context by calling it a 'pasted snippet' and emphasizing 'Snippet only,' but it does not need to add more meaning because the schema handles the definition.

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

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

The description starts with a specific verb and resource: 'Audit a pasted snippet for named deceptive-pattern tells from ethical-design.' It then enumerates the exact patterns checked, making the tool's scope unmistakable and clearly distinct from broader design or accessibility audits.

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

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

The description explicitly scopes usage with 'Snippet only — there is no directory mode' and advises pairing with get_design_doc('ethical-design') and a human reviewing the render. This gives clear when-to-use and when-not-to-use guidance, though it does not name a specific alternative for full-page audits.

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 declare readOnly, idempotent, and non-destructive, and the description reinforces this with concrete behavior: 'it makes no network request, renders nothing,' and no finding is or can be a rendered-output or aesthetic judgement. It discloses non-obvious scoring semantics ('each rule counts once no matter how many times it fires'), directory-mode exclusions of story/test/fixture files, and reports how many files it skipped. This adds substantial behavioral context beyond what the annotations alone convey, with no contradiction.

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

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

Dense but well-segmented: it moves from the audited pattern list to the reporting stance, output format, edge cases, and finally sibling pairings, with no filler phrases. It runs long (~280 words), and some output-format detail (findings fields) overlaps with the existing output schema, so a small trim was possible; still, nearly every clause carries non-redundant operational 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 3-param, 0-required tool with annotations and an output schema already present, the description covers everything an agent needs: detailed scope, output shape, scoring semantics, file exclusions, language limitation, error behavior, and sibling pairings. Because the output schema already defines return values, the description correctly focuses on behavior and selection criteria instead of restating structure.

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%, with each parameter (code, path, filename) already documented, including the filename nuance that the typeface check uses it to tell a landing page from a dashboard. The description adds behavioral context around the path parameter (directory-mode exclusions) and the error result, but the schema already carries the parameter definitions, so the description reinforces rather than compensates. Baseline 3 is appropriate since the structured data does the heavy lifting.

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

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

States a specific verb and resource: 'Audits a web project or snippet' for a precisely enumerated set of generic-design defaults (stock Tailwind gradients, default typefaces, emoji icons, card recipes, hype copy). It further distinguishes itself by its factual stance — 'reports facts, not taste' — and explicitly positions itself against siblings like audit_project and design_review_checklist, so an agent can tell it apart 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?

Gives explicit pairing guidance: use design_review_checklist or get_design_doc for actual critique, audit_project for design drift, and this tool for factual generic-default detection. It also documents when to pass a snippet (code) vs a directory (path), states the English-only copy-rule limitation, and defines the error result for missing paths — leaving no ambiguity about when to invoke 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?

The description goes well beyond annotations by stating it reads source and does not measure: no page loading, no timing, and no Core Web Vitals verdicts. It also discloses behavioral edge cases such as narrow hero rules, a machine-readable notVisible list of unchecked items, and a missing path returning an error result rather than an empty audit. No contradiction with readOnlyHint, idempotentHint, or destructiveHint.

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

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

The description is long, but the tool is genuinely complex and every sentence carries decision-relevant information: scope, examples, limitations, error behavior, return shape, and sibling pairings. The purpose is front-loaded and the added caveats prevent misuse, so the length is appropriate.

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

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

Given the output schema already documents return values, the description covers everything needed for selection and invocation: what the tool audits, what it does not do, how it handles files and filenames, how errors appear, and which siblings complement it. An agent would be unlikely to misuse or under-use 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 coverage is 100%, so the schema already documents all three parameters. The description adds meaningful nuance beyond the schema, especially that path audits every file on its own and does not let a stylesheet in another file size an image in this one, and that filename changes how rules read a component versus a stylesheet. This extra context helps invocation correctness.

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

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

The description names a specific verb and resource: audit a page, component, or web project for source-level performance signals, with concrete examples. It explicitly contrasts itself with measurement tools like measure_screenshot by stating it loads nothing and times nothing, so it is clearly distinguishable from audit_accessibility, audit_seo_geo, and the other audit 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?

The description gives explicit guidance on when not to use it: 'do not call it expecting a vitals report.' It also names the complementary sibling tools to pair with for different signal types, audit_seo_geo and measure_screenshot, and surfaces limitations around hero rules and missing paths. This is strong usage-direction.

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, but the description adds substantial context beyond them: 'it loads no page, renders nothing, takes no screenshot, and no finding is or can be a rendered-output result'; 'Reads only the directory you name; makes no network call'; and the error-handling trait 'A missing or non-directory path is returned as an error result, not as an empty audit' plus the file/byte-cap warning. These are exactly the behavioral traits that prevent misuse, and nothing contradicts the annotations.

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

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

The description is long but earns nearly every sentence: it front-loads the core purpose, then covers output shape, safety profile, sibling routing, error behavior, and pairing. Given 35 siblings and a complex multi-part return, the density is justified. Minor redundancy exists ('Cross-file drift... which is the point of this tool' restates the opening's 'instead of a pasted snippet'), 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?

For a tool of this complexity, nothing essential is missing: inputs (directory + extension override), behavior (read-only, no network), return shape summarized (findings, severity summary, notVisible, scan block) with the output schema covering details, error semantics, exclusions, alternatives, and a cap-related caution that protects against false-negative conclusions. The output schema exists, so the description correctly delegates return-value details to 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 description coverage is 100%, so the baseline is 3; the schema's `extensions` documentation is already exhaustive (leading-dot requirement, replacement semantics, default list, .js/.ts exclusion rationale). The description reinforces the `path` meaning ('point it at a directory') and warns to check the `scan` block, but adds little parameter-specific meaning that the schema doesn't already carry. The schema does the heavy lifting, which the rubric treats as acceptable.

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 pair ('Audit a real codebase... point it at a directory') and precisely enumerates what the tool does: walk design source, run design/accessibility lint over every file, score consistency (colors, type sizes, radii, shadows, spacings), and flag indistinguishable duplicates. It distinguishes itself from siblings by name (audit_security, audit_generic_design, audit_seo_geo, audit_performance, design_lint, measure_screenshot, audit_ux_copy), so an agent can tell exactly which tool to pick.

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

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

The description gives explicit routing: 'It runs design_lint's rules and the consistency count, and nothing else: run audit_security, audit_generic_design, audit_seo_geo and audit_performance on the same directory for theirs.' It states when the tool is the right choice ('Cross-file drift is the thing a single-file lint cannot see') and even gives pairing guidance ('Pair with measure_screenshot for the rendered result and audit_ux_copy for the words'). Exclusion is explicit and actionable.

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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses static-only behavior, no network evaluation, header parsing as text rather than execution, error handling for missing or non-directory paths, and the structured output shape including the `notVisible` list. This is exactly the behavioral context an agent needs beyond structured metadata. No contradiction with annotations 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?

The opening sentence front-loads purpose effectively, and the long enumerations of security rules and config-file locations are dense with actionable detail rather than fluff. However, the description is quite long and could be more scannable with structured lists, so it earns four rather than five.

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 this complexity, the description is remarkably complete: it covers input modes, detection scope, framework inference, limitations, return format, error behavior, and related sibling tools. The output schema already handles return-value documentation, so the description does not need to repeat that. Nothing essential for correct selection or invocation appears to be 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?

Although schema coverage is 100%, the description adds genuinely new meaning: `path` is required for configuration and header rules while `code` is source-rules-only, absolute paths are strongly preferred, and `filename` affects rule interpretation by extension. This helps an agent select and fill parameters correctly in a way the schema alone does not.

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

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

The description opens with a precise verb-object pairing: 'Audit a web project or snippet for security defects a frontend actually ships.' It enumerates concrete defect categories, making the tool's scope unmistakable. It also distinguishes itself from siblings by explicitly pairing with audit_project and audit_accessibility for other concerns.

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

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

The description gives clear when-to-use context by scoping to source-based frontend security checks and explicitly stating what it cannot do: 'it makes no request to your site, tests no live endpoint, and no finding is or can be a penetration-test or vulnerability-scan result — so do not call it expecting one.' It also names companion tools for adjacent use cases, helping an agent route correctly.

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=true and destructiveHint=false, and the description reinforces them with concrete behavior: 'no request is made to your site, nothing is rendered'. It goes well beyond annotations by disclosing the proof policy for absence claims, the cap's downgrading of claims to 'unconfirmed notes', and the error result for missing/non-directory paths — all genuinely useful behavioral context.

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

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

Every sentence carries information, and the definition is appropriately sized for a complex tool with exclusions, modes, and sibling routing. However, it is delivered as one dense unbroken paragraph — the long enumeration of checks is a sprawling run-on — which makes it harder for an agent to parse quickly than the content justifies.

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, two-mode tool with an output schema, the description is complete: it enumerates all rule categories, states the safety profile, explains the absence-proof policy and cap behavior, describes the return shape, documents the error condition, and routes to complementary tools. Nothing an agent needs to invoke 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. The description adds real meaning above the schema: that code mode runs 'page rules only', that path mode is needed for robots.txt/llms.txt/sitemap rules, and that filename is 'load-bearing' because a plain HTML file can prove metadata absent while a framework component cannot. This explanation of the code/path/filename interplay is valuable beyond the field descriptions.

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

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

The opening sentence states a specific verb ('Audit') and resource ('SEO and GEO signals that are actually in the source') and enumerates an exhaustive, concrete list of checks. It further sharpens the definition by stating what it is not ('no request is made to your site... not a vitals or ranking report'), which cleanly distinguishes it from audit_performance and other 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?

The description gives an explicit when-not ('do not call it expecting a vitals or ranking report'), names complementary siblings with their distinct roles ('audit_performance for the delivery signals, audit_ux_copy for whether the writing earns the click, seo_geo_guide for the guidance behind the rules'), and even tells the agent which mode is the 'useful mode' (path over code). This is exemplary 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?

Beyond the readOnly/idempotent annotations, the description discloses important non-obvious behaviors: it reads source and does not measure anything, has no concept of register, and may falsely flag technical documentation for jargon/filler. This significantly shapes how an agent should interpret results.

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

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

The description is information-dense and front-loads purpose, but the final sentence enumerating the output structure is verbose and partially redundant with the markdown/metrics repetition. Every sentence does add value, though the length is slightly more than needed.

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

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

For a single-parameter tool with an output schema, the description thoroughly covers the return shape, limitations, and relationship to sibling tools. An agent has everything needed to call it correctly and interpret its 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?

The schema already provides full coverage for the single 'text' parameter with concrete examples of acceptable input. The description adds no additional parameter-level semantics, so the baseline of 3 applies.

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

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

The description starts with a specific verb ('Audit') and a well-defined resource ('UI / marketing copy') followed by an explicit list of metrics. It also distinguishes itself from the voice/tone-oriented sibling get_design_doc, making its scope clear among many audit_* tools.

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

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

The description explicitly says to pair with get_design_doc('ux-writing') for voice/tone judgment, giving a clear alternative for non-machine-checkable aspects. It also specifies what the tool cannot do (no usability claims, no register awareness), which helps an agent decide when not to use 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 establish readOnlyHint, idempotentHint, and non-destructive behavior. The description goes further by revealing the concrete return shape — a side-by-side table of conventions, porting rules, and an explicit 'do NOT port' list — and by emphasizing the one-problem scope, which is useful contextual behavior 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?

The description is composed of three substantive sentences that front-load the core action and then provide output and use-case detail. The long enumeration of design problems mostly mirrors the schema enum, introducing minor redundancy, but the overall structure remains tight and scannable.

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

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

With no output schema, the description compensates well by explicitly describing the side-by-side table, porting rules, and do-NOT-port list. Schema coverage is 100%, annotations clarify the read-only safety profile, and the use cases are stated. An agent has everything needed to decide whether and how to invoke 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%, so the schema already documents both topic and platforms with examples. The description reinforces that topic is a design problem and platforms become columns, but it adds no new syntactic or semantic detail beyond what the schema provides, so the baseline 3 applies.

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

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

The description opens with a specific verb ('Compare') and a clearly delimited resource: how iOS, Android, macOS, and web each solve ONE design problem, with the problem categories enumerated. This strongly distinguishes it from sibling tools like get_design_language or search_design_knowledge, making its cross-platform comparative purpose unmistakable.

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

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

Provides explicit use conditions: 'when building the same product on more than one platform' or 'when deciding whether a pattern that works on one platform belongs on another.' It does not, however, name alternatives or state when not to use it, so it stops short of full exclusion 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?

Annotations already carry readOnlyHint=true, idempotentHint=true, and destructiveHint=false, lowering the bar. The description adds genuinely useful behavioral context: outputs are platform-dependent ('CSS/Tailwind or SwiftUI/Compose'), one deliverable is conditional ('a stock-region fact if the seed sits in indigo/violet/purple'), and 'ready-to-paste' clarifies the tool returns artifacts for the user to apply rather than persisting state. No contradiction with the readOnly annotation since the generation is computational, not a state 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?

The usage rule is front-loaded at the end of the description and the headline is punchy, but the opening sentence is a single dense run-on enumerating ten artifacts with nested parentheticals ('named defaults to leave, the type pairing as a decision, one signature move, and a stock-region fact...'). The marketing phrase 'THE one-call foundation' adds emphasis but little functional value, and the wall-of-text structure makes scanning harder than it needs to be.

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

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

With no output schema, the description bears the return-value burden and largely carries it: it lists every generated artifact, explains the conditional and platform-dependent behaviors, and names the workflow that follows. The only real gap is that the response envelope (structure/format of the returned design system) is unspecified, though the artifact list makes the return content predictable for a 4-parameter generation 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% — all four parameters have meaningful descriptions with examples and defaults, so the baseline is 3. The description reinforces the relationship (brand_color + vibe + platform drive the whole output) and notes platform 'picks icon set and token output,' but adds no syntax or format details beyond what the schema already provides.

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

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

States a specific verb+resource: 'Turn a brand color + product vibe + platform into a complete, coherent design-system starter' and enumerates concrete deliverables (direction card, tokens, type scale, elevation ramp, components, build checklist). It differentiates from the many design siblings by positioning itself as the 'one-call foundation' and naming get_component_recipe and get_design_roadmap as the follow-up 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?

Explicitly instructs: 'Use this FIRST when someone says design/build me a website/app to lay the foundation, then get_component_recipe for each component and get_design_roadmap for the full process.' This gives an agent a clear decision rule, sequential ordering, and named alternatives without leaving anything 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 readOnlyHint, idempotentHint, and destructiveHint, and the description reinforces and extends this with valuable behavioral context: 'It reads source and does not measure anything: nothing is rendered, no contrast ratio is computed and no tap target is sized.' It also discloses the output shape (markdown plus structured findings, severity summary, machine-readable notVisible list), so an agent understands the tool's limits and return value beyond what the annotations convey. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and anti-pattern list, then progressively covers limitations, output structure, and tool relationships. It is longer than average but every sentence adds meaningful information. There is minor redundancy between 'Returns findings with line numbers, severity, and fixes' and the later structured-output breakdown, but this is acceptable given the added specificity.

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

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

For a simple one-parameter read-only tool with an output schema and rich annotations, this description is complete. It covers accepted input languages, checked anti-patterns, limitations, output format, and the relationship to design_review_checklist. An agent has all the information needed to invoke it correctly and interpret its 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 coverage is 100% and the single 'code' parameter is described as 'The HTML/CSS/JSX/Tailwind snippet to lint.' The description adds extra semantic value by enumerating the anti-patterns it checks for, which helps an agent decide what kind of snippet to pass and what to expect. It does not add format-specific parsing details, but with one well-documented parameter, the marginal gain is modest yet real.

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

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

The description names a precise verb and resource: 'Lint a snippet of HTML / CSS / JSX / Tailwind for design & accessibility anti-patterns.' It lists concrete patterns (hardcoded colors, px font-sizes, removed focus outlines, clickable divs, etc.), making the tool's scope unmistakable. It also differentiates itself from sibling tools by explicitly stating what it does not do: no rendering, no contrast ratio computation, no tap target sizing.

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

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

The description gives explicit when-to-use context ('Fast static design-time check') and when-not-to-use context ('not a replacement for a full audit'). It names a complementary sibling (design_review_checklist) and warns that findings are not visual or accessibility verdicts, steering agents away from using it in place of measurement-based tools.

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 establish read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond that by stating the checklist is assembled from the knowledge base and includes key rules and anti-patterns per area, implying no live design analysis is performed. No contradiction with annotations.

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

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

Two sentences with no filler. The primary action and output are front-loaded, and the second sentence clarifies practical use. Every word earns its place.

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

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

For a tool with two enum-bounded parameters and no output schema, the description is largely complete: it defines the output, how it is assembled, and how it should be used. It does not explicitly mention the focus parameter, but the schema covers that, so no significant gap remains.

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 parameters are already well documented. The description adds only general context around 'areas' and project types, but does little to explain the focus parameter beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states a specific action ('generate a structured design-review checklist') on a specific resource (project type), and explains what the checklist contains. It distinguishes itself from audit tools by framing the output as a checklist for auditing rather than an audit itself, though it does not explicitly name sibling tools.

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

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

The description gives clear usage context: use the checklist to audit an existing design or as acceptance criteria for a new one. It does not mention alternatives or exclusions, but the intended use cases are concrete enough to guide an agent.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: it returns a corrected value rather than a pass/fail report, preserves hue/saturation, and nudges lightness. It could mention whether the function returns both colors or just the adjusted one, but with strong annotations this is a minor gap.

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

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

Three sentences with no wasted words. The core operation and key constraint are front-loaded, and the sibling routing is compact at the end. Every clause earns its place.

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

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

For a 4-param tool with 100% schema coverage, no output schema, and strong annotations, the description is nearly complete. It explains the algorithm, the scope, and the alternatives. The only missing context is exactly what the return value looks like (single hex? pair? object?), but since no output schema exists, that information would have been valuable. Still, the tool is simple enough that the gap is small.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds useful context by explaining the default behavior ('foreground' as the text, target default 4.5, and the meaning of different targets), but it doesn't deeply elaborate on parameter formats beyond what the schema provides. A 3 is appropriate because the schema carries the heavy lifting and the description adds modest interpretive value.

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

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

The description states a specific verb ('Repair'), a precise resource (color pair contrast), and the algorithm's intent (nearest accessible color, hue/saturation preserved, lightness nudged). It explicitly distinguishes itself from audit_accessibility and generate_color_system, so an agent can separate it from siblings without inspecting their 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?

It gives explicit when-to-use ('when audit_accessibility flags a pair') and when-not-to-use ('For a full pass/fail audit use audit_accessibility; to build a whole palette use generate_color_system'), naming the alternatives directly. No inference is 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?

Beyond the readOnly/idempotent/destructive annotations, the description discloses deterministic behavior, WCAG 2.2 checking with auto-adjustment, and that it returns a real generated palette rather than advice. This gives the agent strong expectations about side-effect-free but substantive 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?

Every sentence earns its place: the first defines scope and output, the second explains the accessibility guarantee, and the third conveys determinism and downstream steps. The description is dense but not bloated.

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

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

There is no output schema, so the description carries the burden of explaining return value composition, and it does so thoroughly: tonal scale, neutral ramp, light/dark semantic tokens, and WCAG verification. For a one-parameter deterministic generator, nothing essential is missing.

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

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

Schema coverage is 100% and the only parameter, brand_color, is already described as a hex string with examples. The description adds the 'ONE brand color' emphasis but little new parameter-level meaning, 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?

The description states a specific action ('Turn ONE brand color into...') and names the concrete output components: tonal scale, neutral ramp, and semantic tokens. It clearly differentiates from siblings like generate_design_tokens and audit_accessibility by framing this as palette generation followed by those downstream tools.

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

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

The description gives clear usage context: a single brand color in, a full system out, plus an explicit downstream workflow ('Feed the result into generate_design_tokens, then audit_accessibility'). It stops short of stating explicit when-not-to-use cases or alternatives like generate_type_scale or generate_elevation_system.

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 safety traits. The description adds meaningful behavioral context by stating it is 'Deterministic — outputs code, not advice,' which clarifies it does not produce opinions or partial recommendations. No contradiction with annotations.

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

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

Three sentences: the first front-loads the core transform and output formats, the second adds a key behavioral trait, and the third gives the primary use case and a related pairing. Every sentence earns its place with no fluff.

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

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

Given there is no output schema, the description leaves the return structure unspecified — an agent may not know whether the generated 'artifact files' come back as inline strings, a zip, or a structured mapping. It also does not mention that 'format' defaults to 'all' or supports selective output. For a 7-parameter tool producing multi-file output, this is a notable gap, though the rich input schema and clear purpose mitigate 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 description coverage is 100%, so the schema alone documents all parameters with examples and defaults. The description adds modest value by mapping the abstract format enum to real-world outputs ('Tailwind v4 @theme', 'SwiftUI', 'Jetpack Compose', 'W3C DTCG JSON') and grouping the optional scales, but this is marginal beyond the schema.

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

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

The description clearly states a specific verb ('Turn ... into') and a concrete resource ('a design-token spec'), then enumerates the exact artifact formats produced. It distinguishes itself from sibling generators like generate_color_system or generate_type_scale by emphasizing multi-platform, ready-to-use files and 'one source of truth across web, iOS and Android.'

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

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

The description gives a clear use case ('give a project one source of truth across web, iOS and Android') and suggests pairing with audit_accessibility to verify contrast. However, it does not explicitly state when to avoid this tool in favor of more targeted generators like generate_type_scale or generate_color_system, so it lacks explicit exclusions.

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 signal read-only, idempotent, and non-destructive behavior. The description adds useful context beyond annotations by stating the tool is deterministic and by describing what the output includes (CSS custom properties, Tailwind @theme, dark-mode guidance). No contradiction with annotations.

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

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

The description is compact, front-loaded with the primary purpose, and each sentence earns its place. The deterministic note and the one-token-per-level guidance are valuable without bloating the text.

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 appropriately explains what the tool returns: CSS custom properties, Tailwind @theme tokens, and dark-mode guidance. It also communicates the semantic naming scheme. It could be more explicit about output structure or examples, but it is sufficiently complete for a deterministic, read-only generation 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 coverage is 100%, so the schema already fully documents hue, levels, and strength. The description does not add much parameter-level detail, but it does clarify the overall purpose of the generated ramp and the semantic naming convention, which is enough to maintain the baseline score.

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

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

The description clearly identifies a specific deliverable: a cohesive elevation/box-shadow ramp with semantic levels, CSS custom properties, Tailwind @theme integration, and dark-mode guidance. It is distinct from sibling generators like generate_color_system or generate_type_scale because it names its exact output domain and format.

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

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

The description implies when to use the tool: when you need elevation tokens rather than hand-tuning per-component shadows. However, it does not explicitly mention alternatives or state when not to use it, leaving tool-selection guidance mostly implicit.

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?

Beyond the readOnly/idempotent/destructive annotations, the description adds that output is 'Deterministic real code' and states the delivery form: CSS custom properties plus Tailwind v4 @theme. This gives useful behavioral expectations without contradicting any annotation.

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

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

The description is dense but well-structured: the main action and scope lead, followed by a concrete deliverable list, output format, and usage recommendation. Every clause contributes information with no filler; it is slightly long but justified by the tool's breadth.

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 serves as the output contract, listing all generated artifacts, the technical format, and the embedded design rules. Combined with complete parameter schemas and safety annotations, an agent has everything needed to call the tool correctly.

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

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

The description itself adds no parameter-level detail, but schema description coverage is 100%, with each of the five parameters including defaults, ranges, and enum context. The baseline of 3 applies because the schema carries the full burden for parameter understanding.

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

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

The description opens with a precise verb and resource: 'Generate the layout foundation' and enumerates exactly what is produced: breakpoints, container max-widths, edge padding, a column grid, an auto-fit card grid, container queries, and a fluid section-rhythm scale. It also states the output format, CSS custom properties plus a Tailwind v4 @theme block, which clearly distinguishes it from sibling generators like generate_color_system or generate_type_scale.

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

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

The description gives clear usage context by positioning the tool as the layout foundation other generators leave out, and explicitly recommends pairing it with generate_type_scale and generate_design_tokens. It doesn't provide explicit when-not-to-use conditions or compare against all generate_* siblings, but the context is sufficient for an agent to select it correctly.

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=true, idempotentHint=true, and destructiveHint=false. The description goes beyond this by revealing behavioral traits: outputs are 'grounded in the animation-craft rules', 'deterministic', and 'ready-to-paste real code'. This adds meaningful expectations about output style and constraints.

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

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

The description is a single information-dense sentence that front-loads the core action and resource, then enumerates deliverable components, target stacks, constraints, and output properties. Every phrase contributes meaning; the only minor issue is that the long sentence could have been split for readability.

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?

Without an output schema, the description compensates by detailing what is generated (tokens and animations), which stacks are supported, and the craft rules that shape the output. It doesn't explicitly describe the response format or how 'all' values expand, but for a simple two-parameter generator, the essential information is present.

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% with enum descriptions for both parameters, providing a solid baseline. The description adds value by mapping animation names to concrete output types (fade-in, slide-up, scale-in, spring-pop, shimmer) and explaining that easing tokens are delivered as cubic-beziers with specific variants (decelerate/accelerate/standard/spring), which is not present in the schema.

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

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

The description uses a specific verb 'Generate' and clearly identifies the resource: a motion system composed of easing tokens, duration tokens, and ready-to-paste keyframe animations. The enumerated target stacks (CSS, Framer Motion, SwiftUI) and animation names distinguish it from sibling tools like generate_design_tokens or generate_color_system.

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

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

The description provides clear context for when to use this tool: when a motion system, easing/duration tokens, or keyframe animations in supported stacks are needed. It does not explicitly exclude alternatives or name sibling tools, but the purpose is stated concretely enough that an agent can infer appropriate usage.

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 (readOnlyHint, idempotentHint, destructiveHint), so the description's job is to add behavior beyond that. It does: 'Deterministic real output' assures the agent the result is computed and genuine rather than a placeholder or sample, and the fluid clamp() behavior ('scales display type down on small screens') plus the emitted @theme block describe the output's runtime behavior. No contradiction with annotations — generating a scale as output is consistent with read-only, idempotent, non-destructive hints.

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

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

Three dense, front-loaded sentences with zero filler: purpose and output contents first, then output format, then the behavioral guarantee and companion tools. Every sentence earns its place and the most decision-relevant information (what the tool generates) appears immediately.

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

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

There is no output schema, so the description carries the burden of explaining return values — and it does, covering the named steps, sizes, line-heights, letter-spacing, CSS custom properties, and Tailwind @theme block. All 4 parameters are optional and fully documented in the schema, and the annotations disclose safety and idempotency. The only minor gap is that it doesn't explicitly state the output is returned as text/CSS for the agent to consume rather than written to files, but readOnlyHint largely covers that.

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 with the schema doing the heavy lifting. The description adds marginal connective meaning — 'from a base size and ratio' maps to the base and ratio params, 'optional fluid clamp()' maps to the fluid boolean, and 'named steps (xs…6xl)' clarifies the steps param — but these largely restate what the schema already documents in adequate detail. No critical param semantics are added beyond the schema.

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

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

The description names a specific verb and resource ('Generate a modular typographic scale from a base size and ratio') and enumerates the exact deliverables: named steps (xs…6xl), sizes, line-heights, letter-spacing, and optional fluid clamp(). It distinguishes itself from siblings like generate_color_system and generate_design_tokens by specifying its precise output surface (CSS custom properties and a Tailwind v4 @theme block), leaving no ambiguity about what this tool produces.

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

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

The closing line, 'Pair with suggest_font_pairing and generate_design_tokens,' gives concrete workflow context that positions this tool within a broader design-token pipeline. It implies when to use it (typography scale generation) via the focused subject matter, but it does not explicitly state when not to use it or which sibling (e.g., generate_design_tokens) would be the better choice for broader token needs. Clear context, no exclusions.

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 establish read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral detail about the output: it 'Returns the most relevant docs in full' and specifies the content categories such as specs, states, sizing, anti-patterns, and real-world patterns.

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

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

The description is front-loaded with the core purpose, then provides outcome details and routing guidance in a compact three-sentence structure. Every sentence contributes distinct information without 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?

There is no output schema, but the description compensates by explicitly describing what will be returned: full relevant docs covering specs, states, sizing, anti-patterns, and real-world patterns. It also covers when to use the tool and how to choose between its closest siblings.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description reinforces the component parameter with examples but does not add material meaning beyond the schema, especially for the platform parameter.

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

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

The description opens with a specific verb and resource: 'Get expert guidance for designing one UI component or screen pattern' and gives concrete examples. It also explicitly distinguishes itself from sibling tools by naming get_component_recipe and get_design_examples.

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

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

The description clearly states when to use this tool: 'Use when designing a specific element.' It also gives direct alternative tool guidance: 'for copy-paste code use get_component_recipe, for annotated screenshots use get_design_examples.'

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, so the safety profile is covered. The description adds valuable behavioral context: the output is production-ready code with all states, ARIA/accessibility, keyboard support, motion, and stack-specific variants. It does not detail edge cases or return structure, but this is a read-only lookup tool.

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

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

Three sentences with no filler: the first states the core value, the second gives concrete use cases, and the third points to related tools. The component list is long but directly informs when the tool applies.

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

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

With no output schema, the description compensates by describing what the code includes: states, accessibility, keyboard support, and motion. The optional stack behavior and scales/tokens semantics are already covered in the schema. Missing error/edge-case behavior is a minor gap.

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 schema already explains component, stack, scales, and tokens in detail. The description mainly reinforces that the stack is a choice and lists example components, adding little beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Get production-ready, accessible reference CODE for a UI component.' It clearly differentiates from the sibling get_component_guidance by stating this is 'not advice' but actual copy-paste code, and by naming which components it supports.

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

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

It explicitly says 'Use when you need to actually build' a component, which gives clear situational guidance. It also names companion tools get_component_guidance and generate_design_tokens, but does not explicitly state when not to use this tool versus each sibling.

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 non-destructive behavior, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it specifies the full return contents (title, metadata, prescriptive body, cited sources) and the unknown-id fallback behavior of suggesting near matches.

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

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

The description is compact, front-loaded with the core purpose, and every sentence adds useful information. There is no filler or repetition of the tool name.

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

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

Given one required parameter, full schema documentation, and annotations covering safety, the description is complete. It covers what is returned and how unknown ids are handled, so 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%, with the schema already explaining the id type, examples, and where to get ids. The description only reinforces 'by its id' and repeats the id-source guidance, adding minimal meaning beyond the schema.

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

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

The description uses a specific verb ('Fetch') with a clear resource ('one knowledge-base document in full by its id'). It also distinguishes this tool from list/search siblings by positioning them as id sources and this tool as the retrieval action.

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

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

The description explicitly tells the agent where valid ids come from (list_design_knowledge or search_design_knowledge), which is actionable usage guidance. It does not explicitly state when not to use it, but the single-document fetch purpose is clear enough to route correctly.

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 flag read-only/idempotent behavior, and the description adds significant value by disclosing that screenshot images are NOT bundled and links must be opened externally. This is a non-obvious behavioral trait that prevents false expectations about inline images.

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

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

Two sentences with zero filler; the core purpose is front-loaded and the critical image caveat is clearly separated in a NOTE. Every sentence earns its place.

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

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

For a simple read-only tool, the description covers the return shape (app/site, what works well, source link) and the key limitation (no embedded images). With no output schema, this is sufficient for an agent to call it correctly, though it could mention default behavior or empty-result handling.

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 does not add much beyond the schema for parameters; it mainly lists example query values, which is helpful but not essential since query examples already appear in the schema.

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

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

The description states a specific action ('Fetch curated real-world examples of a design pattern') and a clear resource (examples from top apps/sites), with a helpful list of pattern areas. It is distinct from sibling tools like list_design_knowledge or search_design_knowledge, though it does not explicitly name them as alternatives.

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?

Usage context is implicit: an agent would call this when a user wants real-world examples of a pattern. However, it does not explicitly explain when to prefer this over related knowledge/design tools, nor state any exclusions or alternatives.

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 establish readOnlyHint, idempotentHint, and non-destructive behavior, so the description's additional job is to explain what happens when invoked. It does so by stating that the tool returns 'the complete spec' with rules, do/don't lists, numbers, and examples. This adds useful behavioral context beyond the annotations, though it does not disclose error or edge-case behavior.

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

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

Three sentences with no filler: purpose, return content, and usage alternatives are each front-loaded and directly useful. Every sentence earns its place, and the description is appropriately sized for the tool's simplicity.

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

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

For a single-parameter, enum-constrained read-only tool, the description is complete: it states what is fetched, what the returned spec contains, and when to use it versus relevant siblings. No output schema is present, but the description adequately explains the return value's content. There is no significant missing context for correct tool selection and invocation.

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

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

Schema coverage is 100%, and the sole parameter 'language' already has a descriptive enum with concrete examples. The description lists many of the same enum values and calls the parameter a 'design language or platform design system,' but it adds little beyond the schema. Baseline 3 is appropriate because the schema carries the semantic weight.

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

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

The description opens with a specific verb and resource: 'Fetch the full reference document for one modern design language or platform design system,' and then enumerates the exact systems covered. It clearly says what is returned (rules, do/don't lists, numbers, examples), distinguishing this tool from generic search or component-level 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?

Explicit guidance is provided: use when you need the authoritative platform baseline before designing. It also names two direct alternatives with their conditions: get_component_guidance for a specific component and get_design_roadmap for whole-project planning. This leaves little ambiguity about when to choose this tool.

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 the tool as read-only, idempotent, and non-destructive, so no contradiction exists. The description adds useful behavioral context by explaining that the roadmap is structured by phases, each with goals and associated docs, and that it is the intended entry point for design work.

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

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

The description is two focused sentences with no filler. It front-loads what the roadmap is, then gives actionable usage guidance, making it efficient and easy for an agent to parse.

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

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

The tool is simple with one parameter and no output schema, and the description explains the contents of the roadmap and what the agent should do next. It doesn't describe the exact output format, but that omission is acceptable given the roadmap's clear purpose and the follow-up instruction to fetch phase docs.

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 sole parameter, project_type, already has an enum and a description. The description restates the project types, which adds minimal new semantic value beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as returning a phased, expert design roadmap for a specified project type. It names the exact project types and explains that each phase contains goals and knowledge-base docs, which distinguishes it from sibling tools like get_design_doc or audit tools.

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

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

The description explicitly says 'Use this FIRST when starting any design project' and instructs the agent to 'fetch phase docs as you reach them.' This gives clear timing guidance, though it does not explicitly name or exclude alternative tools.

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 the tool as read-only, idempotent, and non-destructive, and the description adds meaningful behavioral context beyond those: only NAMED tokens are imported, bare hex values are ignored, and JavaScript configs are never evaluated. It also discloses the output contents — named roles, missing semantic roles, WCAG contrast check, and re-emitted artifacts — so an agent understands what will happen when invoked.

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

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

The description is compact but information-dense; every sentence earns its place. It front-loads the core action and outputs, then covers use cases, exclusions, and limitations without tangents. The semicolon-separated list of input formats keeps the structure readable despite covering many formats.

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?

Even with no output schema, the description explains what the tool returns: named roles, missing semantic roles, WCAG contrast checks, and re-emitted code in multiple formats. It also covers accepted input formats, automatic detection, unsupported inputs, and alternative tools. For a tool of this complexity, nothing essential 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 extra meaning by explaining that the source format is detected automatically, clarifying that 'swiftui' or 'compose' is how to take a web theme to native, and framing what kinds of sources are acceptable. This enriches the schema definitions without merely repeating them.

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

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

The description opens with a specific verb and resource: 'Read an EXISTING design system and convert it,' then enumerates accepted input formats and outputs. It further differentiates itself from siblings by calling itself the inverse of generate_design_tokens and distinguishing its scope from audit_design_system, so an agent can tell exactly what this tool does.

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

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

Usage guidance is explicit: use it to port a web theme to iOS/Android, audit an inherited system, or discover undefined roles in a third-party theme. It also names alternatives for adjacent cases, e.g., bare hex values should go to audit_design_system, and states that JavaScript configs are never evaluated. This is strong when-to-use versus when-not-to-use 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?

The description aligns with annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) and adds useful context: it reports on freshness across documents, uses category-specific thresholds, and implicitly performs no mutation. The pointer to the refresh workflow further clarifies the boundary between reporting and acting.

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

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

Two tight sentences deliver the core function and the decision context without filler. The freshness metric is front-loaded, and the workflow pointer is a valuable addition that does not bloat the description.

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

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

For a simple read-only reporting tool with one optional boolean and no output schema, the description adequately conveys what output is expected (a freshness report per document) and how the result should be used. Annotations cover the safety profile, and the refresh workflow pointer addresses the natural follow-up action.

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 only only_stale boolean parameter, so the schema fully documents its meaning and default. The description does not add parameter-level detail, but the baseline of 3 is appropriate given the high schema coverage.

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

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

The description uses a specific verb ('Report') and a well-defined resource ('knowledge documents') with a precise metric: age since last verification compared to each category's staleness threshold. It is clearly distinct from sibling tools, which all focus on design knowledge retrieval or audits rather than freshness reporting.

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

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

The description explicitly states the tool's intended use ('decide which docs need re-research') and directs the agent to the refresh workflow via /refresh-knowledge. It does not explicitly name alternatives or exclusion conditions, but no sibling tool appears to offer freshness reporting, making the context clear enough.

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, so the safety profile is covered. The description adds behavioral context by stating that results are grouped by category and include id, title, platform, and tags, which is valuable beyond annotations.

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

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

The description is two sentences, front-loads the core purpose, and avoids redundancy with the schema. Every clause adds useful information: scope, return composition, and workflow guidance.

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, but the description compensates by naming the exact fields returned (id, title, platform, tags) and the grouping behavior. Filters are fully documented in the input schema, and annotations cover the operational constraints, making this complete for a list/discovery tool.

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

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

Schema description coverage is 100%, and both category and platform already have clear descriptions and enums. The tool description does not add much parameter-level meaning beyond the schema, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'List the knowledge-base index' and enumerates the content domains. It clearly distinguishes itself from siblings by explaining this is the discovery entry point, while read is get_design_doc and search is search_design_knowledge.

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

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

Explicit usage guidance is given: 'Use this first to discover what's available and get exact ids; then read one with get_design_doc, or search by need with search_design_knowledge.' This tells an agent exactly when to call this tool versus its closest alternatives.

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 supply readOnlyHint=true, idempotentHint=true and destructiveHint=false; the description complements these by disclosing operational behavior: 'Reads the local file you name; makes no network call' (scope/privacy), 'PNG only' (input restriction), and the markdown/HTML output modes. The description is fully consistent with the annotations — no contradiction.

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

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

Four sentences, each earning its place: measurement capabilities, output formats, constraints/privacy, then workflow routing. The most decision-relevant information (what it measures, PNG-only, no network) is front-loaded, with zero tautology 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?

For a complex tool with no output schema, the description covers the essentials: measured dimensions (with confidence levels), returned artifacts (markdown, optional HTML), input constraints (PNG, local path), and workflow placement ('before critiquing a UI'). The return format is described narratively rather than structurally, and failure behavior for invalid paths is left unspecified — minor gaps given the strong schema coverage.

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 each parameter is already richly documented — path (absolute paths preferred, working-directory caveat), scale (Retina/2× pixel-ratio logic), format (markdown/html/both semantics), max_colors (cluster count, default 12). The description narratively reinforces the format behavior ('on request, a self-contained HTML report') but adds no genuinely new parameter meaning beyond the schema, 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?

Opens with a specific verb and resource — 'Measure a real screenshot from its actual pixels' — and enumerates the exact outputs: palette, distinct colour count, WCAG contrast ratios, whitespace/density, and structural detections with confidence levels. No sibling tool measures screenshots; fix_contrast and audit_design_system are explicitly positioned as companions, not competitors, so the definition fully disambiguates the tool.

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 states when to invoke it: 'Use it before critiquing a UI so the review cites measured numbers instead of impressions.' It also routes to the right companion tools — fix_contrast for failing pairs and audit_design_system for the codebase behind the screen — and states hard constraints (PNG only, local file, no network call) that shape when it applies.

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 establish read-only, idempotent, and non-destructive behavior. The description adds useful behavioral detail beyond annotations: it searches the entire knowledge base, returns top-matching documents, and includes the single most relevant section excerpt plus document id. This is meaningful context without contradicting the annotations.

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

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

The description is front-loaded with the core action and resource, then covers what is returned and when to use it. The enumeration of knowledge domains is long but informative for an agent deciding whether this tool matches the task; it earns its place even if it 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?

For a search tool with 4 well-documented parameters and no output schema, the description provides the essential return shape (documents with excerpt and id) and usage context. It distinguishes the tool from the most relevant siblings, which is important given the large sibling list.

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 reinforces that query should be a natural-language phrase and gives examples of open-ended questions, but it does not need to add much because the schema already documents limit, category, and platform clearly.

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

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

The description opens with a specific verb and resource: 'Search the whole knowledge base with a natural-language query' and enumerates the covered domains. It clearly differentiates from siblings by stating it returns top-matching documents with an excerpt and id, as opposed to fetching a known doc or listing everything.

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

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

It explicitly states the intended use case ('open-ended how should I… questions') and names alternatives: use get_design_doc when the id is already known, and list_design_knowledge to browse everything. This gives the agent actionable 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the tool returns documentation and can be narrowed by topic, but it does not disclose any additional behavioral details such as output formatting, size limits, or whether external data is fetched.

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

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

The description is compact and organized: domain definition, return behavior, and usage guidance. The first sentence is somewhat long but contains useful disambiguation between SEO and GEO. Every sentence contributes, though the lead could be more action-forward.

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

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

For a read-only reference tool with a required enum and one optional topic parameter, the description covers what the tool returns, when to use it, and how to combine it with a related tool. It does not explain what 'full relevant guide docs' looks like in practice, but with no output schema and low complexity, the gap is minor.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description reinforces the optional narrowing behavior for topic and gives domain examples, but it does not add substantial meaning beyond the schema.

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

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

The description opens by naming the resource ('SEO and GEO expertise for websites') and specifies the verb/resource relationship: it returns full relevant guide docs, optionally narrowed by topic. This clearly distinguishes it from audit-style siblings like audit_seo_geo and design guidance tools by framing itself as a reference/knowledge retrieval tool.

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 usage context: 'Use when planning or auditing a site's discoverability' and even suggests pairing with get_design_roadmap('website') for the full process. It does not explicitly list exclusions or alternative tools, so it stops short of full when-not 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?

Annotations already establish the read-only, idempotent, non-destructive profile. The description adds valuable behavioral context beyond annotations: deterministic curated recommendations rather than generic advice, and what the full result contains including CSS stacks, weights, source, reasoning, pairing rules, and type scale. No contradiction with annotations.

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

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

The description is front-loaded with the core action, then details return value components, then adds the deterministic behavior note and a sibling integration tip. Every sentence earns its place with no filler or redundant restating of the title.

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

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

With no output schema, the description sufficiently enumerates what will be returned so an agent knows what to expect. It covers the input signal, output artifacts, behavioral guarantees, and the natural follow-on tool, making the definition self-sufficient.

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%, with both intent and limit already documented, so the schema carries most of the parameter meaning. The description reinforces the intent-as-vibe concept with examples but adds little new parameter-level detail.

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 and resource: 'Recommend production-ready font pairings' from an intent/vibe, with concrete examples. The detailed output composition (heading + body + mono CSS stacks) makes it clearly distinct from related siblings like generate_type_scale or generate_design_tokens.

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 clear context for when to call it: when the user describes a brand/product vibe and wants production font pairings. It also names a complementary next step (generate_design_tokens), though it does not explicitly state when not to use the tool or which alternatives to prefer.

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?

Adds meaningful context beyond the annotations: 'Deterministic curated guidance' and the critical caveat 'icons are NOT bundled; install the chosen library in your own project'. The return-content list (license, install command, coverage) also clarifies what the agent can expect. Annotations already cover read-only/idempotent/non-destructive, so the description's additions are the right kind of value.

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

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

Four sentences, front-loaded with purpose, then return shape, then the key behavioral caveat, then composition guidance. Each sentence earns its place, though 'universal icon best-practices' is slightly verbose phrasing.

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

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

With no output schema, the description compensates by enumerating return fields (license, install command, coverage, fit rationale, usage rules, best-practices). Combined with annotations covering the safety profile and a simple 2-param schema, almost everything an agent needs is present. Minor gaps: no mention of result ordering or no-match behavior.

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

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

Schema coverage is 100% and both parameters have rich descriptions already. The tool description's intent examples ('minimal SaaS dashboard', 'iOS app') overlap heavily with the schema's own examples, so it adds little beyond it. Baseline 3 is appropriate.

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

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

States a specific verb ('Recommend'), resource ('icon library'), and the input framing ('from an intent/vibe/platform') with concrete examples. The icon-specific focus clearly differentiates it from siblings like suggest_font_pairing and generate_color_system.

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

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

Provides clear context via 'Pair with suggest_font_pairing and generate_color_system', explicitly naming the natural companion tools for a design-system flow. It lacks explicit when-not-to-use exclusions, but the intent/vibe input framing effectively implies the triggering scenario.

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