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

With no annotations, the description must disclose behavior. It implies a read-only operation ('displays a table'), but does not explicitly state safety, auth needs, or side effects. While not misleading, it lacks full transparency expected for a tool without 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 a single, front-loaded sentence with no wasted words. It efficiently conveys the tool's output and purpose.

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 explains the output format (table with status indicators) in general terms, which is sufficient for an agent. However, it could be more specific about what the status indicators represent. Given no output schema, this is acceptable.

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 'pathPrefix' is fully described in the schema (100% coverage). The description does not add meaning beyond the schema, so 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 the tool's purpose: showing a semantic token coverage matrix across UX contexts and property classes, identifying gaps. The verb 'Show' and specific resource 'semantic token coverage matrix' make it distinct from sibling tools like analyze_topology or audit_semantics.

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 its many siblings, such as analyze_topology or validate_tokens. There is no mention of prerequisites or exclusions, leaving the agent without context for selection.

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

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

No annotations are provided, so the description must convey behavioral traits. It describes read-like analysis and suggestions, but does not explicitly confirm no side effects, required permissions, or output format. The description is adequate but not explicit about safety.

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. Every sentence adds value without redundancy or wasted text.

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 function but omits details about return values (no output schema). Given the complexity and nested objects, information about output format or error conditions would improve completeness.

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 parameters adequately. The description adds context about the analysis purpose but does not significantly enhance understanding of individual parameters 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 clearly states the verb 'Analyze' and the specific resource 'existing design token scales (spacing, typography, etc.)'. It distinguishes itself from siblings like 'validate_tokens' or 'suggest_scale' by focusing on pattern detection and improvement suggestions.

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 analyzing token scales but does not explicitly state when to use this tool versus alternatives like 'suggest_scale' or 'validate_tokens'. No when-not-to-use or exclusions are mentioned.

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

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

With no annotations, description fully bears transparency burden. It discloses outputs (graph, charts, matrix) and analyses performed, indicating a read-only analysis tool. However, it does not explicitly state that no mutations occur or mention performance impacts.

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 efficiently convey purpose and outputs. Front-loaded with key action and resource. Could be slightly more concise, but no superfluous 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 complex tool with 6 parameters and no output schema, the description covers high-level outputs (graph, charts, matrix) but lacks details on return structure of each analysis component.

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 baseline is 3. The description does not add additional meaning beyond the schema for parameters; it only describes the overall output.

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 purpose: analyze token topology with dependency graph, anti-pattern detection, and structure analysis. It differentiates from siblings by specifying unique outputs like dependency graph and anti-patterns.

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 topological analysis but does not explicitly state when to use this tool over siblings like analyze_coverage or audit_semantics. No exclusions or alternative guidance 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?

Without annotations, the description carries the full burden of behavioral transparency. It discloses the output: 'get back which components are in the system, which colors match existing tokens (using perceptual color distance), and what gaps exist.' This adequately informs the agent about the tool's behavior, though it does not mention nondestructive nature or potential performance characteristics.

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 tool's action and output, followed by a use case. Every sentence adds value without redundancy 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?

Given the tool has no output schema and only three string parameters, the description sufficiently covers the return values: which components are in the system, matching colors, and gaps. It is complete enough for an agent to understand what to expect, though it lacks specific formatting details of the 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?

Schema description coverage is 100%, so each parameter is already documented in the input schema. The description does not add new meaning beyond the schema; it merely repeats 'components you see' and 'colors used.' The baseline of 3 is appropriate as the description provides no additional parameter context.

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 purpose: 'Analyze UI elements and colors against the design system.' It specifies inputs (components and colors) and outputs (which match tokens, gaps). This distinguishes it from siblings like analyze_coverage or check_contrast, which serve different analysis functions.

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: 'Useful for reverse-engineering a screenshot or mockup into system terms.' It implies when to use this tool (when analyzing UI elements against a design system) but does not explicitly exclude cases or reference sibling alternatives. Still, the context is sufficient for an agent to decide.

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 full burden but only states it performs an audit and returns a gap analysis. It does not disclose whether the tool is read-only, any side effects, authentication needs, or rate limits. This is insufficient for full transparency.

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: first describes the action and outputs, second gives usage guidance. No wasted words, efficiently conveys purpose and context.

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 explains what the tool does and the outputs, but does not describe the return format or provide examples. For a tool with 3 parameters and no output schema, the description is adequate but could be more complete regarding the response structure.

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 descriptions already cover all three parameters (components, description, checkAccessibility). The description paraphrases the schema ('provide the components used') but adds no new semantic information beyond what the schema provides. Baseline 3 is appropriate given 100% schema coverage.

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

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

The description clearly states the verb 'audit' and the resource 'design', and specifies the outputs: missing tokens, naming issues, accessibility problems, and concrete fixes. It distinguishes itself from sibling audit tools by focusing on component-level design system compliance for handoff.

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 advises using this tool 'before handoff to ensure design-system coverage,' providing clear context. However, it does not explicitly mention when not to use it or compare it to sibling tools like audit_semantics or audit_scale_compliance.

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 must fully disclose behavioral traits. It states it 'analyzes sync status' and 'identifies' issues, implying a read-only operation, but it does not confirm whether any data is modified, what side effects exist, or what the output format is. The dependency on another tool is noted, but there is no mention of performance, rate limits, or expected response structure.

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 plus a note, all front-loaded with the primary purpose. Every sentence adds information: first defines the core function, second details what it analyzes, third states a critical prerequisite. 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?

The tool is moderately complex (auditing multiple aspects) and has no output schema. The description does not describe what the tool returns (e.g., a report, list of discrepancies, success/failure). This is a notable gap for a tool that likely produces structured results. The prerequisite and coverage of parameters are good, but missing output details reduce completeness.

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 3 parameters. The description adds value beyond the schema by noting that figmaVariableDefs must come from mcp_figma_get_variable_defs and expects a specific key-value format. This helps the agent prepare the correct input. The description does not fully explain figmaNodeId or figmaFileUrl, but the schema itself 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 states the verb 'audit' and 'cross-reference' with specific resources: Figma variables and local design tokens. It distinguishes this tool from siblings like 'validate_tokens' or 'audit_design' by focusing on sync between Figma and local tokens.

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 specifies a prerequisite: 'Requires Figma variable data from mcp_figma_get_variable_defs.' It also outlines what the tool identifies (unused tokens, missing definitions, naming discrepancies), giving clear context. However, it does not mention when to avoid this tool or provide explicit alternatives among the many 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. It discloses the standards and specific checks (44px touch targets, 1.5 line height, etc.) but does not state whether the tool is read-only, modifies tokens, or has side effects. Since it is an audit, read-only is implied but 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?

A single, well-structured sentence that front-loads the core purpose and immediately lists the standards. Every word 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?

The description covers the tool's purpose and standards but omits any mention of output or return value. Since no output schema exists, the description should hint at what the audit produces (e.g., recommendations, pass/fail). Without this, the agent may not know what to expect.

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 all parameters described. The description adds value beyond the schema by explaining the specific compliance checks (e.g., 44px touch targets) and the meaning of the 'standard' parameter via examples. This helps the agent understand parameter semantics 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 clearly states it audits design token scales against accessibility and platform standards, listing WCAG 2.2, Material Design, and iOS HIG with specific thresholds. This distinguishes it from siblings like 'validate_tokens' and 'audit_semantics' which have different scopes.

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 the tool is for checking token scale compliance but does not explicitly state when to use it versus alternatives, nor does it provide when-not guidance. Sibling tools like 'validate_tokens' might be more appropriate for general validation, but no comparison is made.

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 present, so the description carries the full burden. It states the tool analyzes and suggests migrations but does not clarify if the tool modifies tokens (destructive side effects) or is read-only. It also omits permissions, rate limits, or performance characteristics, making behavior partially opaque.

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 convey the purpose, scope, and output without any wasted words. The description is front-loaded with the action and resource, then elaborates on capabilities.

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 complexity of auditing multiple aspects of semantics, the description covers the main domains and output format. However, it lacks context on whether the tool is read-only, how to interpret the health score, and prerequisites (e.g., must have pre-defined tokens). No output schema exists to supplement return values, so the description could be more thorough.

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?

Both parameters ('skipRules' and 'pathPrefix') are fully described in the input schema. The description adds no additional semantic value beyond what the schema provides, meeting the baseline of 3 for high schema coverage.

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

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

The description uses a specific verb ('audit') and resource ('semantic token set'), listing concrete analysis areas (naming compliance, property-class separation, etc.) and output (health score and report). This clearly distinguishes it from siblings like 'validate_tokens' (syntactic validation) and 'analyze_coverage' (coverage gaps only).

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 the tool is for comprehensive semantic audits but does not explicitly state when to use it over alternatives like 'validate_tokens' or 'audit_design'. No exclusions or when-not-to-use guidance is provided, leaving the agent to infer context from the sibling names 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 does the heavy lifting. It reveals that the tool can operate on single pairs or scan tokens, uses multiple algorithms, and that threshold only affects scan mode. It does not describe return format, error handling, or performance, but the core behavior is transparent and consistent with expected contrast checking.

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, immediately conveying the purpose and modes. No unnecessary words. Information density is high 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 5 parameters, no output schema, and no annotations, the description covers the essential modes and parameters. It might lack details on return values or error cases, but for a straightforward check tool, it is adequate for an agent to decide 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?

Schema coverage is 100%, providing baseline 3. The description adds semantic value by explaining the two interaction modes: background+foreground for a single check vs. threshold+pathPrefix for scanning. It also clarifies that 'threshold' only applies to scan mode. This exceeds the schema's basic existence descriptions.

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 the tool checks color contrast using WCAG 2.1 and APCA algorithms. It outlines two distinct modes (single pair or token scan), which differentiates it from sibling tools that handle tokens, themes, or audits. The verb 'check' and resource 'contrast' are specific and unambiguous.

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

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

The description provides clear context on when to use the tool (checking contrast) and explains the two modes. It does not explicitly state when NOT to use it or list alternatives, but since no sibling tool performs contrast checking, the guidance is sufficient. The scan mode usage is partially implied via parameter 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 full burden. It mentions applying scale factors while respecting WCAG minimum touch targets (44px) and outputting conditional tokens, which provides moderate transparency. However, it does not explicitly state whether the tool is read-only or if it modifies input tokens, leaving some ambiguity.

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 concise sentences with no wasted words. The first sentence states the core function, and the second adds key behavioral details. Front-loaded and efficient.

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 6 parameters including nested objects and no output schema, the description is somewhat sparse. It does not explain the structure of 'conditional tokens' or the scale factors applied. Sibling tools like transform_tokens may cover similar ground, but for this tool's complexity, additional detail would be helpful.

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 parameters are well-documented in the schema. The description adds value by mentioning WCAG constraints aligning with minTouchTarget, but does not elaborate on other parameters beyond what the schema provides. 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 the tool's purpose: deriving a new density mode (compact/spacious) from existing tokens. It specifies the verb 'derive', the resource 'density mode', and distinguishes from sibling tools like transform_tokens by focusing specifically on density conversion with WCAG constraints.

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 context (when you have tokens and need a different density) but lacks explicit guidance on when not to use this tool or alternatives. No prerequisites or exclusions are mentioned, leaving the agent to infer applicability.

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 must convey behavioral traits. It describes an explanatory function but does not explicitly state it is read-only, non-destructive, or has no side effects. Given the tool's nature, this is acceptable but 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?

Two sentences, front-loaded with the main purpose. Every word contributes meaning. No fluff or repetition.

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 zero parameters and no output schema, the description adequately explains the tool's purpose. However, it could specify the output format (e.g., returns a textual explanation) to be 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 has zero parameters and schema coverage is 100% (trivially). Per rules, baseline is 4. The description does not add parameter-level info, but none 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 explains the semantic token naming model, listing specific components (property classes, intents, contexts, states, modifiers, formula) and ends with a clear usage directive. It distinguishes itself from sibling tools like list_dimensions or list_brands by focusing on the naming model.

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 includes 'Use this to understand how semantic tokens should be structured,' providing clear context for when to use it. However, it does not explicitly mention when not to use it or compare to alternatives among the 30+ sibling tools, slightly reducing 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?

No annotations exist, so the description carries full burden. It adds value by mentioning optional theme resolution, but lacks details on destructive behavior, auth requirements, or output structure. Adequate but incomplete.

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

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

Two sentences, no redundancy, front-loaded with primary action. Every word serves a purpose, achieving high efficiency.

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?

Without an output schema, the description should clarify the result format. It only vaguely says 'showing which tokens differ', leaving output structure, pagination, and edge cases unspecified. Insufficient for a 4-parameter 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%, so baseline is 3. The description adds no new parameter-level information beyond the schema; it only restates the theme option. No enhancement over structured metadata.

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 compares two brands side-by-side and shows differing tokens, which is a specific verb-resource combination. It distinguishes from sibling tools like 'diff_themes' or 'resolve_brand' by focusing on brand comparison.

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 comparing brands but offers no explicit when-to-use, when-not-to-use, or alternatives. Minimal guidance leaves the AI agent to infer context 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?

No annotations are provided, so the description carries the full burden. It does not disclose whether the tool is read-only, requires authentication, or has any side effects. The safe assumption is it is read-only, 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?

A single concise sentence that captures the core functionality with no extraneous 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?

The description is adequate but lacking details on output format or edge cases. For a diff tool, additional context like 'returns a JSON object with lists' would improve completeness.

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 baseline is 3. The description does not add meaning beyond the schema descriptions. It only repeats the concept of comparing themes.

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 'compare' and the resource 'themes', and specifies the output (differing, added, removed tokens). It distinguishes from sibling tools like diff_brands which compare brands.

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 use this tool versus alternatives (e.g., diff_brands) nor when not to use it. The description only states what it does.

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 full burden. It discloses critical behaviors: dry-run by default (safe preview), snapshot creation before execution, and post-execution validation (no broken refs/circular deps). It also implies rollback capability. Missing details like authentication or rate limits are acceptable given the 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 two sentences, front-loading the core action and then specifying the safety default. Every sentence adds value: first sentence defines the tool's purpose and scope, second provides critical usage instruction. No unnecessary words 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 7 parameters and no output schema, the description covers the main workflow, safety behavior, and validation. However, it does not describe the return value or result format, which would help the agent understand what to expect. The absence is minor given the clarity of the overall process.

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 baseline is 3. The description adds no new information about parameter semantics that isn't already in the schema. It mentions 'dry run' and 'snapshot' but those are already documented in the schema. The description does not enhance understanding of parameters 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 clearly states 'Execute token migration' and enumerates specific actions (reference updates, validation, rollback). It distinguishes itself from sibling tools like 'transform_tokens' by emphasizing the migration process with safety defaults and snapshot creation. The verb 'execute' combined with the resource 'migration' provides a specific action-resource pair.

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 warns about the default dry-run mode for safety and instructs how to apply changes by setting dryRun:false. It mentions creating a snapshot for rollback, implying caution. However, it does not explicitly state when not to use this tool versus alternatives like 'transform_tokens' or 'generate_refactor_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?

No annotations provided; description lacks behavioral details such as side effects, permissions, or whether it is read-only beyond the stated transformation.

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, front-loaded with main action and context, no 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?

Covers input, output formats, and filtering sufficiently; lacks error handling or performance notes but adequate for a transformation 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 coverage is 100%; description adds context by specifying input source (mcp_figma_get_variable_defs) and explains features like type inference and collection mapping.

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?

Describes specific verb (extract/convert) and resource (Figma variables to standardized token formats), clearly distinguishing from siblings like validate_figma_tokens or extract_styles.

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?

Mentions usefulness for syncing Figma variables but does not explicitly state when not to use or suggest alternatives among many 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?

No annotations provided, so description carries full burden. It describes the scanning behavior (CSS custom properties and SCSS variables) and what it extracts (colors, spacing, typography). No misleading or contradictory statements; indicates a read-only extraction operation.

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 sentences, front-loaded with action, no unnecessary words. Every sentence adds value: purpose, usage guidance, and scanning behavior.

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?

No output schema, but description explains what is extracted (colors, spacing, typography) and scanning patterns. Parameter count is low and all optional. Missing details on output structure, but sibling tools imply further processing.

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 baseline is 3. The description reinforces parameter meanings implicitly (e.g., stylePaths for scanning, outputFormat for output format) but doesn't add significant detail beyond schema descriptions.

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 it extracts design tokens from CSS and SCSS files, specifying the resource and verb. It distinguishes from siblings by detailing reverse-engineering of colors, spacing, typography, and scanning for CSS custom properties and SCSS variables.

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 context: 'Use when project has styles but no design tokens.' While it doesn't list exclusions or alternatives, the guidance is clear and actionable for when to invoke this tool.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool combines local tokens, Figma data, and design system knowledge, and creates LLM+human-readable markdown. However, it does not mention any mutations, authentication needs, or potential destructive actions. The behavioral information is moderate but incomplete.

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: two sentences that efficiently convey the tool's purpose, inputs, and output. Every phrase adds value, and it is front-loaded with the primary action. There is 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 tool with 6 parameters (4 required), 2 enums, and nested objects, the description covers the main purpose and output. It does not explain error handling or behavior when optional inputs (like figmaComponentData) are omitted. However, given the tool's generative nature, the description is fairly complete for agent understanding.

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 baseline is 3. The description adds context like 'combining local tokens, Figma component data, and design system knowledge' which relates to parameters, but the schema already describes each parameter clearly. The description does not significantly enhance understanding 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 clearly states 'Generate comprehensive component documentation' and lists specific outputs (markdown with frontmatter, token references, code examples, accessibility info). It distinguishes the tool from sibling tools like search_tokens or analyze_coverage, though it does not explicitly name an alternative for similar purposes.

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 says 'Perfect for design-to-development handoffs,' which implies a use case but does not provide when-not-to-use or alternatives. There is no explicit guidance on prerequisites or exclusions, leaving the agent to infer usage context.

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 present, so the description must carry the full burden. It only states the tool generates fluid scales and mentions clamp(), but does not disclose behavioral traits like side effects (e.g., token creation/overwriting), authorization needs, rate limits, or error handling. This is insufficient for a 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 description is extremely concise with two sentences. It front-loads the main purpose and then adds key context. Every word is necessary and no redundancy. Excellent structure.

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 8 parameters and no output schema, the description is minimal. It does not explain the return format, how the clamp() function is constructed, or how ratio and steps interact. While the schema covers param details, the description lacks sufficient context for comprehensive understanding.

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 context about Utopia methodology but does not provide additional semantics beyond what the schema already describes for each parameter. No param details are elaborated beyond schema definitions.

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 it generates fluid/responsive scales using CSS clamp() and references Utopia methodology. It specifies the output as viewport-aware tokens. However, it does not explicitly differentiate from sibling tools like generate_scale or suggest_scale, which might also generate scales but static.

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 provide guidance on when to use this tool versus alternatives. There is no mention of prerequisites, when not to use it, or which sibling tools cover similar functionality. The context of Utopia methodology is given, but no explicit usage directions.

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 states the tool generates a folder and exports tokens/rules, but does not disclose if it overwrites existing files, requires permissions, or has side effects. This is adequate but leaves important behavioral traits unspecified.

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 brief, consisting of two sentences that concisely capture purpose. It front-loads the core action (generating a guidelines folder) and provides key format details (Markdown). No redundant information is present.

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 two simple parameters and no output schema, the description covers the essential functionality but lacks depth. It does not mention what the generated folder contains beyond tokens/rules, nor does it discuss integration with Figma Make. It is minimally complete but could be more informative.

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?

Both parameters have schema descriptions, achieving 100% coverage. The tool description reiterates the meaning of 'components' but adds no significant new semantics beyond the schema. A score of 3 is appropriate given the schema already documents the parameters.

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

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

The description clearly states the tool generates a structured guidelines folder for Figma Make, exporting design tokens and component rules into Markdown. It is specific and distinct from sibling tools like 'search_tokens' or 'generate_component_docs', as none directly produce Figma Make guidelines.

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 the tool is used when needing to provide design system context to Figma Make's AI, but it does not explicitly state when to use it over alternatives. No exclusions or prerequisite conditions are mentioned, leaving the agent to infer usage from context.

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 provided, so description carries full burden. Discloses generation behavior and output type but lacks details on side effects, permissions, or error states. Adequate but not thorough.

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, direct and front-loaded. Every sentence provides value with no redundancy or 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?

Explains purpose, supported strategies, and output type for a generator with 5 parameters and no output schema. Missing details on return format and error cases, but adequate for confident usage.

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%, baseline 3. Description adds strategy examples but does not significantly enhance parameter meaning beyond schema. No new semantics for individual parameters.

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

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

Clearly states it generates color palettes with pluggable strategies (HSL, Leonardo, manual, import). Lists specific output: tonal scales with contrast metadata. Distinguishes from sibling tools by mentioning strategies.

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?

Implies usage via strategy descriptions but does not explicitly state when to use this tool versus alternatives like generate_scale or suggest_scale. No when-not or exclusion 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?

Describes outputs (action plans, effort estimates, risk profiles) but does not disclose whether the tool is read-only, has side effects, or requires specific permissions. Since annotations are absent, more behavioral context would improve transparency.

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, front-loaded with the core action and outcomes. No redundant information; every sentence adds 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?

Adequate for a tool with 5 optional parameters and no output schema. Describes the type of output (approaches, plans) but could mention return format or structure for better completeness.

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 clear parameter descriptions. The description does not add new details beyond the schema, so 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?

Clearly states the tool generates migration scenarios for token refactoring with risk assessment, producing three approaches. Distinguishes from sibling tools like execute_migration and analyze_coverage by focusing on scenario planning.

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?

Implies usage for planning B→C token migration by comparing trade-offs. Does not explicitly state when not to use or enumerate alternatives, but context from sibling tools makes the intended use 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?

No annotations are provided, so the description must disclose behavioral traits. It mentions 'returns token-ready values' but does not state whether the tool is read-only, requires authentication, or has side effects. This is minimal behavioral disclosure.

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 concise sentences: the first states the purpose and the second lists strategies and output. No 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?

For a complex tool with 8 parameters and no output schema, the description leaves gaps: the return format is vaguely described as 'token-ready values' without specifying structure or format.

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% (all parameters have descriptions). The description adds context by listing strategies and noting the output type, but does not significantly enhance understanding 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 clearly states the action ('generate'), resource ('mathematical scale'), and domain ('design tokens'). It lists multiple strategies, distinguishing it from sibling tools like analyze_scales or suggest_scale.

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 lists supported strategies but gives no explicit guidance on when to use this tool vs. alternatives like analyze_scales or suggest_scale. No when-to-use or when-not-to-use context is 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?

No annotations are provided, so the description must reveal behavioral traits. It mentions writing files (implied by dryRun) but does not state whether it overwrites existing files, any side effects, or required permissions. This is insufficient for a tool that generates and writes files.

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 concise sentences with no redundancy. The purpose is front-loaded in the first sentence, and the second provides a key usage tip. Every word adds 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?

Despite having no output schema, the description does not explain what the tool returns (e.g., list of generated files, preview output). With many sibling tools, it lacks guidance on when to choose this over others, and crucial details about file overwriting behavior are omitted.

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 baseline is 3. The description adds value by showing examples of template values and recommending dryRun usage, but does not elaborate on the JSON format for params 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 explicitly states 'Generate a new design-token system from a template' and lists supported types (color palettes, spacing scales, full systems), clearly distinguishing it from sibling tools like generate_palette or generate_scale which are more specific.

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 a useful tip ('Use dryRun=true to preview first') but does not explain when to use this tool versus alternatives like generate_palette or generate_scale, nor does it mention cases where this tool should not be used.

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 must fully convey behavioral traits. It clarifies that the tool lists all brands with specific details, but lacks information about return format, pagination, or permissions. Given the simplicity of a list operation, this is adequate but incomplete.

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 conveys purpose and output details without extraneous information. 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 no parameters, no output schema, and no annotations, the description explains the tool's purpose and output content sufficiently. However, missing details about output structure or ordering prevent a perfect score.

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, and the schema coverage is 100% (empty schema). The description adds value by specifying what fields are included in the output, which compensates for the lack of parameter documentation. Baseline for zero parameters is 4.

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

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

The description states a specific verb ('List'), a clear resource ('all brands defined in config'), and details what information is shown ('token paths, token-set overrides, and dimension defaults'). It distinguishes from sibling tools like 'list_dimensions' or 'list_themes' by focusing on brands.

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 use this tool versus alternatives such as 'resolve_brand' or 'diff_brands'. The description implies a simple listing operation but does not clarify prerequisites, limitations, or appropriate contexts.

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 provided. Description does not disclose behavioral traits such as read-only nature, idempotency, or required permissions.

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?

Single sentence with clear action and examples. Efficiently communicates purpose without extraneous 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?

Description is complete for a parameterless listing tool with no output schema. It covers what is listed and what information is returned.

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, so schema coverage is 100%. Description adds value by specifying what is listed (allowed values and defaults), which is helpful context beyond the empty 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?

Clearly states the tool lists variation dimensions with examples (color-scheme, density) and describes output (allowed values, defaults). Distinct from sibling listing tools like list_brands, list_themes.

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?

Implies usage when working with design-token theming config, but does not specify when to prefer this over alternatives or when not to use 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?

With no annotations, the description indicates a read-only operation ('list') and adds detail about the content shown. However, it does not disclose potential constraints like pagination or authentication requirements, which would improve transparency.

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 immediately states the main purpose. Every word adds value; 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?

For a parameterless listing tool, the description adequately explains what is listed and what information is shown. Without an output schema, it could be slightly more specific about the return structure, but 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?

There are zero parameters and the schema coverage is 100% (empty object). The description does not need to add parameter details, and the baseline for zero parameters is 4.

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

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

The description clearly states the tool lists all available factory templates for generating token systems and specifies that it shows required parameters and algorithm options. This distinctively identifies the tool's function and differentiates it from sibling tools like list_dimensions or list_brands.

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 explicit guidance on when to use this tool versus alternatives like generate_system or analyze_coverage. The description does not mention prerequisites, context for use, or when not to use 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?

The description explains what a theme is (combination of dimension values) but does not disclose behavioral traits beyond the list action. No annotations exist, so more context about side effects, auth, or return characteristics would be beneficial.

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 succinct sentences, each adding value without redundancy or unnecessary detail. It is front-loaded with the core action.

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

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

For a read-only list tool with no parameters, the description covers the purpose and explains the concept. It is adequate for an agent to understand when to use it, though it could slightly improve by explicitly stating it is safe.

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?

With no parameters, the description does not need to cover parameter semantics. It provides conceptual context (themes as combinations of dimension values), which is helpful. Baseline 4 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 verb 'list', resource 'themes', and scope 'all named themes defined in config', with an example. This distinguishes it from sibling tools like list_dimensions and resolve_theme.

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 provide explicit guidance on when to use this tool versus alternatives like list_dimensions or resolve_theme. It only describes the function without contextual usage advice.

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 present, so the description carries full burden. It reveals that output can be written to disk and mentions merge/split strategies, but lacks details on potential destructive actions (e.g., file overwrite behavior, backup, or rollback). Some behavioral info is present but incomplete.

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 sentences, each providing critical information: the core mapping function, built-in presets, and file output capabilities. No redundant or vague phrasing. Front-loaded with the main purpose.

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 9 parameters and no output schema, the description should cover return format when not writing to disk, error conditions, or a high-level mapping process. It does not explain the inline output structure or prerequisites (e.g., palette must come from generate_palette). Functional but leaves research questions.

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% (baseline 3). The description adds value by explaining presets for light/dark modes, the ability to write to disk as an alternative to inline output, and the merge/split strategies. This goes beyond the bare schema descriptions.

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 purpose: mapping generated palette scales to semantic tokens. It mentions configurable rules, built-in presets for light/dark modes, and file output capabilities. This distinguishes it from siblings like generate_palette (generates palette) and transform_tokens (general token transformation).

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 explicit when-to-use or when-not-to-use guidance is provided. The description implies use after palette generation but doesn't compare to alternatives like transform_tokens or analyze_coverage. The context of many sibling tools makes this gap more significant.

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 full burden. It states the tool returns suggestions and requirements, implying a read-only analysis without side effects. However, it does not explicitly confirm non-destructiveness, rate limits, or authentication needs, leaving some ambiguity about behavioral traits.

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 front-loads the problem ('blank canvas syndrome') and lists outputs. Every phrase adds value; there is 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?

Given the tool has 3 parameters, no output schema, and no annotations, the description adequately covers its purpose, inputs, and outputs. It could be enhanced with more detail on output structure or error handling, but it is sufficient for basic understanding.

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 baseline is 3. The description adds context for the 'description' parameter (e.g., natural language examples) but does not elaborate on 'maxPatterns' or 'includeScaffold' beyond what the schema provides. No additional meaning is added to the parameters.

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

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

The description uses a specific verb ('describe', 'get back') and resource ('UI patterns, component inventories, token surface requirements, next steps') to clearly state the tool's function. It effectively distinguishes from siblings by targeting 'blank canvas syndrome' and starting new designs, which differentiates it from analysis or validation 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?

Explicitly states it's 'perfect for starting a new design or understanding what a feature needs', providing clear use cases. However, it does not mention when not to use it or suggest alternative sibling tools (e.g., scaffold_semantics) for related tasks, which would strengthen the 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?

Without annotations, the description bears the transparency burden. It discloses that the tool resolves tokens and shows brand overrides, and mentions truncation behavior. However, it does not explicitly state that the operation is read-only or safe to call repeatedly, though this is implied by the 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 three sentences that are front-loaded with the core purpose, followed by a behavioral note and a usage hint. Every sentence is meaningful and there is no redundancy or 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?

Given the absence of an output schema, the description could better explain the structure of the returned tokens (e.g., a list of token objects with properties). The truncation hint implies pagination, but the overall output format is vague. It is adequate but not 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 good parameter descriptions. The tool description adds only the truncation handling hint, which is already partially covered by the limit parameter's schema description. Thus, the description adds minimal semantic value 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 clearly states the tool resolves design tokens for a brand, optionally combined with a theme, and shows brand overrides. It is specific about the verb and resource but does not explicitly distinguish from sibling tools like resolve_theme or diff_brands.

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 guidance on handling truncation ('When truncated, offer to fetch more by calling again with limit set to the total count'), but does not indicate when to use this tool versus alternatives (e.g., use resolve_theme for theme-only resolution).

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 mentions truncation behavior and that it shows token changes, but lacks details on auth requirements, rate limits, or potential side effects. For a read operation, this is insufficient.

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 with two sentences: one for purpose and one for a usage hint. No fluff, well 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 no output schema, the description should indicate what is returned. It says 'shows how tokens change' and mentions truncation, but does not specify response format or structure. Adequate but could be more 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 clear descriptions for all parameters. The description confirms the theme can include coordinates and hints at limit usage, but adds minimal extra meaning 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 clearly states the purpose: resolving design tokens for a specific theme or coordinate set and showing changes from default. It is specific and easily distinguishable from siblings like list_themes or diff_themes.

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 includes a usage hint for handling truncation (calling again with limit set to total count). However, it does not provide explicit guidance on when to use this tool over alternatives like search_tokens or when not to use 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?

With no annotations, the description bears full responsibility for behavioral disclosure. It describes the generative output but does not mention potential side effects like overwriting files (though the mergeStrategy parameter addresses that). No warning about file system changes or required permissions.

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

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

Two sentences, no redundant words, front-loaded with action and resource. Every word adds 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?

Given 10 parameters (1 required) and full schema coverage, the description adequately sets expectations. It lacks explicit output structure details, but parameters like format and splitStrategy cover that. No contradictions or 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%, so the description does not need to detail parameters. It mentions only the components parameter, which is the key input. Baseline score of 3 applies since the schema handles parameter semantics.

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 ('Generate') and resource ('minimum viable semantic token set'), clearly distinguishing from sibling tools like 'validate_tokens' or 'transform_tokens'. It states input (component inventory) and output (structured tokens).

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 starting with a component inventory and needing baseline tokens, but does not explicitly contrast with alternatives or state when not to use it. No guidance on prerequisites or exclusion criteria.

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?

Without annotations, the description partially covers behavioral traits by disclosing truncation behavior and advising against reporting it as failure. It does not mention whether the tool is read-only, authentication needs, or rate limits, leaving gaps in complete transparency.

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, front-loading the core purpose and then providing actionable usage hints. Every sentence serves a clear function 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?

Given 9 optional parameters, no output schema, and no annotations, the description does not fully cover what the agent needs. It explains search and truncation but omits details about the output structure (e.g., which fields are returned).

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 each parameter described. The description adds value by contextualizing the limit parameter's role in truncation handling, which is not covered in the schema.

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

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

The description clearly states the tool is for searching design tokens by various criteria, with specific example queries like 'What color tokens exist?'. It distinguishes itself from sibling tools (e.g., list_dimensions) by focusing on search and discovery rather than enumeration.

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 guidance with example questions and explicit instructions for handling truncated results by fetching more with limit. However, it does not explicitly differentiate when to use this tool versus alternatives like list_dimensions for full listings.

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 must disclose behavior. It states the tool 'suggests' parameters and combines multiple standards, implying a read-only recommendation. However, it does not mention side effects, authentication needs, or rate limits. It is moderately transparent but lacks detailed behavioral 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 concise with two sentences. The first sentence clearly states the action and purpose. The second sentence lists design standards, which adds value but could be streamlined. Overall, it is well-structured 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?

The tool has 3 parameters all documented, but no output schema. The description hints at return fields ('strategy, ratio, base, constraints') but does not explicitly declare them. It also lacks differentiation from sibling tools like 'generate_scale'. The description is adequate but incomplete for full 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?

Schema coverage is 100% with all parameters described in the schema. The description adds no extra meaning beyond the schema; it only mentions output fields ('strategy, ratio, base, constraints') which are not parameters. Thus, it meets the baseline for high schema coverage.

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

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

The description clearly states the tool suggests optimal scale parameters based on design principles, with a verb (suggest) and resource (scale parameters). It lists several design standards, making the purpose specific. However, it does not explicitly distinguish from similar sibling tools like 'generate_scale', so it loses a point for 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 the tool is used when one wants scale parameters derived from design principles, but it provides no explicit guidance on when to use it versus alternatives (e.g., 'generate_scale') or when not to use it. The usage context is implied rather than stated.

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

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

No annotations provided, so description carries full burden. It discloses generation of output files and dryRun behavior, but lacks details on overwriting, permissions, or error handling.

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

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

Two sentences, no fluff, front-loaded with core action. Every sentence adds 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?

Given the tool's complexity and no output schema, the description covers transformation purpose, output types, and a usage hint. Adequate for an 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?

Schema coverage is 100%, so description adds little beyond listing platforms. The mention of output formats echoes the enum values without deeper semantics.

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?

Description clearly states the verb 'transform' and resource 'design tokens into platform-specific output files'. Lists specific output formats, distinguishing it from siblings like validate_tokens or search_tokens.

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?

Includes a practical tip: 'Use dryRun=true to preview without writing files.' While it doesn't explicitly contrast with alternative tools, the purpose is clear enough for selection.

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

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

With no annotations, the description covers expected checks, report contents (errors, warnings, sync status), and mode behavior. It lacks explicit mention of side effects (e.g., read-only), but for a validation tool this is acceptable.

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 sentences with no wasted words, front-loaded with the primary action and key features. Efficient and easy to parse.

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, description mentions a detailed report with errors, warnings, and sync status, giving a reasonable picture of output. Could be more precise about return structure, but sufficient for a validation 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 coverage is 100%, providing baseline 3. Description adds value by explaining the expected format of figmaVariableDefs (dictionary from another tool) and clarifying strict mode behavior, going beyond schema descriptions.

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?

Description clearly states it validates Figma variables against local token definitions, listing specific checks (naming mismatches, type errors, etc.). While it is specific, it does not differentiate from sibling tool 'validate_tokens' which might have overlapping 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?

Description implies usage for validating Figma tokens and offers mode selection (strict/non-strict), but does not explicitly state when not to use it or recommend alternatives among sibling tools like 'validate_tokens'.

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 full burden. It states the output is 'a structured report with errors, warnings, and suggestions' but does not disclose whether the tool is read-only, has side effects, or requires special permissions. For a validation tool, the mutability and safety profile are critical.

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: first states purpose and checks, second states output. No unnecessary words, well front-loaded with purpose.

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 two parameters and no output schema, the description adequately covers what the tool does and what it returns. However, it omits details like whether pathPrefix is optional or how presets map to specific rules. Still, it is fairly complete for a simple validation 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 coverage is 100%, so baseline is 3. The description adds context about what the presets control and pathPrefix filters, but largely repeats schema descriptions. It does not add significant meaning 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 states 'Validate design tokens against configurable rules' which is a specific verb+resource. It lists specific checks (naming conventions, value formats, type requirements, deprecated references, architectural patterns) and distinguishes from sibling tools like search_tokens, transform_tokens, and various audit 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 implies usage for validating design tokens but does not explicitly state when to use this tool versus alternatives like audit_semantics or validate_figma_tokens. No when-not or exclusion criteria are provided.

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