Server Quality Checklist

Tool Scores

• list_componentsB
  3.2/5.0
  Behavior3/5

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

  The readOnlyHint annotation already conveys the safe read-only nature, and the description aligns with that. It adds the notion of filtering but doesn't disclose return structure, pagination, or default behavior with no filters. No contradiction.

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

  Conciseness4/5

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

  The description is one sentence and front-loaded with 'component catalogue', making it concise. However, it is a noun phrase rather than an explicit verb phrase, which slightly reduces actionability.

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

  Completeness3/5

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

  For a simple list tool with two optional enum parameters, the description is adequate but leaves out what the returned catalogue entries look like and what happens when no filters are applied. Without an output schema, a bit more return context would be helpful.

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

  Parameters3/5

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

  Both parameters are fully described in the schema with enums and descriptions, so the description's mention of 'filtered by category or status' adds no new meaning. Schema coverage is 100%, so the schema carries the semantic weight.

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

  Purpose4/5

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

  The description identifies the tool as 'the component catalogue', implying a list of components with optional filters. It is clear enough, but it relies on the title for the verb and doesn't explicitly differentiate from siblings like get_component or search.

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

  Usage Guidelines2/5

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

  No guidance is given on when to use this tool versus alternatives such as get_component or search. The optional filters hint at usage context, but there is no explicit when-to-use or when-not-to-use guidance.

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

• export_tokensA
  3.6/5.0
  Behavior3/5

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

  readOnlyHint and openWorldHint already establish a read-only, closed-world operation. The description adds the useful property that all outputs derive from a single source, so changes propagate consistently. It doesn't disclose response size or format details beyond what the schema provides, but with annotations, this is adequate.

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

  Conciseness5/5

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

  Two sentences, tightly packed. The first sentence gives the core action, the second adds the single-source propagation behavior. No unnecessary words.

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

  Completeness4/5

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

  The tool's complexity (11 formats, theme constraints) is mostly handled by the exhaustive format descriptions in the schema. The description adds the single-source consistency fact, which is useful context. However, the description doesn't explicitly state the output type (e.g., string content vs file download), but given the format descriptions, this is a minor gap. For a tool with no output schema, this is sufficient.

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

  Parameters3/5

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

  Schema description coverage is 100% with detailed per-param descriptions, so the baseline is 3. The description adds no semantic information about the parameters themselves; the 'full token set' line is a property of the tool, not of any specific parameter.

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

  Purpose4/5

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

  Clear verb+resource+scope ('Emit the full token set in a consumable format'). Distinguishes from siblings like get_tokens and get_primitives by focusing on export/build format, though it doesn't explicitly name an alternative.

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

  Usage Guidelines3/5

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

  The description implies usage for generating distributable token artifacts but provides no explicit when-to-use or when-not-to-use guidance. No alternative tools are named. The schema's format descriptions offer some context, but the description itself doesn't state when to prefer export_tokens over get_tokens or inspect siblings.

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

• get_tokensA
  3.8/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, so the read-only nature is established. The description adds valuable behavioral context: it returns values across all themes by default, making dark-mode differences visible side by side. This exceeds the annotations without contradicting them.

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

  Conciseness5/5

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

  Two concise sentences, front-loaded with the core purpose ('Resolved token values'). Every clause earns its place—filters and theme behavior are covered with zero fluff.

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

  Completeness4/5

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

  Given the read-only annotation, rich schema, and simple list return, the description covers the essential behavior: resolvable filters and all-theme display. No output schema exists, so the description's mention of theme side-by-side serves as a return hint. Minor gaps like pagination or ordering are not critical for this tool.

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

  Parameters3/5

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

  The input schema already documents all 4 parameters with descriptions, achieving 100% coverage. The description adds minimal extra meaning—it paraphrases the 'group' and 'filter' parameters but does not deepen semantic understanding beyond the schema. Baseline 3 applies.

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

  Purpose4/5

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

  The description states the tool retrieves resolved token values, and distinguishes from siblings like get_primitives by emphasizing 'resolved'. It specifies filtering by group, name fragment, or everything. However, it does not explicitly name alternative tools for raw values or search, so it lacks strong sibling differentiation.

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

  Usage Guidelines3/5

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

  The description implies usage context: use this to fetch resolved token values with optional filters. It does not explicitly state when to use an alternative like search or get_primitives, nor provide exclusions. Guidance is present but implicit.

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

• get_foundationA
  3.9/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, so the description does not need to restate safety. The description adds context about the tool's purpose ('reasoning behind the system') and usage timing, but does not disclose return format, pagination, or other behavioral traits. This is adequate but not rich beyond what annotations convey.

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

  Conciseness4/5

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

  The description is two sentences, front-loading the content scope and then adding a clear usage instruction. The list of topics is somewhat long but directly reflects the valid parameter values, so it is informative rather than redundant. No filler or unnecessary wording.

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

  Completeness4/5

  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 a single enum parameter and no output schema, the description covers the essential context: what the document contains and when to read it. It does not explain the return structure, but that is unnecessary given the tool's simplicity and the readOnlyHint annotation. Complete enough for reliable selection and invocation.

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

  Parameters3/5

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

  The input schema provides 100% coverage with a descriptive enum list and a 'Foundation id.' description. The tool description repeats the enum values in prose, which adds context but no new semantic meaning about parameter usage. The baseline of 3 applies when the schema handles parameter documentation well.

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

  Purpose5/5

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

  The description clearly states the tool retrieves a foundation document covering design system reasoning, listing specific areas like principles, color, and typography. This distinguishes it from sibling tools like get_tokens or get_component, which fetch different resource types. The verb 'get' plus resource type and content scope make the purpose explicit.

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

  Usage Guidelines4/5

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

  The instruction 'Read the relevant foundation before implementing in that area' provides clear guidance on when to use this tool: as a prerequisite for implementation work. It does not explicitly name alternatives or exclusions, but the context is strong enough to avoid misuse. A 5 would require explicit when-not-to-use or alternative tool references.

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

• get_layoutA
  4/5.0
  Behavior4/5

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

  Annotations already establish read-only safety, so the description adds value by detailing the exact contents returned (regions, responsive strategy, accessibility obligations, dark-mode notes, markup, CSS) and the design trait (flex-first, most no media queries). This goes beyond the bare annotation and sets expectations for output richness.

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

  Conciseness5/5

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

  The description is two tight sentences: the first lists the output components, the second notes the design constraints. No redundant or filler words; every phrase adds information.

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

  Completeness4/5

  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 a single enum parameter and no output schema, the description sufficiently conveys what the payload includes and its design approach. It lacks an explicit return format or pagination details, but these are not necessary given the finite enum and read-only nature. The coverage is adequate for an agent to select and invoke it.

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

  Parameters3/5

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

  The schema covers the only parameter (id) with an enum and a short description. The tool description does not add further meaning to the id parameter itself; it does not explain the differences between enum values or how to choose an id. With 100% schema coverage, the description adds no parameter semantics, so baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly identifies this as a page-level layout retrieval tool, enumerating the deliverable contents (regions, responsive strategy, accessibility, dark-mode, markup, CSS), and the title 'Get a page layout recipe' reinforces the specific resource. It distinguishes from component/pattern/token tools in the sibling list by focusing on complete page blueprints.

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

  Usage Guidelines3/5

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

  The description implies usage for complete page layouts through its blueprint content, but it does not explicitly state when to prefer this over alternatives such as get_component or get_pattern, nor does it provide exclusion criteria. The flex-first note hints at design context but not tool selection.

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

• get_component_codeA
  4.1/5.0
  Behavior4/5

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

  Annotations already indicate readOnlyHint=true, so the description is not required to disclose mutation. It adds valuable behavioral context by explaining what each framework returns (reference markup with ARIA, stylesheet with tokens, typed wrappers with forwarded accessibility attributes). This goes beyond the annotations and gives the agent a clear picture of the output nature.

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

  Conciseness5/5

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

  The description is exactly two sentences, front-loaded with the core purpose, then expanding into framework-specific behavior. There is no redundancy or filler; every sentence earns its place. This is a model of conciseness.

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

  Completeness5/5

  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 two well-documented parameters and no output schema, the description fully covers what the tool does and what to expect from each framework variant. It is complete for an agent to select and invoke correctly without additional context.

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

  Parameters3/5

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

  Schema coverage is 100%, so the schema already documents both parameters ($id and framework) and even provides per-enum descriptions for framework. The description reiterates the framework distinctions in prose but adds no new information beyond the schema. As per the rubric, a baseline of 3 is appropriate when the schema is thorough.

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

  Purpose5/5

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

  The description states a specific verb+resource: 'Production code for a component in the requested framework.' It also clarifies the expected output type for each framework option, which distinguishes it from sibling tools like get_component (which likely returns component metadata/overview) and get_stylesheet (which likely returns only the stylesheet). This is more specific than the title alone.

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

  Usage Guidelines3/5

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

  The description implies usage: if you need production component code in a particular framework, use this tool. However, it does not explicitly mention when not to use it or name alternatives such as get_stylesheet for stylesheet-only needs. With many sibling tools listed, the lack of explicit differentiation leaves some ambiguity for an agent.

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

• get_patternA
  4.1/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds valuable context by specifying the structure of the returned pattern (problem, solution, rules, accessibility obligations, anti-patterns), going beyond the annotations without contradicting them.

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

  Conciseness5/5

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

  The description is a single, well-structured sentence that front-loads the core purpose and uses a colon to list the included components. Every word earns its place with no redundancy.

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

  Completeness5/5

  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 one parameter and no output schema, the description is complete. It clearly explains what the tool returns and the schema fully documents the parameter. No critical information is missing for an agent to correctly select and invoke the tool.

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

  Parameters3/5

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

  The input schema has 100% coverage with a single enum parameter 'id' described as 'Pattern id.' The description does not add any additional meaning beyond the schema, so a baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool retrieves a UX pattern and enumerates its contents (problem, solution, rules, accessibility obligations, anti-patterns). It distinguishes from sibling tools like get_component or get_foundation by focusing on recurring UX problems and the Sekura answer.

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

  Usage Guidelines3/5

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

  The description implies usage when a UX pattern is needed, but it does not explicitly mention alternatives or when-not-to-use scenarios. Sibling tools exist but are not referenced, so the guidance is limited to implied context.

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

• searchA
  4.1/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds the search scope (across components, foundations, etc.) but does not disclose behavior like result format, pagination, or default limits. This is similar to the get_calls example where basic scope is added but return behavior is omitted.

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

  Conciseness5/5

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

  Two concise sentences, front-loaded with the core function and a clear usage heuristic. No filler or redundancy; every word earns its place.

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

  Completeness5/5

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

  For a simple search tool with comprehensive schema coverage and read-only annotations, the description provides sufficient context. It explains what is searched, the use case, and the schema handles parameter details. No output schema is needed for a search tool that returns matching items.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema fully documents all parameters (query, kinds, limit). The description adds general context about full-text search but does not enhance parameter meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool performs full-text search across specific resource types (components, foundations, patterns, layouts, tokens) with a specific verb. It distinguishes itself from sibling retrieval tools by framing its purpose as finding content when location is unknown.

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

  Usage Guidelines4/5

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

  Provides explicit usage guidance: 'Use when you know what you need but not where it lives.' This clearly indicates the appropriate context, though it does not explicitly mention alternatives or when-not-to-use scenarios.

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

• suggest_tokenA
  4.1/5.0
  Behavior4/5

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

  Annotations already mark this as read-only (readOnlyHint=true), so safety is established. The description adds behavioral context beyond annotations by describing the output: 'resolved values per theme and a note on why that token rather than a neighbour.' It does not explain limit behavior or edge cases, but for a read-only suggestion tool, this is adequate.

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

  Conciseness5/5

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

  The description is two concise sentences, front-loading the main action ('Describe what you are styling') and adding a clear usage tip ('Use this instead of...'). No unnecessary words or repetition.

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

  Completeness3/5

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

  While the description covers the core purpose and gives some output details (resolved values per theme, reasoning), it fails to explain the 'limit' parameter and does not clarify how themes are determined or whether the tool relies on the current theme. Given there is no output schema, more detail on return values and parameter behavior would be needed to be fully complete.

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

  Parameters3/5

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

  The 'intent' parameter is well explained in both the schema (with examples) and the description ('Describe what you are styling'). However, the 'limit' parameter has no description in either the schema or the tool description, so its purpose (likely output count) is unclear. With schema description coverage at 50%, the description only partially compensates for the missing documentation.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Describe what you are styling in plain words and get the semantic tokens that apply.' It uses a specific verb (get) and resource (semantic tokens), and distinguishes itself from sibling tools like 'get_tokens' by emphasizing intent-based natural language input and reasoning about token selection.

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

  Usage Guidelines4/5

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

  The description gives clear context: 'Use this instead of guessing a token name or reaching for a hex value.' This indicates when to use the tool (when you don't know the exact token) but does not explicitly name alternative tools or describe when not to use it beyond the 'instead of' guidance. It gives useful context without full exclusions.

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

• audit_themeA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds meaningful context: the scope (all four themes or one), the build-gate role, and a key semantic rule ('A pairing that is not declared here is not promised'). 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.

  Conciseness5/5

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

  Two sentences, zero waste. The first sentence states what it does, the second gives usage and a critical design-system rule. Perfectly front-loaded and structured.

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

  Completeness4/5

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

  Given the moderate complexity, the description covers purpose, usage context, and a semantic constraint. It doesn't describe output format or failure reporting, but the read-only annotation and clear scope make the tool easy to use. Sibling differentiation via check_contrast is implicit but sufficient.

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

  Parameters3/5

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

  Schema coverage is 100%, with both parameters described in the schema. The description restates the theme omission behavior ('one theme or all four') which is already in the schema, and doesn't add new meaning for failuresOnly. Baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states a specific verb ('Runs') and resource ('every contrast promise... against one theme or all four'). It distinguishes from sibling tools like check_contrast by emphasizing it audits all declared pairings, not just specific checks.

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

  Usage Guidelines4/5

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

  The description explicitly names when to use it: 'run it after any palette change' and frames it as the 'build gate.' It doesn't name alternatives or explicitly say when not to use it, but the context strongly implies it's the comprehensive audit.

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

• check_contrastA
  4.2/5.0
  Behavior4/5

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

  Annotations already indicate read-only (readOnlyHint=true). The description adds behavioral detail beyond annotations: token resolution per theme and compositing translucent values over the page. This gives the agent important context about how inputs are processed 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.

  Conciseness5/5

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

  The description is two sentences, front-loaded with the core function, and each sentence earns its place. No fluff or repetition of schema details.

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

  Completeness4/5

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

  The tool is simple and low-complexity. The description mentions the output (ratio and pass/fail verdict) and the schema covers thresholds via enum descriptions. It is complete enough for an agent to understand the tool's behavior without an output schema.

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

  Parameters3/5

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

  Schema coverage is 100% and each parameter has a meaningful description. The tool description adds minimal extra parameter semantics—only the note about compositing translucent values—which is somewhat beyond the schema but not substantial. Baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states a specific verb ('Check') and resource ('colour pair against WCAG'), and specifies WCAG 2.2 contrast ratio and pass/fail verdict. This distinguishes it from all sibling tools, none of which mention contrast or WCAG.

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

  Usage Guidelines4/5

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

  The description conveys clear usage context: it accepts hex values or token names and resolves tokens for the chosen theme. It does not explicitly state when not to use it, but the uniqueness among siblings and the specific focus on contrast make the intended use obvious.

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

• get_stylesheetA
  4.2/5.0
  Behavior4/5

  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 nature is covered. The description adds valuable context about the content (four themes, three densities, all layers) and its purpose, exceeding what the annotations alone provide.

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

  Conciseness5/5

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

  Two sentences with no filler. The first sentence efficiently lists the stylesheet contents, and the second highlights its purpose. Every word earns its place.

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

  Completeness4/5

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

  For a simple read-only retrieval tool with one optional parameter and no output schema, the description is quite complete. It explains the return scope and provides usage context, though it does not specify the exact output format (e.g., CSS text vs. file download).

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

  Parameters3/5

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

  The schema description covers the sole parameter 'include' with 100% documentation, so the baseline is 3. The description does not add additional meaning beyond listing the layers, which the schema already enumerates.

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

  Purpose5/5

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

  The description clearly states the tool retrieves the entire Sekura stylesheet as one file, enumerating its contents (tokens, reset, prose, utilities, components). It distinguishes this from sibling tools like get_tokens or get_foundation by emphasizing this is the single artefact needed for any interface.

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

  Usage Guidelines4/5

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

  The phrase 'This is the single artefact needed to render any Sekura interface' provides a clear when-to-use directive. It implies that this tool is for complete stylesheet requests, though it does not explicitly mention alternatives or exclusions.

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

• validate_markupA
  4.2/5.0
  Behavior4/5

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

  The description goes beyond the readOnlyHint annotation by enumerating the specific failure categories it detects, giving the agent a clear sense of coverage. It also explicitly states the tool's advisory nature ('a clean result is not a certificate of accessibility'), which is important behavioral context. No contradictions 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.

  Conciseness5/5

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

  The description is compact yet information-dense: two sentences that immediately state the tool's function, list concrete examples of what it catches, and add a crucial advisory. No fluff or repetition.

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

  Completeness4/5

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

  The description covers the tool's core function, scope, and advisory nature. It doesn't explicitly describe the output format, but the mention of 'a clean result' implies a pass/fail or issue list, which is sufficient for a linter. With only two clearly-schema'd parameters and read-only annotations, the contextual needs are modest.

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

  Parameters3/5

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

  The input schema provides full descriptions for both parameters (markup and componentId) at 100% coverage, so the schema carries the semantic weight. The description does not add parameter-level details, but it does provide context about the tool's purpose which indirectly clarifies the markup input. Baseline 3 applies because schema coverage is high.

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

  Purpose5/5

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

  The description uses the specific verb 'Checks' and clearly identifies the resource (HTML/CSS) and the specific categories of failures (accessibility, design-system). It distinguishes from sibling tools by listing concrete examples, making it clear this is a markup linting tool, not a contrast or theme audit.

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

  Usage Guidelines4/5

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

  The description clearly indicates the tool is for linting markup for specific accessibility/design-system issues, providing context for when it applies. It also includes an advisory that a clean result isn't a full accessibility certificate, which tempers expectations. However, it does not explicitly compare to sibling tools like check_contrast or audit_theme, so it lacks explicit exclusions/alternatives.

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

• get_componentA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, so behavioral safety is covered. The description adds substantial context about the content returned (e.g., accessibility contract, dark-mode behavior, tokens consumed), which goes beyond structured annotations and helps set expectations for the response.

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

  Conciseness5/5

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

  The description is one dense sentence that efficiently enumerates the scope of the spec without fluff. Each listed item adds meaningful detail, and the structure is front-loaded with 'complete spec for one component' before expanding.

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

  Completeness5/5

  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 carries the burden of explaining return contents. It covers all major aspects of a component spec comprehensively (anatomy, variants, props, accessibility, content, do/don't), making the tool's purpose and result unambiguous for an agent.

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

  Parameters3/5

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

  The input schema already documents the single 'id' parameter with a clear description and examples, giving 100% schema coverage. The tool description adds nothing specific about parameters, so a baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description specifies a clear verb ('get') and resource ('component specification'), with an explicit enumeration of content: anatomy, variants, states, props, accessibility contract, etc. This distinguishes it from sibling tools like get_component_code or get_pattern.

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

  Usage Guidelines4/5

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

  The description clearly states that this returns the complete spec for one component, implying it is the go-to for full specification details. It lacks explicit exclusions or alternative tool mentions, but the context is clear enough for a single-purpose getter.

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

• get_overviewA
  4.3/5.0
  Behavior3/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• get_primitivesA
  4.6/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint=true, but the description adds meaningful behavioral context beyond safety: primitives are theme-invariant and will not adapt to dark mode, and referencing them in product code is disallowed. This is genuinely useful information that the annotations do not provide.

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

  Conciseness5/5

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

  The description is only two sentences, the first immediately defines what the tool does, the second packs usage guidance and a critical warning. No filler words, 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.

  Completeness4/5

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

  For a simple retrieval tool with one optional parameter and no output schema, the description adequately covers what it returns and key usage constraints. It does not explicitly state the behavior when the ramp parameter is omitted, but the optionality in the schema combined with the description is sufficient for an agent to infer the likely behavior.

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

  Parameters3/5

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

  The input schema already provides 100% coverage with a detailed description of the 'ramp' parameter and its possible values. The tool description does not add any additional parameter syntax or behavior, so the baseline 3 is appropriate.

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

  Purpose5/5

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

  The description uses a specific verb-resource pair: 'raw colour ramps' are the resource being retrieved, and the purpose is clearly to access primitives behind the semantic layer. It distinguishes from siblings like get_tokens by emphasizing 'behind the semantic layer' and the stated use case of building semantic tokens or re-branding.

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

  Usage Guidelines5/5

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

  It explicitly says when to use ('Use these to build new semantic tokens or to re-brand') and gives a strong exclusion ('Never reference a primitive from product code'), explaining why (does not adapt to dark mode). This provides clear context and a when-not, even though it does not name sibling tools directly.

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

• get_setupA
  4.6/5.0
  Behavior5/5

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

  Beyond the readOnlyHint and openWorldHint annotations, the description discloses a critical behavioral requirement: the pre-paint theme script 'must be inline and synchronous, or you get a flash of the wrong theme.' It also details exactly what content is included, adding substantial value 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.

  Conciseness5/5

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

  One dense, well-structured sentence that leads with the primary purpose and uses every clause to convey necessary information. The parenthetical warning is valuable and not extraneous.

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

  Completeness4/5

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

  The description covers the tool's purpose, the full list of included parts, and a critical deployment nuance. The `part` parameter's default and enum values are already in the schema, so the description only needs to clarify what each piece is. It does not describe the exact output format, but for a setup-bundle tool this is nonessential.

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

  Parameters4/5

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

  The schema only provides a generic 'which part to return' description and bare enum values. The tool description maps those enum values to concrete, meaningful content (HTML scaffold, theme script, reset, utilities, prose, theme control) and adds an important constraint for the theme-script part, enriching the parameter semantics.

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

  Purpose5/5

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

  The description states the tool returns 'Everything needed to start' and enumerates the exact contents: HTML scaffold, pre-paint theme script, reset, utility layer, prose styles, and theme control markup. This clearly distinguishes it from sibling tools that focus on components, patterns, or tokens.

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

  Usage Guidelines4/5

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

  The phrase 'Everything needed to start' clearly indicates this tool is for initial project setup. It does not explicitly mention alternative tools or when not to use it, but the context is unambiguous and sufficient for a starting-point utility.

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