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

No annotations are provided, so the description carries the full burden. It usefully discloses that both L1 (memory) and L2 (disk) caches are wiped and implies a cost (cache rebuild), but says nothing about permissions required, whether the clear is reversible, or any latency impact.

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

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

A single sentence with the action and the operational trigger front-loaded; every clause earns its place.

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

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

For a zero-parameter, no-output-schema tool the description covers the essential action, scope, and motivation. Only the absence of any permission or side-effect detail for a state-mutating (cache-wiping) operation keeps it from being fully complete.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4.

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

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

States a specific verb (clear) and resource (compile caches), and even scopes it to both L1 memory and L2 disk. It does not explicitly name a sibling it differs from, but the resource is distinctive enough to separate it from the mapping/component tools in the sibling list.

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?

Gives a concrete trigger condition: 'use to force a refresh after the data source changes.' That is clear when-to-use guidance, though it offers no when-not-to-use or named alternatives.

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 entire behavioral burden. 'Check' and 'flag' weakly imply a read-only diagnostic, but the description never states that it is non-mutating, whether it repairs anything, what 'stale' means operationally, or how results are surfaced. For a filesystem-touching tool with zero annotation coverage, this leaves key behavior undefined.

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

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

A single front-loaded sentence that pairs the operation with its result, with no redundancy or filler. Nothing could be removed without losing information.

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

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

For a one-parameter diagnostic tool with no output schema and no annotations, the description covers the core operation but omits the shape of the result (list of stale entries? count?) and whether any remediation is offered. Adequate but with clear gaps given the absence of structured metadata.

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

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

There is a single parameter with 100% schema description coverage ('Absolute path to the project root'), so the schema fully documents it. The description adds no additional meaning about how projectRoot scopes the check, which is the expected baseline when the schema does the work.

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

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

States a specific verb ('Check'), a specific subject ('component files referenced by the mapping asset library'), and the outcome ('flag stale entries'). This is clearly a diagnostic tool distinguishable from mutation siblings like save_component or remember_mapping, though it never explicitly names or contrasts with them.

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?

No guidance on when to run this versus alternatives such as scan_components, export_mappings, or import_mappings, and no mention of prerequisites (e.g., that the mapping library must already be populated). The agent must infer the trigger condition from the purpose statement alone.

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 does add valuable cost/auth context ('In BYOK mode the token bills the user'), which is genuinely beyond the schema. But it never says whether compiling writes files to disk, mutates project state, or merely returns a mapping, which is the key behavioral unknown for a tool taking a projectRoot.

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

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

Three compact sentences with the core purpose front-loaded and no filler. Slightly more efficient than typical, though the third sentence about billing is a fragment that could be folded in.

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 an 8-parameter tool with no annotations and no output schema, the description should explain what the compile actually produces and whether it persists anything. It covers inputs and billing but leaves the return/persistence semantics unstated.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters including the mode and styleFormat defaults and the figmaUrl/figmaNode either-or rule. The description adds no syntax, format, or precedence detail beyond that, so baseline 3 applies.

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

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

States a specific verb ('Compile') and resource ('a Figma node') with the output shape named ('Tailwind + variant-mapping context'). It is clear on its own, but it never distinguishes itself from siblings like fetch_figma_node or save_component, which an agent must choose between.

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

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

It clarifies the two input paths ('offline figmaNode JSON or a figmaUrl (live Figma API)'), which is useful routing guidance. However it gives no when-to-use versus when-not-to-use advice relative to fetch_figma_node or save_component, leaving the sibling selection to inference.

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 full burden. It usefully discloses the produced artifact and its location, which is real behavioral value, but says nothing about whether it overwrites an existing file, what permissions it needs, or whether it touches anything beyond the local mappings file.

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

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

A single front-loaded sentence with the verb first and the qualifier last; nothing is wasted and the artifact path is surfaced immediately.

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

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

For a one-parameter, no-output-schema tool this is nearly sufficient: it names the artifact produced and the purpose. The only meaningful omission is overwrite/permission behavior, which an agent might want before running an export.

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?

Only one parameter exists and schema coverage is 100%, so the schema already fully documents projectRoot. The description adds no further meaning about the parameter, which is the expected baseline when the schema does the work.

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?

Specific verb 'Export' paired with a concrete resource and even the exact artifact path (.smart-figma/mappings.json), so the agent knows precisely what is produced. It reads as the inverse of the sibling import_mappings, though that relationship is implied rather than named.

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 parenthetical '(for team sharing or migration)' hints at the intent, which implies usage, but there is no explicit statement of when to pick this over import_mappings or whether any prerequisites exist. Adequate but leaves the routing decision to inference.

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 full behavioral burden. It usefully discloses the 'max 100 components per call' limit and the on-disk cache semantics, but says nothing about permissions, error behavior, or determinism of the returned contract, leaving meaningful 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?

Three compact sentences, front-loaded with what is returned, then why it matters, then the limit. The anti-hallucination rationale is slightly redundant with the 'machine-readable source of truth' clause but still 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 4-param read tool with no output schema and no annotations, the description covers both return modes (index with categories + import paths; props table with types, required flags, enum values) plus the batch limit and caching behavior. Only auth/permission context is missing, a minor gap given the local project-root nature of the tool.

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% (all four params documented, including `components`, `refresh`, and `includeManifest`), so the baseline is 3. The description restates the `components`-present/absent behavior already in the schema rather than adding format or syntax detail beyond it.

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

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

States a precise verb+resource ('Fetch the authoritative Astryx component contract as JSON') and enumerates the two return shapes: the component index or the per-component props table. It does not name the adjacent siblings (probe_astryx, scan_components) so an agent must infer how it differs from those, which keeps it short of a 5.

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

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

Gives a clear use context ('use the enum values to avoid inventing props... generated code contains no hallucinated variants') and an implied mode rule ('when `components` is given' vs omit for the index). It stops short of explicit when-not or named alternatives, so no 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?

With no annotations, the description carries the full burden, and it does disclose a meaningful trait: it calls the external Figma API and normalizes the result into compiler input, and it returns Auto Layout info. It does not mention auth requirements, error handling, or rate limits, so coverage is partial rather than complete.

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 short sentences with the core action front-loaded and the return content stated second; no filler. Marginal room to be tighter but effectively sized.

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 fetch tool with no output schema, the description does convey what comes back (structured node data with Auto Layout), which is the most important missing piece. It omits auth/env behavior and the file_meta branch effects, leaving it adequate but incomplete.

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 enum (node/file_meta), figmaUrl, and optional figmaToken are already documented in the schema. The description adds no parameter meaning beyond 'design node' loosely implying the node action, so the baseline 3 applies.

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

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

Specific verb (fetch) plus resource (design node) plus a transformation step (normalize into compiler input format), so the agent knows this is a read-and-convert operation. It does not, however, differentiate itself from likely-related siblings like compile_figma_component or scan_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 gives no when-to-use guidance, no prerequisites, and names no alternatives despite several plausibly adjacent siblings (compile_figma_component, scan_components). Context is only inferable from the name.

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 behavioral burden and does disclose the critical merge semantics: 'Existing keys are not overwritten.' That tells the agent this is a non-destructive additive import. It stops short of covering error behavior, whether the target file is created if missing, or how nested conflicts resolve.

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 short sentences, zero filler, with the action front-loaded and the key side-effect constraint in the second sentence. Every clause earns its place.

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

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

For a two-parameter file-import tool with no output schema and no annotations, the description covers the core action and overwrite policy but leaves gaps: no error semantics, no statement on whether the .smart-figma file is created or must pre-exist, and no explanation of nested-object merge behavior despite the data param being a nested object.

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 both parameters are already documented. The description adds only the loose mapping of 'external JSON' to the data parameter; it says nothing about the shape of the mappings array or the projectRoot path contract beyond what the schema 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?

States a specific verb and resource ('Import mapping assets from external JSON') plus the exact target file, so the agent knows precisely what happens. It does not explicitly distinguish itself from the sibling export_mappings, though the import direction is implicit.

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

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

Usage is only implied by the phrase 'from external JSON' – there is no explicit when-to-use, no mention of export_mappings as the counterpart that produces such JSON, and no prerequisites (e.g. project root must already contain a mappings file).

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 it does useful work: it discloses that the check reports CLI/core installation and version, and that it "degrades gracefully when Astryx is absent" rather than erroring. It does not state that it is read-only or whether it touches the filesystem/network, leaving a small gap for a probe 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?

Two sentences, zero waste, front-loaded with the purpose before the usage rule and the degradation caveat. 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?

There is no output schema, so the description should ideally characterize the return value; it partially does by naming what is checked (CLI + core installed, version) but does not specify the response shape (boolean vs. object). For a one-parameter probe tool, this is nearly 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% and the single projectRoot parameter is fully documented as an absolute path, so the schema does the heavy lifting. The description adds no syntax, path-format, or default information beyond it, making the baseline 3 appropriate.

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

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

States a specific verb (check availability) and resource (Astryx design-system contract), plus the precise criteria it verifies: CLI + core installed, version. This clearly separates it from fetch_astryx_contract, which retrieves the contract rather than probing for it.

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

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

"Use this before fetch_astryx_contract" gives an explicit sequencing rule tied to a named sibling, which is strong routing guidance. It stops short of stating when not to call it (e.g., if the contract is already known to be present), so it is clear context without 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, the description carries the full burden, and it does disclose the two most important traits: a network fetch from a remote URL and a local filesystem write to .smart-figma/crl.json. It does not cover auth requirements, overwrite semantics for an existing cache file, or failure behavior when the URL is unreachable.

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, zero waste, front-loaded with the action and resource, then the source and cache destination. Nothing to trim and nothing buried.

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

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

For a single-optional-parameter tool with no output schema, the description covers what it does, where it fetches from, and where it writes. Only peripheral details (permissions, failure modes, whether it returns the CRL contents) are absent, which is minor at this 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?

Schema coverage is 100% and the single parameter already documents the URL and its CRL_URL env-var default, so the schema does the heavy lifting. The description's phrase 'from a remote URL' merely restates the parameter without adding syntax, format, or validation detail beyond it.

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

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

States a specific verb (refresh) plus the resource (license revocation list / CRL) and even the mechanism and destination (remote URL → local cache at .smart-figma/crl.json). It does not differentiate from any sibling, though none of the listed siblings overlap in function, so the ambiguity risk is low.

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

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

Usage is only implied by the verb 'refresh' — an agent can infer you call this when the local CRL is stale or missing, but the description states no explicit trigger, no prerequisites (network access, env var configuration), and names no alternatives. Adequate but with clear gaps.

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 behavioral burden and mostly fails it. It does not say whether writes are idempotent, whether an existing mapping is overwritten, what storage location or permissions apply, or what the response contains; 'private asset' is the only behavioral detail offered.

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?

It is a single front-loaded sentence, which is efficient, but the closing 'forming a switching-cost moat' clause is marketing filler that consumes space without helping invocation. The core statement is tight; the tail is waste.

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 mutation tool with no annotations, no output schema, and a nested object parameter at 0% coverage, the description leaves critical gaps. It states the intent but omits preconditions, overwrite semantics, storage details, and the shape of the nested target, which the schema does not supply either.

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

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

Schema description coverage is 0% across four parameters, including a nested, untyped 'target' object. The description adds no information about any parameter's format, expected structure, or the relationship between figmaComponentKey, figmaName, and target, so an agent cannot construct a valid 'target' payload.

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 sentence names a specific verb and resource: persisting a Figma->local-component mapping. The scope ('user-confirmed', 'private asset') helps separate it from siblings like save_component or import_mappings, though the trailing 'switching-cost moat' clause is business framing rather than functional description.

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?

'User-confirmed' hints at a precondition, but there is no explicit when-to-use guidance, no statement of alternatives such as save_component or import_mappings, and no indication of when this should be avoided. The agent must infer the workflow position entirely.

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 it does disclose genuinely useful behavior: the operation is deterministic, mutates the code by stripping data-node-id, and has a side effect on the index.ts barrel. It stops short of stating whether an existing file is overwritten, how the path is resolved from projectRoot/featureDir/componentName, or what happens on failure.

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

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

A single front-loaded sentence that leads with the operation type and then enumerates the three effects, with no filler. It is efficient, though the terse style contributes to the gaps in parameter and usage 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?

For a mutation tool with zero annotations, no output schema, and 0% parameter coverage, the description is too thin. It never explains path resolution, overwrite semantics, or the expected response, which an agent needs before performing a deterministic write that also edits a barrel file.

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

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

Schema description coverage is 0% and none of the four parameters (code, componentName, projectRoot, featureDir) is explained in the description. The phrase 'the exact path' hints that a path is derived but does not say from which parameters or in what combination, so the description fails to compensate for the coverage gap.

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

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

The description states a concrete write action with three specific behaviors: stripping data-node-id, writing to an exact path, and updating the index.ts barrel. An agent can tell this is the persistence step for a component file. It does not, however, name or contrast itself with any sibling (e.g., compile_figma_component or scan_components), so differentiation is left to inference.

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

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

There is no explicit when-to-use guidance, no prerequisites (does the component need to be compiled first?), and no mention of alternatives among the many siblings. The reader must infer from the name alone that this is the terminal save step in a component-generation pipeline.

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 supplied, so the description carries the full burden. It usefully discloses the extraction targets (names, CVA variants, import paths) and is implicitly read-only, but says nothing about side effects, caching (notable given the sibling cache_clear), performance on large projects, or failure behavior.

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

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

A single front-loaded sentence with no filler; the verb, scope, and extraction outputs are all delivered economically.

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

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

With no output schema, the description compensates by enumerating the data returned (component names, variant definitions, import paths). For a one-parameter read-style tool with no annotations this is nearly complete, missing only side-effect and prerequisite context.

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?

Only one parameter (projectRoot) with 100% schema description coverage, so the schema already documents it fully. The description adds no format or constraint details beyond what the schema provides; baseline 3 applies.

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

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

States a specific verb ('scan') and resource ('the project's local component library'), and enumerates what it extracts (component names, CVA variant definitions, import paths). It is easy to distinguish from a save/compile tool, though it never names the relevant siblings (e.g. save_component) to sharpen the boundary.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no stated prerequisites, such as whether this must run before save_component or compile_figma_component. Usage is only implied by the phrase 'auto-scan the project's local component library'.

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