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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds meaningful behavioral context: it is a validation gate over declared contrast promises, and undeclared pairings are not guaranteed. It stops short of describing the exact output/report format, but the build-gate framing makes the pass/fail nature clear.

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 tight sentences with no filler. The core action is front-loaded, followed by when to use it, then the important contract warning. 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?

With optional parameters, full schema coverage, and read-only annotations, the definition covers the essential operational context. An explicit description of what the tool returns on success/failure is missing, but 'build gate' and 'failuresOnly' make the expected behavior reasonably inferable.

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 fully documented. The description reinforces the 'one theme or all four' scope but adds no new parameter-level detail, matching the baseline for schema-covered parameters.

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: it runs every contrast promise in the design system against one theme or all four. This clearly differentiates audit_theme from a single-pairing check like check_contrast, leaving no doubt about scope.

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

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

The tool is explicitly positioned as 'the build gate' with a directive to run it after any palette change, giving clear usage context. It does not explicitly name alternatives or when not to use it, but the intended workflow is well communicated.

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 annotation, the description adds meaningful behavioral details: it resolves token names for the chosen theme and composites translucent values over the page. This helps the agent understand how inputs are processed and that token resolution is theme-dependent. It does not contradict the 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 two sentences with no redundant content. It front-loads the core output (contrast ratio and verdict) and then provides the key input behavior (hex/token acceptance, theme resolution, compositing). 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 low-complexity, read-only calculation tool, the description covers the main inputs, behavior, and result format. The lack of an output schema is mitigated by the explicit mention of 'contrast ratio and pass/fail verdict.' Some details like error handling for invalid hex/tokens could be added, but they are not critical 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 schema already provides 100% coverage with descriptions for all parameters, so the baseline is 3. The description adds value by explaining the token-resolution behavior for foreground and background, including compositing translucent values, which is not fully captured in individual parameter descriptions. It also clarifies the role of the 'use' parameter indirectly by mentioning the pass/fail verdict driven by thresholds, though that is already 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 clearly states the verb (check) and resource (a foreground/background pair), specifying exactly what it does: computes the WCAG 2.2 contrast ratio and a pass/fail verdict. It also distinguishes itself from the sibling tools, none of which offer this contrast-checking functionality directly. The mention of accepting hex values and Sekura token names further clarifies scope.

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

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

The description implies its use case — checking contrast for a colour pair — but does not explicitly state when to use it versus alternatives like audit_theme or validate_integration. It provides no exclusions or when-not-to-use guidance. The usage context is inferable from the tool's purpose, but not explicitly articulated.

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 provide readOnlyHint=true and openWorldHint=false, and the description does not contradict them. It adds useful behavioral context: all outputs are generated from one source, so primitive changes propagate to every format. This goes beyond the annotations, though it does not describe response mechanics or edge cases.

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 first sentence states the action and scope, and the second explains a meaningful generation guarantee. 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?

The schema covers both parameters and the read-only annotation is present, so most calling context is complete. The description communicates the core behavior and output purpose, but because there is no output schema, an explicit statement of what the tool returns would make it fully complete.

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

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

Schema description coverage is 100%, and the schema already thoroughly explains each format enum value and the theme restriction for json. The description itself adds no parameter-level meaning, 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 uses a specific verb, 'Emit', and a clear resource, 'the full token set', and the title adds 'in a build format'. It is distinct enough from siblings like get_tokens or get_primitives because it emphasizes producing full-token build artifacts, though it does not explicitly name a sibling for contrast.

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 does not state when to use export_tokens versus alternatives such as get_tokens or get_primitives. It implies 'use this to emit the full token set', but gives no exclusions, prerequisites, or guidance about which tool to prefer for inspection versus build output.

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 openWorldHint=false, so safety is covered. The description adds useful scope detail (what is included, and that omitting id returns the full catalogue), but says nothing about result size, pagination, or cost of the unfiltered call, which is the main behavioral risk here.

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, no filler, with the content scope and the filter behavior front-loaded. The trailing inventory of included artifacts is slightly list-like but each item is informative.

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?

An output schema exists, so return-value explanation is unnecessary, and the read-only annotations cover the safety profile. For a single optional filter parameter, the description covers scope, filtering, and the unfiltered default — nothing needed to call it correctly is missing.

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

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

Schema description coverage is 0% for the single id parameter, so the description must carry the load — and it does, explaining that id accepts a component id or an exported API name and that omitting it returns everything. It stops short of format examples or accepted value shapes.

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: retrieves the runtime behavior and lifecycle contract surface, with a concrete content list (TypeScript declarations, selectors, initialization, cleanup, events, responsibilities). It is clear about what it returns, though it does not explicitly distinguish itself from near-siblings such as get_component or get_component_code.

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?

"Filter by component id or exported API name; omit id for the full catalogue" tells the agent how to scope the call but not when this tool is the right choice versus get_component, get_component_code, or get_layout. Usage is implied by the content list rather than stated.

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 openWorldHint=false, so the safety profile is covered by structured data. The description adds useful scope information (a single call is comprehensive across anatomy, a11y, tokens, content rules), telling the agent it need not chain other tools, but it discloses nothing about response shape or pagination.

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 one-line purpose before an inventory of covered domains. The enumeration is long but each item signals real returned content; nothing is padded with filler or marketing language.

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 a readOnly annotation set and an output schema present, the description need not explain return values or safety, and it correctly focuses on what a single call covers. The remaining gap is sibling routing among the many get_* tools, which an agent would have to resolve on its own.

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

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

There is a single required 'id' parameter with 100% schema description coverage, including examples ('button', 'table', 'combobox'). The description adds no additional meaning about the id format or lookup behaviour, so the baseline of 3 for schema-carried semantics 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 ('The complete spec for one component') and enumerates the domains covered (anatomy, variants, accessibility, tokens), so its scope is unambiguous. It falls short of a 5 because it never distinguishes itself from near-neighbours like get_component_code, get_pattern, or get_behavior, which an agent must choose between.

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 is implied rather than stated: an agent can infer it should call this when it needs a component's full specification, and the enumerated coverage acts as an implicit trigger. There is no explicit when-to-use, no prerequisites, and no routing to alternatives such as get_component_code for code samples or list_components for discovery.

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 openWorldHint=false, so the safety profile is covered. The description adds real substance beyond that: it discloses what each framework mode returns (reference markup with ARIA wiring, production stylesheet on semantic tokens, editable recipes with lifecycle wiring) and points to implementation metadata for dependencies and responsibilities.

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, front-loaded with the core purpose before per-framework behavior and the metadata pointer. Every sentence carries content, though the middle sentence is somewhat packed and could be tighter.

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?

An output schema exists, so return values need not be explained; annotations cover the safety profile; and the schema fully documents both parameters. The description completes the picture by noting the metadata pointer for dependencies and application responsibilities, leaving no critical gap 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?

Schema description coverage is 100% and the enum descriptions are highly detailed, so the schema carries the parameter semantics. The description only summarizes the framework families (HTML/CSS/framework options) without adding syntax or format detail beyond the schema, making the baseline 3 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 (returns 'Production code') and resource (a component in the requested framework), so the agent knows it produces framework-specific implementation code. It does not explicitly differentiate from siblings like get_component or get_behavior, leaving the boundary slightly inferable.

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 explains what each framework option yields (HTML vs CSS vs framework recipes), which implicitly guides selection, but gives no explicit when-to-use vs when-not or named alternative tools. Usage is implied rather than directed.

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 openWorldHint=false, so no safety contradiction exists. The description adds meaningful behavioral context beyond annotations: the server may be mounted under a path prefix, and the returned URLs are authoritative for this instance. This helps the agent understand why hardcoding paths is unsafe.

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 wasted words. The first sentence front-loads what the tool returns, and the second provides the rationale for using it over assumptions. Every phrase 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 no-parameter, read-only endpoint discovery tool, the description is nearly complete: it lists the artefacts whose URLs are returned, explains why the tool exists, and clarifies the server-authoritative nature. It doesn't specify the exact response shape or keys, but the artefact list gives an agent sufficient expectation of what it will receive.

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

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

The tool has zero parameters and schema coverage is 100% vacuously, so there is no parameter information missing. The description doesn't need to define inputs, and the baseline for zero-parameter tools is 4.

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 returns absolute URLs for specific artefacts (stylesheet, token files, behaviours bundle, documentation site), which distinguishes it from siblings that fetch content or tokens. The verb is implicit but the resource scope is concrete and unambiguous.

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

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

The description explicitly says to use this tool instead of assuming paths, and explains why: the server may be mounted under a path prefix that only the server knows. It doesn't name sibling alternatives or give when-not-to-use conditions, but the context is clear enough for an agent to select it over content-fetching 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 declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds the workflow framing (read before implementing) but says nothing about the form of the returned content (markdown? length? sections?) or any constraints, so it adds only modest context 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 opening clause frames the content well, but the long comma-separated enumeration largely duplicates the schema enum and pads the description. The actionable instruction is buried at the end rather than 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 single-enum-parameter read tool with no output schema, the description conveys the topical scope but not the return shape or size, which is the main thing an agent cannot infer from the schema. Adequate but with a clear 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 coverage is 100% and the single enum parameter is fully documented in the schema. The description's topic list essentially restates the enum values rather than adding syntax, defaults, or selection guidance, 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 enumerates the subject matter ('principles, colour, dark mode, ... theming') which makes clear this returns a design-foundation document, and the closing sentence confirms the read-for-guidance intent. However, it never states the verb directly ('retrieves/returns the foundation doc for the given id') and does not differentiate itself from siblings like get_overview or get_primitives.

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?

'Read the relevant foundation before implementing in that area' gives a clear triggering condition tied to the implementation workflow. It stops short of naming alternatives or when-not-to-use cases (e.g. vs. get_overview or get_tokens), so it is context without 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 mark the tool read-only and closed-world; the description adds useful behavioral context beyond that: returned recipes are flex-first, mostly avoid media queries, include accessibility and dark-mode obligations, and are paste-ready. 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 tight sentences: the first is front-loaded with what the tool returns, the second adds a useful style qualifier. Every word contributes, and there is no redundant restatement 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?

For a read-only, one-parameter tool with an enum and no output schema, the description adequately covers the output contents and general style of the result. It does not describe the response envelope, but the simplicity of the input and annotations make this 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?

The schema covers 100% of parameters, with the single id parameter fully described and an enum of valid layout ids. The description adds nothing about parameter selection, so the schema carries the burden as expected.

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 specifies a concrete deliverable – 'a complete page blueprint' – and enumerates its contents: regions, responsive strategy, accessibility obligations, dark-mode notes, and paste-ready markup plus CSS. This clearly identifies a full-layout resource and sets it apart from component/foundation-level 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 'complete page blueprint' phrasing implies this is the tool for whole-page layouts, and the flex-first note hints at general usage context. However, it never names alternatives like get_component or get_foundation nor says when not to use this tool, so guidance remains implied rather than explicit.

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=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the guide bundles global migration requirements with rollout/rollback guidance, and componentId filtering narrows behavior changes without dropping the global requirements — a non-obvious filtering trait.

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 with the payload scope front-loaded and the parameter nuance second. It is dense but every clause maps to real content or behavior; no filler or restatement 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?

An output schema exists, so return values need not be spelled out, and annotations cover the read-only safety profile. The description completes the remaining gaps — payload composition and the componentId filtering side-effect — leaving only minor omissions such as prerequisites for v3 migration.

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 0% and the schema only gives componentId as a minLength-1 string, so the description must carry the semantics. It does: componentId 'filters behavior changes while preserving global migration requirements,' which tells the agent both the effect and the important side-effect that global content is retained. It stops short of format examples.

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

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

States a specific verb and resource ('get_migration_guide' → 'Full canonical v2-to-v3 migration plan') and enumerates the payload contents (rollout/rollback guidance, behavior changes, compatibility baseline, legacy geometry CSS), so an agent knows exactly what it retrieves. It does not, however, explicitly differentiate itself from overlapping siblings like get_behavior or get_overview.

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 is only implied by the content listing — an agent infers this is for v2→v3 migration work — but there is no explicit 'use this when' statement and no named alternative for narrower questions (e.g., get_behavior). The one guidance-adjacent sentence describes parameter behavior rather than when to select 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, so the read-only nature is covered. The description adds no additional behavioral context such as rate limits or side effects, but is consistent with the annotation. With annotations present, the bar is lower and this meets the baseline.

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?

One efficient sentence, front-loaded with 'Start here', and lists the contents in a compact way. 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 zero-parameter overview tool, the description fully explains what is returned (map with categories and tool calls) and is sufficient for an agent to understand its role without an output schema.

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

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

The tool takes no parameters, so parameter explanation is unnecessary. Per rubric, 0 parameters yields a baseline of 4.

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 returns a map of all available design system resources and includes the tool call for each. It distinguishes itself from specific siblings like get_foundation or list_components.

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 phrase 'Start here' gives clear directive to use this tool first, but it does not explicitly name alternatives or state exclusions. The context is sufficient for a starting point, though not as explicit as naming 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?

The annotations already signal read-only behavior and a closed world, so the description does not need to restate those. It adds useful context about the content of a pattern, but it does not disclose details such as whether the response is a full document, whether there are length limits, or how missing ids behave. This is acceptable given the readOnlyHint, but not rich.

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, compact sentence that uses a colon to list the key sections of a UX pattern. It is efficient and free of filler, though the lack of an explicit verb slightly reduces its structural clarity.

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 get-by-id tool with one enum-constrained parameter and no output schema, the description covers the main return content sufficiently. It names the expected sections of a pattern, and the schema handles id validation, making the tool callable without missing critical 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 input schema has 100% description coverage for the only parameter, id, including an explicit enum of valid pattern ids. The description adds no additional parameter semantics, but the baseline of 3 applies because the schema fully documents the parameter.

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

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

The description clearly identifies the resource as a 'UX pattern' and enumerates its contents: problem, solution, rules, accessibility obligations, and anti-patterns. It is clear about what the tool is about, though it does not explicitly state the retrieval action or distinguish it from sibling tools like get_component or get_foundation.

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 no guidance on when to use get_pattern versus alternatives such as search, list_components, or get_component. It does not mention when to avoid using it or what prerequisites exist, leaving the agent to infer usage from the tool name and title.

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 annotation, the description adds meaningful behavioral context: primitives do not change between themes and therefore will not adapt to dark mode. This explains a key limitation of the data returned and helps the agent understand why these values should not be used directly in product code.

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 short, purposeful sentences: the first defines what the tool returns, the second states when to use it, and the third warns against misuse. There is no redundancy or filler, and the most important 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 simple tool with one optional parameter and no output schema, the description covers purpose, usage, and a critical constraint. It does not explicitly state what happens if the optional ramp parameter is omitted, but the schema's description of the parameter and the overall simplicity of the tool make this a minor gap rather than a significant omission.

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

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

Schema coverage is 100% for the single optional 'ramp' parameter, and the schema already lists the valid ramp names. The description does not add additional parameter-level detail, but it doesn't need to because the schema fully documents the parameter. This matches the baseline for 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 and resource: it returns 'raw colour ramps behind the semantic layer'. It clearly differentiates this from semantic-token tools by explaining that primitives are the underlying layer used to build semantic tokens, which distinguishes it from siblings like get_tokens and get_foundation.

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 use cases: 'Use these to build new semantic tokens or to re-brand.' It also gives a strong when-not-to-use rule: never reference a primitive from product code because it won't adapt to dark mode. It does not name an alternative tool explicitly, but the context is clear enough to guide selection.

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

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

The description adds a concrete behavioral constraint beyond the readOnly/openWorld annotations: the pre-paint theme script must be inline and synchronous or the page shows a flash of the wrong theme. This is actionable knowledge an agent would otherwise not have. 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?

One sentence, front-loaded with the overall purpose, then a tightly packed list of contents. The parenthetical warning is dense but relevant and earns its place. No repetition or filler; it could be split for readability, but it is appropriately compact for the information it carries.

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 optional enum parameter and no output schema, the description conveys both what is returned and a key integration constraint. It doesn't describe the exact return format or how the parts are delimited, which would be helpful, but for a simple get-setup tool this is sufficient. The main gap is no output-structure hints, and that gap is minor because the contents list already sets expectations.

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 describes `part` 100% with enum and a default note, so the baseline is 3. The description adds value by mapping enum values to friendlier terms (utility layer → utilities, theme control markup → theme-control, pre-paint theme script → theme-script), which helps an agent understand the semantic intent of each part. It doesn't explain the `all` default, but the schema already covers that.

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 defines a specific bundle: HTML scaffold, pre-paint theme script, reset, utility layer, prose styles, theme-control markup, framed as 'Everything needed to start'. This clearly distinguishes it from more targeted sibling geters like get_layout or get_tokens, though it doesn't mention any sibling by name. The verb is supplied by the tool name/title, but the resource and scope are unambiguous.

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

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

'Everything needed to start' gives clear situational context: call this tool when bootstrapping a project with the full setup. It doesn't name alternatives or state exclusions, so it stops short of a 5, but it still tells the agent when this tool is the right choice better than a purely generic description would.

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 and closed-world behavior, so the description does not need safety disclosures. It adds value by describing the all-in-one-file behavior and the exact layers returned, going 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?

Two sentences, no filler, with the central purpose and content scope front-loaded. 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?

One optional parameter, fully schema-documented, and no output schema, so the description's enumeration of returned layers is sufficient context for an agent. It could mention the include filter explicitly, but that is already in the schema.

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 include parameter, its enum values, and default-all behavior all documented. The description does not need to repeat this, but it also adds no extra parameter meaning.

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

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

States a specific verb (get) and resource (stylesheet), then spells out exact contents: tokens for four themes and three densities, reset, prose, utilities, and every component. This clearly distinguishes it from sibling tools like get_tokens or get_component.

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 frames the tool as 'the single artefact needed to render any Sekura interface,' giving a clear condition for use. It does not name when-not alternatives, but the resource scope makes the intended usage strong.

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 the description builds on that by disclosing the resolved-value nature, the multi-theme output behavior, and the all-or-filtered scope. It doesn't contradict the annotations or claim side effects; the only minor gap is not stating output shape or limits, but the read-only and closed-world hints lower the burden.

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

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

The main statement is front-loaded in one short sentence, followed by a compact summary of filters and output behavior. Every sentence earns its place, and no schema information is redundantly repeated.

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 four optional parameters with full schema descriptions, read-only annotations, and no output schema, the description covers the core behavioral expectations: what is returned, how filtering works, and the all-themes default. It could be slightly more explicit about when to choose this over sibling tools, but nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already explains group, theme, filter, and includeScales. The description adds only a compact restatement ('filter by group, by name fragment, or return everything') and the default all-themes behavior, which is useful but not needed to understand the parameters.

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 resource ('resolved token values') and a clear action (return them), then distinguishes the tool's breadth: filters by group or name fragment, or returns everything. It also adds the cross-theme viewing behavior, which separates it from related tools like get_primitives or export_tokens without needing to open schema.

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

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

The description effectively gives usage context: use this for resolved tokens, optionally scoped by group, theme, or name fragment, and compare theme values side by side. It doesn't name sibling alternatives or give when-not conditions, but the intended invocation context is clear from the filtering options and 'resolved' wording.

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 openWorldHint=false, so the read-only, closed-world nature is covered. The description adds that this is a complete catalogue with optional filters, but does not disclose ordering, pagination, or default inclusion of deprecated items. This is adequate given the annotation coverage, but not rich.

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 one short sentence: 'The component catalogue, optionally filtered by category or status.' It is front-loaded with the core noun phrase, adds the conditional filter clause, and contains no redundant or filler words. 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 read-only listing tool with two optional enum parameters and no required fields, the description covers the essential what (component catalogue) and how (optional filters). It does not describe the return shape or pagination, but the tool name and 'catalogue' imply a list, and readOnlyHint covers safety. A bit more detail about what each catalogue entry includes would push it higher.

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%: both status and category have clear descriptions ('Filter by maturity.' and 'Filter by category.') and enums. The description merely paraphrases the schema with 'filtered by category or status', adding no new semantic meaning, so it stays at the baseline 3.

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 resource ('the component catalogue') and implies the listing operation, distinguishing it from single-item siblings like get_component. It does not use an explicit active verb beyond the title, and it does not name a specific sibling alternative, so it stops short of a 5.

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 offers no guidance on when to use this tool versus search, get_component, or get_layout. 'Optionally filtered by category or status' implies flexibility but not a selection criterion. No alternatives or exclusions are mentioned.

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 openWorldHint=false, so the safety profile is covered. The description adds the search scope but says nothing about ranking, result ordering, or how the limit interacts with results, so it contributes limited behavioral context beyond the structured fields.

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, zero filler, with the scope statement front-loaded ahead of the usage condition. Every clause carries information.

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

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

With no output schema, the description could say something about result shape or ordering, and it does not. However, the annotations, complete schema coverage and default-limit documentation mean an agent has enough 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 query, kinds and limit are already documented in the schema. The description's domain list loosely maps to the kinds enum but adds no syntax or format guidance beyond it; baseline 3 applies.

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

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

States a specific verb (full-text search) and resource (the design-system corpus), and enumerates the content domains it covers. That enumeration plus the 'full-text' qualifier cleanly separates it from the get_*/list_* siblings, which retrieve a single known artifact.

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?

'Use when you know what you need but not where it lives' gives a clear, actionable selection condition. It implies rather than names the alternative (the direct get_component/get_tokens tools when you do know where it lives), so it falls just short of an explicit when-not/alternative statement.

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 the tool is read-only, and the description adds meaningful behavioral detail beyond that: it returns resolved values per theme and explains token selection with reasoning about neighboring tokens. This gives the agent a clear picture of the tool's output without contradicting any 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, both substantive: the first explains the tool's function and output, the second gives practical usage guidance. 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 simple, read-only tool with only one required parameter and no output schema, the description covers the key context: how to phrase the input, what kind of results to expect, and when to prefer this tool over guessing. It could be slightly more complete by explicitly noting the optional limit parameter or naming a sibling alternative, but these are minor gaps.

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

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

The description explains the intent parameter semantically ('Describe what you are styling in plain words') and the schema provides useful examples for intent. However, the optional 'limit' parameter is not mentioned in the description and has no schema description, so the semantics of that parameter are left entirely to inference from its name and min/max constraints.

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 ('Describe... and get') with a clear resource ('semantic tokens') and states what is returned: resolved values per theme and a rationale comparing to neighboring tokens. This clearly distinguishes the tool from siblings like get_tokens or search, which retrieve tokens rather than recommend them from a natural-language intent.

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 instruction 'Use this instead of guessing a token name or reaching for a hex value' gives clear guidance on when this tool is appropriate. It does not explicitly name alternative sibling tools or state when not to use it, but the intended use case is unambiguous.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: it returns structured findings plus fixes, and explicitly does not execute callbacks — a meaningful side-effect boundary the annotations do not convey.

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

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

Two tight sentences with no filler; the validated surface is front-loaded and the behavioral caveat follows. Efficient and well-ordered for its size.

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?

An output schema exists, so return value detail is not owed by the description, and the read-only nature is covered by annotations. However, the low parameter coverage and absence of any when-to-use/alternative routing leave gaps for an agent deciding whether to call this versus validate_markup.

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 only 13% across 8 parameters, so the description must compensate. It narratively covers markup, stylesheets, SVG symbols, ID references (externalIds), initialization, and handledEvents, but omits controllers and componentIds and gives no format/syntax detail. Partial compensation justifies a mid 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 states a specific verb (check) and enumerates exactly what is validated: markup, stylesheet dependencies, SVG symbols, ID references, initialization, and declared events. This is far more concrete than the title, though it never explicitly distinguishes itself from the sibling validate_markup beyond the implicit 'integration' scope.

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

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

There is no when-to-use guidance and no mention of the obvious sibling validate_markup, which an agent would need to choose between. The scope (integration-level) is only inferable from the name and the checklist of what it inspects.

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 annotations set openWorldHint=false, implying a closed-world result where absence of findings is meaningful. The description says 'Advisory — a clean result is not a certificate of accessibility,' which asserts the opposite: a clean lint result does not rule out accessibility failures. This directly contradicts the openWorldHint 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 two sentences with no filler. The first sentence is front-loaded with the action and resource, and the list of concrete failure types earns its place. The advisory caveat is short but materially changes how the result should be interpreted.

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

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

Given only two simple parameters and a complete schema, the invocation inputs are well covered. The main gaps are the absence of any description of the result shape—there is no output schema—and no explicit differentiation from validate_integration. These are minor for calling the tool but material for interpreting its response.

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

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

The input schema fully documents both parameters, with 100% schema description coverage, so the baseline is 3. The description repeats the HTML/CSS scope and implies component-specific checking but adds no additional syntax, formatting, or semantic detail 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?

The description opens with a specific verb and resource: 'Checks HTML or CSS for the accessibility and design-system failures...' and lists concrete failure classes such as missing accessible names, unlabelled inputs, and hard-coded colours. This makes the tool's purpose unmistakable and distinguishes it from siblings like validate_integration without requiring a schema inspection.

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 first sentence clearly communicates that the tool applies to HTML/CSS markup, so the input context is implied. However, there is no explicit when-not-to-use guidance and no reference to alternatives such as validate_integration, leaving the agent to infer the routing between validation tools.

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