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

With readOnlyHint annotation already declaring the tool as safe/read-only, the description adds the behavior of defaulting to the first variant when omitted. It does not disclose error handling, output format details, or any edge cases, but the annotation reduces the burden. This is consistent with a moderate score.

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

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

The description is three sentences long, front-loaded with the core purpose, and every sentence adds value—returning markup, default behavior, and a pointer to a sibling tool. No fluff or redundancy.

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

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

For a simple read-only tool with only two parameters and an output schema present, the description is sufficiently complete. It clarifies the default variant behavior and how to discover variants. Slightly more detail on error cases or output structure could push it to 5, but the existing context is adequate.

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

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

Schema description coverage is 100%, and both 'component' and 'variant' are well-documented in the schema. The description repeats the default-variant behavior already present in the schema, adding no additional parameter meaning. Baseline 3 applies here.

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 'Returns' and the resource 'HTML markup for one specific variant of a Bootstrap Italia component', making the tool's purpose unambiguous. It also distinguishes from the sibling tool by pointing to bsi_list_component_variants for discovering variant names, which sets it apart from listing tools.

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

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

The description provides clear guidance on when to use this tool: for getting markup for a specific variant, and explicitly tells the user to use bsi_list_component_variants to discover available names. It lacks an explicit exclusion or comparison with devkit_get_component_markup, but the reference to the variant-discovery sibling covers the main alternative usage.

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

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

Annotations already declare `readOnlyHint: true`, and the description adds useful non-obvious context: the library-specific behavior, the complete set of valid statuses, the default library, and the uiKitItalia limitation (Figma-only). It does not describe the response format, but an output schema is present, so the description carries acceptable weight for a read-only filter tool.

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

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

The description is only three sentences and front-loads the core action. Every sentence earns its place: the first states the operation and main parameters, the second lists valid values, and the third covers a limitation and points to the sibling alternative. No filler or redundant restating.

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

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

Given the tool's modest complexity, a complete input schema, a read-only annotation, and an output schema, the description covers all essential operational details: valid statuses, library choices and default, an explicit limitation, and a clear alternative. There are no critical gaps that would leave an agent guessing.

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

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

The input schema already describes both parameters at 100% coverage, so the baseline is 3. The description goes beyond the schema by enumerating every accepted status value, specifying the default library (`bootstrapItalia`), and warning that uiKitItalia is unsupported, which adds meaningful parameter-level guidance.

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

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

The description opens with a specific verb ('Lists') and clearly names the resource ('Design System .italia components') and the filtering dimension (implementation status). It also distinguishes itself from the sibling `dsi_list_components` by noting its per-library filtering and explicitly pointing to that sibling for full 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?

The description explicitly states when to use this tool versus alternatives: 'Use dsi_list_components for full status overview.' It also clarifies that uiKitItalia is not filterable here (Figma-only), provides the default library, and enumerates all valid status values, leaving little ambiguity about when this tool is appropriate.

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 readOnlyHint annotation already indicates a safe read operation. The description adds useful behavioral context by stating 'Returns names only — no markup,' which clarifies the output scope and prevents the agent from expecting markup. This goes beyond the annotation without contradicting it.

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

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

The description is two sentences, front-loads the primary purpose, and includes the alternative reference without unnecessary fluff. Every sentence earns its place.

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

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

For a simple one-parameter tool with an output schema, the description fully covers the purpose, output, and alternative. No additional context is needed.

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

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

Schema description coverage is 100% for the single 'component' parameter, with the schema already providing an example and type. The tool description adds no additional parameter-specific details, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Lists all available variant names for a Bootstrap Italia component.' It uses a specific verb and resource, and explicitly differentiates from the sibling tool by saying 'Returns names only — no markup. Use bsi_get_component_markup to fetch a specific variant.'

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 direct usage guidance and an alternative: 'Use bsi_get_component_markup to fetch a specific variant.' This clearly tells the agent when to use this tool versus the complementary markup-fetching 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 declare readOnlyHint, and the description adds useful context beyond that: markup is extracted from Storybook via CI snapshot, and omitting the variant returns the default (first) variant. This provides meaningful behavioral information without contradicting the annotations.

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

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

The description is three sentences, front-loaded with the main purpose, then concise supporting details. Every sentence earns its place with no redundancy or filler.

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

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

For a simple read-only retrieval tool with an output schema and good annotations, the description covers purpose, source, and default behavior. It is largely complete, though it could mention how this tool differs from the bsi_get_component_markup sibling.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying that variant is optional and defaults to the first variant, which supplements the schema's parameter description.

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 HTML markup for a specific variant of a Dev Kit Italia web component, using a specific verb and resource. It does not explicitly distinguish this from the similar sibling bsi_get_component_markup, so it is clear but lacks explicit sibling differentiation.

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 usage when you need markup for a particular variant, and explains the default behavior when variant is omitted. However, it does not state when to choose this tool over alternatives like bsi_get_component_markup or devkit_list_component_variants.

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 indicate readOnlyHint=true, and the description adds behavioral detail about including subcomponent props and listing specific fields (name, type, description, default, options). This goes beyond the bare annotation without contradicting it.

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

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

The description is two sentences, front-loaded with the core action and resource, and includes a concrete example ('it-accordion-item'). No filler or redundant content.

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 list tool with one parameter and an output schema, the description is sufficient. It specifies what is returned, the target components, and the inclusion of subcomponents, leaving no major 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?

Schema coverage is 100%, providing a baseline of 3. The description adds meaning by restricting the 'component' parameter to Dev Kit Italia it-* components and mentioning subcomponent support, which clarifies valid input beyond the schema's simple 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?

The description clearly identifies the tool's action ('Lists all HTML attributes'), the resource ('Dev Kit Italia web component (it-*)'), and the scope ('Includes subcomponent props'). It distinguishes from sibling tools like devkit_list_component_variants by focusing specifically on props.

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

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

The description provides clear context on when to use the tool — when you need HTML attributes/props for a Dev Kit component. It does not explicitly mention alternatives or when not to use it, but the usage scenario is unambiguous due to the focus on props.

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 readOnlyHint annotation already declares a safe read operation. The description adds behavioral context by specifying that the tool 'returns names only,' which clarifies the return shape and avoids expecting full component data. It doesn't mention edge cases like empty results or ordering, but for a simple list tool this is sufficient.

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 the key action stated immediately. It wastes no words and every sentence earns its place by explaining purpose and the alternative tool.

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?

This is a simple read-only list tool with one parameter, an output schema, and a clear description of return semantics ('names only'). The description, combined with annotations and schema, fully covers what the agent needs to know. The existence of an output schema also means return values need not be elaborated further.

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 provides 100% coverage for the single 'component' parameter, including an example. The tool description adds no additional parameter detail beyond the schema. As schema coverage is high, the baseline of 3 is appropriate.

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

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

The description clearly states the tool lists all available variant names for a Dev Kit Italia web component, with a specific verb (lists) and resource (variant names). It also notes the output is names only, which distinguishes it from sibling tools like devkit_get_component_markup that fetch full markup.

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

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

The description gives clear guidance to use devkit_get_component_markup for fetching a specific variant, establishing an explicit alternative. It implies this tool is for discovering variant names. However, it doesn't explicitly state 'when not to use' beyond the markup reference, so it falls just short of a 5.

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

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

Beyond the readOnlyHint annotation, the description adds valuable behavioral context: it flags devKitUrlMismatch in warnings when the Dev Kit doc URL diverges, and notes that Storybook entries are included 'when available'. This discloses conditional behavior and special warning flags, going well beyond 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 a single, dense sentence that is front-loaded with the core purpose ('Returns usage guidelines') and efficiently packs the list of returned content and a special warning behavior. Every clause adds value with no redundancy.

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

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

Given the tool returns a rich guide with multiple sections and the output schema exists, the description sufficiently sets expectations by naming the main sections and the warning flag. It does not over-explain return formats, relying on the 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?

Schema coverage for the single parameter is 100%, and the schema description already explains it with examples. The tool description adds no additional parameter-level detail, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool 'Returns usage guidelines for a component from Designers Italia website' and lists specific content (whenToUse, howToUse, accessibility, library status, Storybook entry). This specific verb+resource distinguishes it from siblings like bsi_get_component_markup or tokens_list_component_vars.

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

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

The description clearly implies when to use the tool (when you need usage guidelines for a component) by enumerating the returned sections. However, it does not explicitly mention alternatives or when not to use it, though the context is clear and no exclusions are 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?

The annotation readOnlyHint=true is complemented by rich behavioral details: the description explains that each component is a single entity with two possible implementations, and that bsi and devkit subobjects can be null. This goes beyond the mere read-only hint and discloses the inventory's structure and null semantics, which is valuable for an agent.

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 deliver a dense but clear description. Front-loaded with the main purpose, then details of output structure and null semantics, plus a usage directive. No wasted words; 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?

Despite no output schema, the description fully explains what the tool returns: one row per component, with specific keys and null behavior. Combined with usage guidance and clear scoping, it is complete for a list tool. The sibling context shows many related tools, but this description sufficiently distinguishes itself.

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 are zero parameters, so the baseline of 4 applies. The description adds relevant output semantics (rows, fields, nulls) but no parameter-specific information is needed. It appropriately explains the tool's behavior without parameter overhead.

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 'Lists' and clearly identifies the resource: 'all Design System .italia components as a single unified inventory'. It also details the output structure with bsi and devkit fields, distinguishing it from sibling tools like bsi_list_component_variants or devkit_list_component_variants by focusing on a unified component list rather than variants.

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

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

Explicit guidance is given: 'Call before fetching markup, tokens or props.' This sets clear context for when to use the tool. Additionally, it explains how to filter for BSI-only or DevKit-only components using null fields, providing practical usage direction. It does not explicitly name alternatives or exclusions, but the context is clear.

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 readOnlyHint=true, so the safe-read nature is already known. The description adds meaningful behavioral context: it searches the union of Bootstrap Italia and Dev Kit, returns rows shaped as bsi:{}|null/devkit:{}|null, and provides alias normalization examples. This goes beyond the minimal annotation coverage, though details like match semantics (substring vs exact) are not disclosed.

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

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

The description is three concise sentences with the action verb first, followed by scope, row-shape note, and examples. Every sentence earns its place and no filler or repetition exists.

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

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

For a simple single-parameter read-only search tool, the description is complete: it defines the search scope, the data source, the field types, and the output row shape via the reference to dsi_list_components. The absence of an output schema is mitigated by the row-shape hint, and no critical usage context is missing.

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

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

Schema coverage is 100% for the single 'query' parameter, but the description adds semantic depth by clarifying that the query can be a name, slug, Italian/English alias, or Dev Kit tag, plus concrete alias examples. This enriches the parameter meaning beyond the schema's simple 'Search text' label.

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

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

The description clearly identifies the tool as a search over the unified Design System component inventory, specifying searchable dimensions (name, slug, Italian/English alias, Dev Kit tag). It distinguishes itself from dsi_list_components by explicitly noting it returns the same unified rows but is a search operation, and the alias examples reinforce its purpose.

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

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

The description implies when to use this tool versus listing all components by referencing dsi_list_components as the source of the same rows. It does not explicitly list exclusions or compare to sibling search tools like tokens_search, but the context is clear enough for an agent to determine this is the component-search entry point.

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, which covers the read-only safety profile. The description adds useful behavioral context by enumerating the four repositories queried and mentioning the integration with components_status.json, revealing that the result is a blend of GitHub issues and pre-existing known issues.

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, well-structured sentence that leads with the main action and clearly lists the repositories and the supplementary data source. There is no redundant phrasing or unnecessary detail.

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 well-documented parameter and an output schema present, the description does not need to explain return values in depth. It provides the essential scope, the four repositories, and the inclusion of known issues, offering sufficient contextual completeness for an agent to select and invoke the tool correctly.

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

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

The single parameter 'component' is fully documented in the schema with examples, so schema coverage is 100%. The description only alludes to 'component' generically and does not add format or syntax details beyond what the schema already provides, so it adds minimal additional 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?

The description uses the specific verb 'Returns' and clearly identifies the resource: 'open GitHub issues for a component' across four named repositories. It also differentiates from sibling tools by focusing on issues, whereas siblings handle tokens, markup, variants, or component listings, none of which are issues.

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

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

The description clearly defines the scope: this tool retrieves open GitHub issues for a specified component from four specific repositories and also incorporates known issues from components_status.json. It does not explicitly name alternatives or state when not to use it, but the context is sufficiently clear given the focused toolset.

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 provide readOnlyHint=true, and the description adds context by specifying the data returned (open issue links) and what is not included (Projects v2 board cards). This adds behavioral clarity beyond the annotation without contradiction.

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

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

The description is only two sentences, with the primary purpose front-loaded and no unnecessary words. Each sentence adds distinct value.

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

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

With no parameters and an output schema, the description effectively covers the tool's scope and limitations. It's sufficient for an agent to select and invoke correctly.

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

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

The tool has zero parameters, so the baseline is 4. The description adds value by specifying the output scope, so no parameter explanation is needed.

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

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

The description clearly states the tool returns links to open issues for each Design System .italia repository, with a specific verb and resource. It also differentiates from sibling github_get_component_issues by explicitly naming the alternative.

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 names github_get_component_issues as the alternative for component-specific issues, providing clear usage guidance. It also discloses a limitation (excludes live Projects v2 board data), which helps set expectations.

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 description adds value by listing specific return fields (status, version, timestamp, source state warnings). This provides useful behavioral context beyond 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 a single concise sentence that efficiently communicates purpose and return information without unnecessary words.

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

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

Given the tool has no parameters, no output schema, and a simple health-check purpose, the description fully covers what the agent needs to know about purpose and output.

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?

No parameters exist, so schema coverage is 100% by default. The description does not need to add parameter info, but it correctly lists return fields, adding some semantic value.

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

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

The description uses a specific verb ('Checks') and specifies the resource ('connection to the MCP server'), clearly distinguishing it from sibling tools that deal with tokens, components, or boards.

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 usage for verifying connectivity, but does not explicitly state when to use this tool versus alternatives, nor does it provide any exclusions or prerequisites.

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 discloses important behavioral nuances: indirect impact via resolution chain, accepted token formats, and the fact that components reflect BSI's internal grouping keys rather than canonical names. This adds significant context and helps the agent set expectations.

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

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

The description is three well-structured sentences. The first states the primary purpose, the second explains input formats and typical use case, and the third provides a key caveat. It is information-dense without fluff, making it appropriately sized and 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?

Given that an output schema exists, the description does not need to detail return values. It covers the tool's scope, input variations, indirect impact, theming use case, and a subtle but important caveat about component naming. This is complete for the tool's complexity.

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 provides 100% coverage for the single parameter, so the description need not repeat basic syntax. However, it adds semantic value by explaining the distinction between direct usage (--bsi-*) and indirect impact traced through the chain (--it-*/$it-*), which is not clear from the schema alone.

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

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

The description clearly states the tool's function with a specific verb ('Returns the Bootstrap Italia components impacted by a given design variable') and distinguishes it from related tools like dsi_list_components by explaining the internal grouping key caveat. This exceeds basic clarity and explicitly differentiates from siblings.

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

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

The description provides clear usage context: it accepts different token forms and is 'useful for theming.' It also implicitly contrasts with dsi_list_components by warning about grouping key differences, offering guidance on when to use this tool. However, it does not explicitly name alternatives or state when not to use the tool, so it falls short of a perfect 5.

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

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

Annotations already declare readOnlyHint=true, but the description adds valuable behavioral context: it explains that --bsi- variables are safe to override at runtime and warns against overriding the central Design Tokens (--it-/$it-). It also clarifies the resolution chain and concrete value output, going beyond the read-only hint.

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, tightly written, with no fluff. It front-loads the core purpose (lists CSS custom properties) and then adds essential usage nuance. 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?

Given the tool's moderate complexity, an output schema exists, and the readOnly annotation is present, the description is adequately complete. It covers purpose, output details, and override safety. It does not discuss error cases or invalid component names, but these are not necessary for a list-style tool with a simple parameter.

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 one parameter with a description ('Component name or slug (e.g. "accordion", "Alert")') and schema_description_coverage is 100%. The description does not add any extra parameter-specific meaning beyond what the schema already provides, 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 ('Lists') with a precise resource ('CSS custom properties (--bsi-)... to customize a Bootstrap Italia component') and states the output fields (semantic description, resolvedVia, resolved value). This distinguishes it from sibling tools like tokens_list_globals (global tokens) and tokens_resolve (single token resolution).

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

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

The description clearly implies when to use this tool: when you need to customize a component via CSS overrides. It also provides crucial guidance that --bsi- variables are safe to override while --it-/$it- are not. However, it does not explicitly name alternative tools or state conditions when not to use it, though the context is 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 declare readOnlyHint=true, and the description is consistent. It adds behavioral context beyond annotations by explaining the output entry structure (paired central token, global --bsi-* property, resolved value), the filter semantics (substring, not semantic), and the scope limitation (only bridged tokens). No contradictions. This is valuable transparency for a read-only tool.

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

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

Three concise sentences: the first states purpose, the second explains output structure, and the third covers usage and alternatives. No unnecessary words. The description is front-loaded and every sentence earns its place.

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

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

The tool is simple (one optional param), no output schema, but the description adequately covers return entry structure, filtering behavior, scope, and sibling differentiation. It even notes the inclusion criteria. This is complete for the tool's complexity with minimal 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 input schema percent coverage is 100% and already fully documents the 'match' parameter semantics, including examples and the fact it is literal substring matching. The description adds little beyond what the schema provides—it only repeats the example usage. Baseline 3 is appropriate since the schema carries the documentation burden.

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 lists global design tokens used by Bootstrap Italia, with a specific verb and resource. It explicitly distinguishes itself from sibling tool tokens_list_component_vars by directing per-component variable lookups there. The scope is precise ('global design tokens... that Bootstrap Italia actually uses'), avoiding ambiguity.

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

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

Provides explicit usage instructions: 'Without arguments returns all global tokens; pass match to filter' with examples. It states the alternative tool for per-component variables and clarifies the inclusion rule ('Only tokens bridged into BSI are listed'). This gives clear when-to-use and when-not-to-use guidance.

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

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

The description reveals the resolution process (following the full chain to a literal) and explains the semantics of each hop's role and overridable flag. This adds significant behavioral context beyond the readOnlyHint annotation, which is consistent. It also clarifies the distinction between bsi and dti token roles, helping the agent understand output implications.

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 well-structured: the first sentence states the core function, the second explains the output semantics, and the example chain is concise and illustrative. Every sentence adds value without redundancy or padding.

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

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

The description covers the tool's behavior, interpretation of results, and actionable guidance for overriding tokens. With a single parameter, complete schema coverage, and an output schema present, the description is thorough and self-sufficient for an agent to use correctly.

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

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

The input schema already documents the parameter ('Token name in any form: --bsi-*, --it-*, or $it-*') with 100% coverage. The description reinforces this by showing an example but does not add new parameter-level meaning. Baseline of 3 is appropriate.

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

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

The description states exactly what the tool does: resolves --bsi-, --it-, or $it- variables to their concrete literal values. It is specific and distinct from sibling tools like tokens_search or tokens_list_component_vars, which search/list rather than resolve. The example chain clarifies the 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 provides clear context on how to use the resolved output—explaining which hops are safe to override and which are not—and instructs to override --bsi-* variables rather than $it-/--it- ones. It does not explicitly contrast with sibling tools, but the usage intent is clear enough for an agent to decide when to invoke it.

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

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

Beyond the readOnlyHint annotation, the description discloses substantial behavioral traits: the matching algorithm (substring), the fields searched (name, description, value), the value resolution difference between BSI (raw) and DTI (resolved), and a concrete failure example. This goes well beyond the annotation's safety signal.

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

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

The description is compact yet information-dense. Every sentence adds value: purpose, scope, matching behavior, examples, and a critical limitation. It is front-loaded with the core action and efficiently structured without redundancy.

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

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

For a simple one-parameter search tool with readOnlyHint, the description covers all necessary aspects: what is searched, how matching works, what values are searched, and a meaningful limitation. No output schema exists, but the description sufficiently conveys the tool's behavior and expected outcomes.

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

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

The single 'query' parameter is fully described in the schema, but the description adds rich semantics: examples of valid queries, noting that values are matched in both raw and resolved forms, and clarifying the substring-only constraint. This adds meaning beyond the schema's simple 'Search term' description.

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

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

The description clearly states the tool's action: searching for Design Tokens Italia or BSI tokens by substring match. It specifies the exact scope (BSI CSS custom properties and DTI global tokens) and provides examples, making it distinct from sibling tools like tokens_list_globals or tokens_resolve.

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

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

The description gives clear context for when to use the tool (to find tokens via substring matching) and explicitly notes a limitation (semantic phrases like 'primary color' will not work). However, it does not explicitly reference alternative sibling tools, so it misses the 'alternatives' aspect of a 5.

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