CSS Crème

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses that data is 'read from the open web-features dataset at build time,' implying a potential staleness caveat. It also transparently describes the exact return contents: baseline status, date, lacking browsers, site counts, @supports details, and fallback notes. This is rich behavioral context that complements the annotations without 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?

The description is long but well-structured: it front-loads the two questions, then details the second question, then provides usage guidance with examples, and ends with the no-argument behavior. Each sentence serves a purpose—explaining scope, outputs, and use case. It is not overly terse, but the level of detail is warranted given the tool's complexity.

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

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

There is no output schema, so the description must convey what the tool returns. It does so comprehensively: baseline status, date, lacking browsers, number of sites, which ones, @supports usage, exact conditions, and fallback notes. It also covers the Ship Gap scenario. While it doesn't specify a JSON structure or pagination, the output is well-scoped and sufficient for an agent to understand the result.

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

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

The input schema already describes the parameter with examples and explicitly notes the omission behavior ('Omit for the whole Ship Gap summary'). The description adds usage context (before writing CSS) but does not materially expand on the parameter's format or semantics beyond what the schema provides. With 100% schema coverage, the description's additional value is marginal.

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 it answers two specific questions about a CSS feature: Baseline status and adoption across curated sites, with concrete examples of features it covers. It distinguishes itself from siblings by focusing on CSS feature support data rather than site decoding or theme retrieval. The verb 'answers' plus resource 'modern CSS feature' makes the purpose unambiguous and specific.

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 when to call it: 'Call it before writing CSS that uses container queries, :has(), ...' This provides a clear usage trigger. It also explains the alternative behavior when no feature is given (returns Ship Gap). However, it does not explicitly mention when not to use it, though no sibling tool competes directly, so the guidance is adequate.

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?

Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds substantial behavioral detail: it reads from sitemap.xml or falls back to homepage links, reports counts and the pages actually read, and explicitly states it never returns a score. This goes well beyond annotation metadata.

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

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

The description is compact and front-loaded: it opens with the core operation and output, then gives a brief rationale, return-value semantics, and a clear usage trigger. Every sentence earns its place; there is no filler or repetition of schema details.

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

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

For a two-parameter tool with no output schema, the description fully equips an agent to select and invoke it: it explains how pages are discovered, what counts as consistency, what is returned, and when to prefer this tool. No critical operational context is missing.

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

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

Schema description coverage is 100%, so the schema already documents the url and pages parameters completely. The description reinforces that pages are a sample and ties url to site-wide discovery, but does not add new parameter-level meaning beyond what the schema provides.

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

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

The description states a specific, observable behavior: read a sampled set of pages from a single site and report which design tokens, colors, fonts, radii, and spacing values are consistent across them. It explicitly contrasts this with single-page analysis ('One page shows what a page uses'), clearly distinguishing it from decode_url and other 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 provides an explicit when-to-use statement: 'Use when the user asks whether a site is really on a system, or wants the system rather than one page of it.' It implies when not to use it (single-page questions) but does not name decode_url or other alternatives explicitly, so it stops just 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?

Beyond the readOnly/idempotent annotations, the description discloses that it reads CSS without rendering, reports confidence levels ('tokens' vs 'derived'), and flags JavaScript shells. This sets accurate expectations about limitations and output 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 mechanism, then contextual details. It is a bit long and includes explanatory color like the markdown rationale, but every sentence carries useful information; only minor trimming would improve it.

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

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

With no output schema, the description fully explains the return values: list of CSS-derived design data, the drop report, confidence indicators, and the JavaScript-shell flag. Together with the schema-described format enum, an agent has sufficient context for correct invocation.

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

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

The input schema already provides 100% coverage of all parameters, including detailed descriptions for url, expect, and the format enum. The description adds no extra parameter-level meaning, so the baseline score 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 names a specific verb and resource: it fetches a public site's HTML and stylesheets and returns its CSS-declared design tokens, colors, fonts, radii, spacing, and framework. The distinctive 'drop' report and confidence levels separate it from typical theme tools, though it never explicitly differentiates itself from siblings like decode_site or get_theme_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?

Explicit 'Use when' guidance is provided for two concrete cases: matching a site not in the catalogue, and needing back the design layer lost in markdown. It stops short of naming alternatives or saying when not to use it, so it lacks full exclusionary routing.

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; the description adds useful output behavior by noting that the block points at DESIGN.md rather than restating it and includes a token fingerprint for drift detection. There is no contradiction with 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?

Three compact sentences deliver the purpose, usage, and unique output traits with no filler. The most important information about what the tool returns is front-loaded, and 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 single-parameter, read-only tool with no output schema, the description covers the return value's purpose, content strategy, and installation targets. The id meaning is covered by the schema, and sibling tools provide discovery context for valid themes or templates.

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 id parameter has 100% schema description coverage, so the baseline is 3. The description does not add additional meaning about valid id values or how the id affects the generated rules block, leaving the schema's 'Theme or template id' as the only guidance.

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 ('Return') and names the exact resource: a short standing-instructions block for agent config files. It also states the block's function (forcing DESIGN.md reads before UI changes) and its drift-detection trait, making it distinguishable from siblings like get_design_md or verify_design_md.

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

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

The description gives explicit placement guidance ('Paste it whole into CLAUDE.md, AGENTS.md or .cursor/rules/design.mdc') and frames the intended context for use. It does not enumerate when to prefer this over get_design_md or verify_design_md, so it stops short of a 5.

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 adds the practical behavior of saving the fetched content to the repo root, and clarifies the fetched artifact is a full DESIGN.md. No contradictions.

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, front-loaded with the core action, then the content inventory and a direct usage directive. 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 one-parameter, read-only fetch tool, the description is complete: it states what is returned, what to do with it, and when to call it. No output schema is required because the content is described in prose.

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 sole parameter `id` is fully documented in the schema (coverage 100%) with an example and source for valid IDs. The description only reinforces that the tool is per-theme, without adding new parameter semantics, so baseline 3 applies.

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

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

Statement 'Fetch the full DESIGN.md for one theme' names a specific action and resource, and the content list (semantic colors, shadcn tokens, typography, contrast ratios, rules) distinguishes it from sibling tools like get_theme_tokens and get_design_md_for_url, which serve different retrieval scopes.

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 call to action: 'Read this before writing any UI,' and explains the persistence step ('Save it at the repo root as DESIGN.md so it applies to every session'). It does not explicitly name alternatives or when not to use it, so it stops short of full alternative routing.

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 reveals a critical limitation: it 'reads declared CSS and does not execute JavaScript' and reports 'what the stylesheets say rather than what the page renders.' This is valuable behavioral context that prevents false expectations and does not contradict 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 main verb and resource, and every sentence earns its place. The first sentence, however, packs a large 15-item output enumeration into one long clause, making it less scannable than a structured bulleted list would 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?

For a one-parameter tool without an output schema, the description covers invocation, output scope, and the no-JavaScript caveat quite well. It does not explicitly state the exact return representation (e.g., Markdown text versus saved file) or behavior for inaccessible or CSS-less pages, so it is strong but not fully exhaustive.

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 the only parameter with 100% coverage ('Absolute public http(s) URL of the page to read'). The description adds contextual emphasis that the target is a public site and that stylesheets are read, but it does not add new 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 opens with a specific action and resource: 'Read the stylesheets of a public site and return a full DESIGN.md', and enumerates a detailed output list, so its purpose is unmistakable. However, it never references sibling tools like get_design_md or get_theme_tokens, so differentiation from close alternatives is implicit rather than explicit.

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

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

It gives a clear use context: 'This is the artefact to hand a coding agent before it writes UI that should match a site.' It does not mention when not to use it or point to alternatives such as get_design_md, so it lacks explicit exclusions and 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, covering the safety profile. The description adds that the tool also reads a registry URL, which is extra behavioral context beyond the annotations, and it does not contradict them.

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 waste: the first states exactly what is returned, the second gives the usage condition. The core function is front-loaded, and 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 simple tool with one parameter and no output schema, the description covers what it returns (command + registry URL) and when to use it. It does not discuss error cases or format details, but given the tool's simplicity and annotation coverage, this is adequate.

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% (the `id` parameter is described as 'Theme or template id.'). The description adds no further semantic detail about the parameter beyond repeating that the id must be known, so it stays at the baseline for full 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 states a specific verb ('Return') and resource (the `npx shadcn@latest add <url>` install command) and even gives the exact command format. It clearly distinguishes itself from siblings like `list_themes` or `get_theme_tokens` by focusing solely on producing the install command.

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

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

It provides an explicit trigger condition: 'Use when the user says "install it" and you already know the id.' This is clear context but does not mention alternatives or when not to use it, so it stops short of a 5.

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, and the description adds real contextual value by detailing the output contents (OKLCH tokens, light/dark, paste-ready CSS, install command). It does not contradict the annotations and requires no additional side-effect warnings.

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, front-loaded with what the tool returns and ending with when to use it. There is no filler or repetition 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?

For a read-only tool with a simple schema, the description sufficiently explains the returned artifacts despite no output schema. The only gap is not disambiguating its included install command from the sibling get_install_command.

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 applies; id and format are already documented, including enum and default. The description reinforces that results are for a single theme but does not add param-level details 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 ('get') and names the exact resource: shadcn/ui registry item, OKLCH tokens light/dark, CSS variables, and install command for one theme. It disambiguates from list/search siblings by emphasizing 'one theme' and from get_design_md by indicating it is the follow-up token-writing step.

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 to use after get_design_md and precisely when ('when you are ready to write the tokens into globals.css'). It does not, however, contrast with get_install_command or state when not to use 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about the specific agents and the benefit of session-wide persistence, but does not add new behavioral details beyond confirming it is an explanation. This is consistent with annotations and adds modest 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?

A single sentence, front-loaded with the verb 'Explains' and the object. Every phrase earns its place: the agent list and the session-vs-message contrast are directly useful. No filler or redundancy.

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

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

For a simple instructional tool with one parameter, no output schema, and annotations that already convey idempotency and read-only behavior, the description is fully adequate. An agent can understand what it does, who it applies to, and why it matters without needing more information.

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 doc for the 'tool' parameter is complete (100% coverage) and already enlists the five possible values. The description repeats that same list without adding further detail on syntax, defaults, or usage, so it does not go beyond the schema. Per the rubric, 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 uses the verb 'Explains' and names the exact resource ('where a DESIGN.md belongs for a given coding agent'), with a specific list of agents (Claude Code, Cursor, v0, Codex, Lovable). It clearly differentiates itself from sibling tools like get_design_md or get_agent_rules by focusing on placement/installation rather than retrieval.

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 communicates its purpose and scope (which agents it covers and the outcome of applying design rules across sessions), which gives strong context for when to use it. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5 but is 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds that this is a browsing/catalogue operation, but it does not explain important behaviors like the fact that results can be filtered by kind or mode, or what the returned catalogue contains. It does not contradict 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 two sentences with no filler. The action is front-loaded ('Browse the full catalogue'), followed by a crisp usage condition. 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 list tool with optional parameters and no required fields, the description covers the core intent. However, it does not explain how the parameters affect results, that both are optional, or what the output looks like. Given the absence of an output schema and parameter descriptions, this is an adequate but incomplete definition.

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 0% and the description does not mention the parameters at all. The enum values like 'theme', 'template', 'light', and 'dark' give some self-evident meaning, but the description should clarify that kind and mode are optional filters. The description fails to compensate for the lack of parameter documentation.

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

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

The description clearly states the resource and action: 'Browse the full catalogue of curated themes and templates.' It distinguishes itself from searching by saying it is for when the user wants to 'see options rather than search for one.' The title and description align well enough with the tool's purpose.

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

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

The description provides a clear usage context: 'Use when the user wants to see options rather than search for one.' This implies the alternative of searching, but does not explicitly name search_themes or provide any when-not-to-use guidance. It is clear but lacks an explicit alternative reference.

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 agent knows this is a safe, non-mutating operation. The description adds value by specifying the return payload (matching themes with DESIGN.md URL and install command), which is not implied by the annotations. This covers what an agent needs to know about behavior 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?

Two sentences with no filler. The first sentence establishes purpose and gives examples; the second explains the return value and the optimal usage scenario. Every clause earns its place, and the key information is front-loaded.

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 search tool with one required parameter and full schema coverage, the description covers all essentials: what it does, how to phrase the query, what it returns, and when to use it. The output schema is absent, but the description states the return format sufficiently. No critical information is missing for an agent 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 description coverage is 100%, so the schema already documents all four parameters (query, kind, mode, limit) with meanings and defaults. The description adds concrete examples ('dark developer tool', 'calm fintech dashboard') that illustrate how to phrase the query, which goes beyond the schema's 'Free text: mood, industry, colour, or use case.' This added context helps the agent construct effective queries.

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 ('Find') and resource ('design system') and clarifies how to use it ('by describing what you are building'). It also mentions what it returns (matching themes with DESIGN.md URL and shadcn install command), which distinguishes it from siblings like list_themes and get_design_md. The phrase 'Call this first' implies a distinct role among the 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 states when to use this tool: 'Call this first when the user has no design system defined.' This gives a clear condition and implies when not to use it (when a design system is already defined). It doesn't name a specific alternative tool, but the sibling list includes list_themes, which would be the natural fallback, so the guidance is sufficient though not exhaustive.

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 disclose readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it explains that if the fingerprint does not match, the server returns the current tokens so the agent can update the file, and it clarifies the matching mechanism. 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 three sentences, each earning its place: it explains the fingerprint mechanism, states what the server returns, and gives the usage trigger. Information is front-loaded and there is no fluff or repetition.

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

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

For a simple verification tool with two well-documented parameters, no output schema, and supportive annotations, the description is complete. It explains the input source, the behavior (match/stale), the return value (current tokens when stale), and the recommended usage time. An agent has everything needed to invoke the tool correctly.

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

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

Schema description coverage is 100%, with both parameters well-documented (id from Source line, fingerprint from Fingerprint line with example). The description reinforces the parameter roles but does not add meaning beyond what the schema already provides. According to calibration, baseline 3 is appropriate when the schema carries the semantic load.

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

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

The description clearly states the tool's purpose: to verify whether a DESIGN.md copy is current by checking its fingerprint against the server's current token set. It uses a specific verb ('verify') and resource ('DESIGN.md copy'), and it is easily distinguishable from siblings like get_design_md (which likely fetches) and get_theme_tokens (which retrieves tokens directly).

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 an explicit trigger condition: 'Call this at the start of a session when a DESIGN.md is already in the repo.' This gives clear context for when to use the tool, though it does not explicitly name alternative tools or state when not to use it. The guidance is adequate for correct selection.

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