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

With no annotations provided, the description carries the full burden. It discloses a key behavioral trait: the tool refuses composition if a component is not in DS meta, and it indicates the output format (snippet with merged imports). However, it does not disclose other important details like return type, error handling, or whether the operation has side effects, leaving some transparency gaps.

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 primary action and includes a relevant constraint. Every word contributes meaningful information; there is 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?

Given the medium complexity (one parameter with nested objects), no annotations, and no output schema, the description provides the core purpose and one constraint but lacks specifics about the exact output format beyond 'snippet', error behavior, or usage examples. It is adequate for basic selection and invocation but leaves room for ambiguity in edge cases.

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% per the input schema, so the baseline is 3. The description adds minimal value beyond the schema—it only paraphrases 'multiple components' without explaining the structure or providing additional semantic context that the schema already lacks.

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 action ('Compose'), the resource ('multiple DS components'), and the output ('a single snippet with a merged import block'). It also adds a specific constraint ('Refuses composition if any component is not in DS meta'), which distinguishes it from sibling tools like get_component or list_components.

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

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

The description implies usage (use when you need to combine multiple components into one snippet), but it does not explicitly mention alternatives or when not to use it. No comparison with sibling tools is provided, leaving the agent to infer the scope from the word 'multiple'.

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?

No annotations are provided, so the description carries the burden. It implies a read-only lookup by describing the content as examples/patterns, but does not explicitly state that it has no side effects or that it is safe. It adds context like 'Canonical' and 'Brand-neutral', but behavioral traits are minimal.

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 extremely concise, with only two short phrases that each communicate meaningful information: what the tool provides and the brand-neutral attribute. It is front-loaded and has no 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 tool with one optional parameter and full schema coverage, the description is minimally adequate. However, it does not explain what 'usage' entails or the return format, and there are no annotations or output schema. It is complete enough for a trivial case but leaves some 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 schema covers the single parameter fully (100% coverage) with an enum and default behavior described. The description adds no parameter information, so it neither contributes nor detracts. 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 indicates the resource (canonical DS animation patterns) and adds scope ('CSS keyframes + usage', 'Brand-neutral'). While it lacks an explicit verb, the tool name 'get_animation_examples' supplies the action. It is fairly distinguishable from sibling tools like get_design_tokens or get_theme_presets, though it doesn't explicitly differentiate.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention any context, prerequisites, or exclusions, leaving the agent without usage direction.

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

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

With no annotations, the description carries the full burden. It discloses one important behavioral constraint: 'Rejects JSX-unsafe prop values'. However, it does not explain error behavior, output format beyond the snippet, or any side effects, leaving the agent with limited insight for a code-generation 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 entire description is a single, front-loaded sentence that states the action and output immediately. It earned its place by including both the primary function and a key rejection behavior, with no filler or redundancy.

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

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

For a tool with 3 params and no output schema, the description is sufficiently complete: it specifies the return shape (JSX snippet with import and element) and the main constraint. It does not need to enumerate the component list, as that's in the schema. Slightly more detail on return formatting or error handling would push it to 5, but it's 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?

The schema already provides 100% parameter descriptions, so the baseline is 3. The description adds minimal parameter semantics beyond mentioning 'props/children' and the unsafe-value rejection, which is more behavioral than semantic. It does not clarify parameter formats or relationships beyond the schema.

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

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

The description opens with a specific verb, 'Generate', and a precise resource, 'a JSX snippet (import + element) for a DS component'. It clearly distinguishes the tool from siblings like get_component_props or get_component_reference by focusing on code generation.

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 a JSX snippet for a component, but it does not explicitly state when to use this tool versus alternatives like compose_components or get_component_reference. No exclusions or alternative tools are mentioned.

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

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

With no annotations, the description carries the burden and discloses important behavioral traits: the default returns the full matrix, filters narrow the matrix, and 'component' returns a single entry. It does not describe the output shape but conveys the operational semantics well.

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

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

One sentence delivers the purpose, default behavior, and parameter usage without any redundant words. It is front-loaded with the core concept and efficiently structured.

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

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

Covers the key invocation patterns (default, filters, single component) in a compact form. It lacks explicit output format details, but given the absence of an output schema and the tool's self-descriptive nature, it is sufficiently complete 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 description explains that booleans serve as filters and component is for a single entry, adding meaning beyond the sparse schema (only component has a description). It doesn't detail each boolean's interpretation, but the names are self-explanatory and the filtering role is clear.

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 'DS capability introspection' and explains it returns a full matrix by default with optional filters for single components. It differentiates from siblings like get_component by focusing on capability flags (rscSafe, clientOnly, etc.) rather than component details or 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?

It provides clear usage context: use for a full matrix of capabilities, or narrow by passing filter flags or a single component. Although it doesn't explicitly name alternatives or exclusions, the behavior is well-specified with the 'or' distinction for component vs. filters.

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

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

The description adds context by noting the data is 'derived from meta.components[X].props', which gives insight into the source. With no annotations provided, it also implicitly conveys a read-only operation by using 'Return'. However, it does not detail the exact return format, possible errors, or behavior on invalid component names.

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, front-loaded sentence that immediately specifies the action and resource. It contains zero filler and is appropriately sized for a simple 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?

For a simple one-parameter getter with a fully specified enum, the description is sufficient: it states what is returned and the source. The only missing detail is the exact return representation ('TypeScript-interface view' remains slightly ambiguous), but the tool's simplicity keeps this from being a major gap.

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

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

Schema coverage for the single parameter is 100%, including an enum and description for 'componentName' (PascalCase). The tool description adds no additional parameter 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 clearly states a specific verb ('Return') and resource ('a component's props'), describing the output as a 'TypeScript-interface view'. It differentiates itself from siblings like get_component and get_component_capabilities by focusing specifically on the props interface.

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

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

Usage is implied: use this to obtain a component's props as a TypeScript interface. However, there is no explicit statement about when it should be used over sibling tools (e.g., get_component_reference) or any exclusions.

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

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

With no annotations provided, the description carries the full burden for behavioral disclosure. It conveys that the response includes multiple sections and that theming class-name maps are optional via the include parameter. However, it does not describe response structure, error conditions, or potential payload size, leaving notable gaps for an unannotated 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 exceptionally concise, consisting of two sentences that directly convey the tool's function and legacy context. Every word earns its place, with no 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 lists the response contents and the schema provides valid parameter values, making it sufficiently complete for selecting and invoking the tool. It lacks explicit comparison to current sibling tools, but the purpose and capabilities are clearly communicated, so it remains effective.

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

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

Schema description coverage is 100%, with both parameters already detailed including default include sections and PascalCase component names. The description itself adds only generic tool-level information and no additional parameter-specific semantics, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns a full component reference with enumerated sections (description, examples, composition hints, props, theming maps). It uses the specific phrase 'Full component reference in one call' and explicitly distinguishes itself as replacing older v2.x tools, clarifying its consolidated role.

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 as a replacement for get_component_docs and get_usage_example, signaling it is the unified way to fetch comprehensive component info. However, it does not explicitly contrast with current sibling tools like get_component_props or get_composition_hints, leaving some ambiguity about when to choose a more granular 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?

With no annotations, the description carries the full burden. It discloses that the data is sourced from 'meta.verbose.composes' and only covers 'documented props,' which is useful context. However, it does not describe return format, error behavior for invalid component names, or whether the data is always available for every component.

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 sentence with a clear, front-loaded purpose followed by a source note. Every word 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.

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

For a simple read tool with one parameter and no output schema, the description adequately explains the return concept ('for each documented prop, which component (or shape) it expects'). It could be slightly more explicit about the exact output structure, but overall it is complete enough 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 schema already provides complete coverage of the single parameter (componentName) with a clear description and enum. The tool description does not add additional meaning about the parameter beyond what the schema states, 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 that it provides 'DS-authoritative composition hints for a component' and specifies exactly what it returns: 'for each documented prop, which component (or shape) it expects.' This distinguishes it from sibling tools like get_component_props (prop types) or compose_components (actual composition).

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 composition hints are needed, but it does not explicitly state when to use this tool over alternatives or provide exclusion criteria. There is no mention of when not to use it or which sibling tool might be a better fit for other scenarios.

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?

With no annotations, the description carries the full burden. It explains meaningful behavioral details: the 'css' format returns CSS variable references that resolve to OKLCH at runtime, 'hex' returns sRGB hex from meta, and 'both' returns both. It also notes the default behavior. This goes beyond a simple getter and provides useful operational context.

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

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

The description is extremely concise, using two short sentences to convey the resource scope and format options. There is no fluff or repetition; every phrase adds information. The structure front-loads the core purpose before detailing format specifics.

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 a single optional parameter and no output schema, the description adequately covers the key aspects: what tokens are included and the format options. It could be slightly more complete by explicitly stating that it returns all tokens or describing the overall return shape, but for a simple retrieval tool it is sufficient.

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

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

The schema already describes the 'format' parameter with an enum and a generic description, but the tool description adds significant semantic value by explaining what each enum value actually means (css vars vs hex values). This goes beyond the baseline schema coverage and helps the agent choose the correct format.

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 retrieving DS design tokens covering colors, spacing, typography, radius, shadows, and motion. It distinguishes itself from sibling tools by focusing on tokens rather than components, icons, or hooks. However, it lacks an explicit verb like 'get' or 'retrieve', relying on the tool name to convey the action.

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

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

The description does not state when to use this tool instead of alternatives such as get_theme_presets or get_ds_metadata. Usage is only implied by the resource name 'design tokens', with no explicit conditions, exclusions, or comparisons to sibling tools.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior. It clearly lists what the tool returns, which gives an accurate picture of its read-only nature and output contents. It does not explicitly state 'read-only' or 'no side effects', but the nature of a metadata getter and the explicit output list provide sufficient transparency for a zero-parameter 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 two sentences, front-loaded with the key idea ('One-call'). It efficiently lists the content and use cases without any redundant or extraneous wording. Every word earns its place.

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

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

Given the tool's simplicity (no parameters, no output schema) and the lack of annotations, the description is nearly complete. It explains the returned data and typical use cases. It could be slightly more explicit about the format of the exports map or whether any schema details are included, but for a self-orientation tool, this is adequately complete.

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

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

The tool has zero parameters, so the baseline is 4. There is no input schema to clarify, and the description does not need to add parameter semantics. The focus is entirely on the output, which is well described.

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 what the tool does: it returns metadata about the design system package, including version, schema version, component/capability/icon/hook counts, and exports map. The phrase 'One-call what am I talking to' gives a succinct purpose, and the content list distinguishes it from sibling tools that focus on specific components, icons, or hooks.

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 mentions two use cases: CI version guards and self-orientation. This provides clear context for when to use the tool. However, it does not explicitly state when not to use it or name alternative tools, so it falls short of the highest bar.

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?

With no annotations, the description carries the full burden and does well to enumerate the output structure, clarifying that this is a read-only lookup and what data will be returned. However, it omits behavior for invalid hook names or potential error responses, which is a minor gap.

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

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

The description is a single sentence using a dash-separated list to pack all relevant details in a front-loaded, efficient manner without any fluff.

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

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

For a simple read-only tool with one parameter and no output schema, the description covers the essential information by listing exactly what will be returned. It could mention error cases or relationship to other hook-related tools, but overall it is adequately complete.

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

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

Schema coverage is 100% with a descriptive enum and example for the only parameter. The description adds no additional parameter semantics beyond what the schema already provides, keeping the baseline at 3.

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

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

The description clearly states the tool's function: retrieving full details for a DS utility hook. It specifies the exact contents (signature, returns, category, RSC safety, subpath, description, import snippet), distinguishing it from sibling tools like get_component and list_hooks.

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 use when complete hook information is needed, but it does not explicitly differentiate from alternatives like list_hooks for exploring available hooks or get_component for component details. No exclusions or when-not-to-use scenarios are provided.

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 discloses the behavioral change (no default, presets must be chosen) and the version context, which is useful. However, with no annotations provided, the description carries the full burden and could clarify what exactly is returned (e.g., a list of preset identifiers or objects), but it stops short.

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 main purpose ('Available DS theme presets'), and the second sentence adds valuable context without redundancy. No wasted 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?

For a zero-parameter tool with no output schema, the description adequately conveys that it returns available theme presets and explains the broader context of brand-neutralization. It could be more explicit about the output format, but given the simplicity, it is reasonably complete.

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

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

The tool has zero parameters, and the schema coverage is 100% (vacuously). According to baseline guidance, 0 params earns a 4. The description adds no parameter details, but none are 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 'Available DS theme presets' clearly indicates the tool returns a list of theme presets, and the 'get' prefix reinforces the retrieval action. It is not a tautology and distinguishes from siblings like get_design_tokens by focusing on theme presets specifically.

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 context that after v0.34, there is no baked brand default, so users must pick a preset or apply their own ramps. This implies when to use the tool (to discover available presets) and gives an alternative (custom ramps), though it does not name specific sibling tools.

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

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

With no annotations, the description carries the transparency burden. 'Meta-backed since v3.0.0' adds some context about data source, but it doesn't disclose return format, pagination, ordering, or any side effects. 'List' implies a read-only operation, but this is not explicit.

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 extremely concise, consisting of two short sentences. It front-loads the purpose and includes only essential details like filters and version metadata, with no wasted 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?

For a simple listing tool with optional filters, the description is adequate but lacks explicit mention of what the response contains or any pagination/limit behavior. Since there is no output schema, this leaves some ambiguity for the agent.

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 with clear descriptions for all five parameters. The description only re-lists the parameter names, adding no extra semantic value beyond what the schema already states.

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 'List DS components' with explicit optional filters, using a specific verb and resource. It distinguishes from sibling tools like get_component by focusing on listing rather than retrieving a specific component.

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

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

The description clearly implies usage for browsing/filtering components, and the mention of optional filters provides context. However, it doesn't explicitly state when not to use it or compare with alternatives like get_component or get_component_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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It adds a version note ('Meta-backed since v3.3.0') and implies a read operation via 'List', but does not detail return format, side effects, or limitations. This is adequate but not rich.

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

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

The description is two concise sentences, front-loaded with the main action. The version note is ancillary but not wasteful; every sentence carries meaningful information without 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?

For a simple list tool with two optional parameters and no output schema, the description covers purpose, filters, and version context. It does not specify return fields, but for a straightforward listing operation this is a minor gap, not a major incompleteness.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description only repeats the parameter names ('category, serverSafe') without adding semantics beyond the schema, so it does not elevate the baseline.

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 ('List') and resource ('DS utility hooks'), and differentiates from sibling tools like list_components and list_icons by focusing on hooks. It also mentions the optional filters, giving a clear, precise purpose.

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

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

The description provides clear context: use this tool to list utility hooks with optional filters. It does not explicitly mention alternatives or exclusions, but the intended use case is evident from the resource and filter hints.

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?

With no annotations, the description carries the transparency burden and reveals important behavioral traits: 'ds-brand' maps to ~70 authoritative icons, 'lucide' has ~1,500 with only ~80 having hand-authored metadata, and 'all' unions both. This helps set expectations about data richness, though it doesn't cover pagination or result ordering.

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 concise and well-structured: a lead sentence, then a terse breakdown of each source value. Every sentence adds value, and the use of backticks for parameter values improves readability.

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

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

For a list tool with four optional parameters, the description covers the key differentiator (sources) and acknowledges metadata limitations. However, it could be more complete by mentioning the return format or explicitly referencing search_icons for filtered lookups, which would aid selection between sibling tools.

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

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

Schema coverage is 100%, so a baseline of 3 applies. The description adds significant meaning to the `source` parameter by explaining the enum values, including exact counts and the metadata caveat for lucide. It goes beyond the schema's terse 'Icon source' 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 function ('List available icons') and provides specific details about the three source options, distinguishing it from sibling tools like search_icons and list_components. The scope (sources and counts) is unambiguous.

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

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

The description gives clear context on when to use each source variant (ds-brand, lucide, all), but does not explicitly contrast with the sibling search_icons tool. It implies usage through source semantics but lacks an explicit 'when to use this vs search_icons' note.

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?

With no annotations, the description carries the burden of behavioral disclosure. It does disclose ranking behavior (metadata-annotated icons rank higher, name similarity for bare Lucide names), which is useful. However, it omits other behavioral aspects like return format, pagination, or error handling, so it's decent but not rich.

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

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

The description is two sentences, tightly packed with relevant information and zero filler. It front-loads the core purpose before adding scope and ranking details.

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

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

For a search tool with four parameters and no output schema, the description provides enough to understand what it does but lacks deeper context such as result ordering, empty-result behavior, or specific exclusions. It does mention ranking, which is helpful, but could be more complete for a no-annotation environment.

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 all four parameters (query, limit, source, category) already have detailed descriptions. The tool description adds no parameter-specific meaning beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description clearly states a specific verb and resource: 'Semantic icon search by purpose.' It also defines the scope (DS-brand + Lucide catalog), which distinguishes it from a simple listing tool like list_icons, though it does not explicitly name the sibling.

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

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

The description provides no guidance on when to use search_icons versus alternatives such as list_icons. It implies a use case (searching by purpose) but does not state explicit conditions, exclusions, or comparisons to sibling tools.

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