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

No annotations are provided, so the description carries the burden. It clearly states the tool is for checking status and the kind of information reported, indicating a read-only operation. However, it could explicitly state it has no side effects.

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

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

The description is extremely concise, using two sentences that front-load the purpose. Every word adds value, and there is no 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 zero parameters and no output schema, the description fairly sets expectations about what is reported (client info, command counts, bridge address). It is sufficient for a simple status check, though a bit more detail on response format 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?

There are no parameters, so schema coverage is 100% by default. The description does not need to add parameter details; the baseline score of 4 applies.

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

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

The description uses a clear verb ('reports') and explicitly lists what the tool returns (client info, command counts, bridge address). It distinguishes itself from sibling tools which are unrelated to connectivity status.

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 plugin connectivity, but it does not provide explicit guidance on when to use it versus alternatives, or any conditions for use.

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; the description discloses core behavior: returns diff ratio, anti-alias accounting, per-band diff localization, pass/fail logic, and mutual exclusivity of bands/bandEdges. It could add more on side effects, but covers essential 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 paragraph of ~120 words, front-loaded with purpose. It efficiently covers key points but could be structured into shorter sentences for better readability; still not verbose.

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 (19 parameters, no output schema), the description explains workflow, pass/fail, and band localization. However, it lacks explicit output structure (only mentions diff ratio and anti-alias but says 'see methodology in the response'), which reduces completeness for an agent needing to parse results.

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 74%; the description adds meaning beyond the schema for key parameters like maxRatio (when to raise), bands/bandEdges (mutual exclusion, mapping to elements), and outRenderPath (avoiding second call). Not all parameters get extra context, but the added value is significant.

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 ('One-shot visual comparison'), resource ('HTML page/element pixel-diffs against reference image'), and distinguishes it from siblings like render_html_screenshot (replaces manual two-step).

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 explains when to use (visual regression) and provides contextual guidance (raising maxRatio for rework loops). It doesn't explicitly list when not to use but implies it replaces a manual two-step, providing good context among siblings.

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 immediate download of temp URLs, caching, chunking, and manifest return. However, it does not disclose potential side effects like file system writes or rate limits.

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?

Description is concise with three sentences, each adding key information. Front-loaded with core purpose, no filler.

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

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

No output schema, so description must explain return value; it mentions manifest. Tool has 9 parameters and no required ones; description doesn't explain default behavior or parameter interactions. 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 67%, so the description adds limited value over schema fields. The description mentions nodeIds and includeImageFills but does not clarify relationships or behavior for conflicting parameters (e.g., url vs fileKey).

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 batch-exports nodes as files and raw image fills, saving to a directory with a manifest. It distinguishes from sibling tools like get_screenshot by focusing on batch export and caching.

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 explicitly state when to use this tool versus alternatives (e.g., get_screenshot for single exports). Usage context is implied but no exclusions or comparisons are provided.

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

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

With no annotations, the description discloses key behaviors: queuing while disconnected, batch progress heartbeats, timeout handling, and export_node's disk writing. However, it does not explicitly state whether commands have side effects (e.g., destructive ones like delete_node).

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 fairly long but efficient. It front-loads the core purpose and command list, then adds behavioral details. Every sentence contributes value, though minor redundancy exists (e.g., queue mention twice).

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 7 parameters, nested objects, and no output schema, the description covers essential behaviors like batching, timeouts, and export. It could detail overall return structure more, but what's provided is sufficient for most use cases.

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

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

Schema coverage is 100%, but the description adds significant meaning: explains queue behavior, batch execution, timeouts, and export_node's return format. This goes beyond the schema's basic 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: 'Send a command envelope to the companion Figma plugin over the local bridge.' It lists specific supported commands, making it distinct from sibling tools like get_screenshot or bridge_status.

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 (e.g., compare_html_to_image, import_html_replica). Usage is implied through the command list, but no when-not-to or prerequisites are stated.

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

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

No annotations exist, so the description carries full burden. It implies a read-only operation but does not disclose error handling, file existence requirements, authentication needs, or whether it modifies local state. The behavioral details are 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 a single, well-structured sentence that immediately conveys the tool's purpose. It is front-loaded and contains 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?

The description covers the basic action but lacks details on error conditions, expected file format, and the relationship between node subtree and nodeId parameter. Given no annotations and no output schema, it is sufficient for a simple tool but not fully comprehensive.

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 adequate individual parameter descriptions. The tool description adds no extra meaning beyond the schema, so it meets the baseline but does not enhance parameter understanding.

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 'Read' and 'return' and the resource 'figmingo.components.json', specifying it returns code targets for components in a requested node subtree. This distinguishes it from sibling tools like get_design_context or get_variable_defs.

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 is provided on when to use this tool versus alternatives, prerequisites, or conditions under which it should not be used. The description is purely functional without contextual 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?

With no annotations, the description partially describes behavior: it reveals the 'simplified' nature of the context and suggests using format=compact to reduce token footprint. However, it does not disclose whether the operation is read-only, performance characteristics, or what aspects are excluded from the simplified output.

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 efficient sentences: first defines purpose and content, second offers a practical tip. No redundant or extraneous information, and critical details are 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 description is moderately complete given the tool's complexity (6 params, no output schema). It explains the result content but omits usage guidelines and behavioral transparency. The tip about format is helpful, but overall the description leaves gaps that an agent would need to infer.

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 advising use of format=compact for smaller token footprint and noting that node-id in the URL is honored, which goes beyond the schema's description. No further elaboration on other 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 retrieves simplified design context for a Figma file or node, listing specific content types (layout, fills/strokes/effects, text styles). This distinctively differentiates it from sibling tools like get_metadata or get_screenshot.

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. The description does not mention exclusions, prerequisites, or scenarios where a different tool would be more appropriate, leaving the agent with no criteria 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 carries full burden. It describes output contents but omits behavioral traits like rate limits, authentication requirements, or size constraints. Lacks insight into default behavior (summary vs inline) implications.

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

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

The description is a single, well-structured sentence that front-loads the main action and output components. No superfluous text, but could be slightly more detailed.

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 11 parameters, no output schema, and no annotations, the description provides adequate but not complete context. It mentions output schema matches another tool but doesn't elaborate on return structure or edge cases.

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

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

Schema coverage is high (82%), so baseline is 3. The description adds no significant parameter instructions beyond the schema. Two parameters (depth, outPath) lack descriptions in schema, but description doesn't compensate.

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 builds a replica-optimized spec from Figma, listing specific output elements (rects, typography, colors, etc.). It distinguishes from siblings by focusing on spec generation for parity verification.

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 vs alternatives like get_design_context or get_variable_defs. No when-to-use or when-not-to-use context is given.

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 output format and what is returned (id, name, type, bounds) and notes it's lightweight. Missing details on authentication, rate limits, or potential side effects, which are important for a file access tool.

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

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

Two well-structured sentences. First sentence delivers core purpose and return values; second specifies output formats. 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?

Given no output schema, the description adequately covers the idea of a lightweight tree for orientation. Could benefit from clarifying whether the tree includes all children or just immediate, and the format of bounds, but sufficient for basic use.

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 80% (4 of 5 parameters documented). The description adds that output can be XML or JSON and that node-id in URL is honored, but does not significantly 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?

Clearly states it returns a lightweight tree of Figma file/node with id, name, type, bounds for orientation, distinguishing it from a deep fetch. The verb 'get' and resource 'metadata' are clear, and the scope is 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?

Explicitly mentions 'for orientation before a deep fetch', giving context for when to use. However, does not explicitly state when not to use or compare directly with sibling tools like 'get_design_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?

With no annotations, the description carries full burden. It discloses that the tool returns base64 inline and/or saves to disk, and specifies valid inputs (scale range, formats). It does not mention authentication, error states, or read-only nature, but covers core behavioral aspects adequately.

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 with no wasted words. The first sentence immediately states the core purpose, and the second adds key options. It is 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 7 parameters and no output schema or annotations, the description covers essential input choices and output behavior. It lacks detail on response format beyond 'base64' and error handling, but it is sufficiently complete for typical 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 71%, and the description adds context beyond schema: it clarifies scale range, formats, and the choice between url/fileKey. It explains the output modes (inline base64, savePath) and that node-id can come from url. This helps an agent determine parameter values.

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 renders a Figma node to an image using the specified endpoint, and lists supported formats and output options. It distinguishes the tool from siblings (e.g., render_html_screenshot) by the resources and endpoint used.

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 technical details (scale, format, output modes) but does not explicitly state when to use this tool versus siblings like get_design_context or render_html_screenshot. No exclusion criteria or alternative suggestions are given.

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 the fallback mechanism and that every output is marked with source, which is good transparency. However, does not mention potential side effects, authentication requirements, or rate limits.

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 with no wasted words. Front-loaded with main purpose, then details in second sentence. Very concise.

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

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

Covers the core functionality and fallback behavior. No output schema, but return values are fairly standard (tokens with source markers). Could mention that it returns variable definitions, but sufficient 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 description coverage is 100%, so baseline is 3. Description adds context about fallback behavior but does not enhance parameter understanding beyond existing 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 retrieves design tokens with a specific verb 'Get'. It explains the dual approach: tries Enterprise endpoint and falls back to published styles/inferred tokens, distinguishing it from other 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 use for retrieving design tokens but does not explicitly guide when to use this tool over siblings like 'search_design_system' or 'get_metadata'. No 'when not to use' or alternatives mentioned.

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

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

With no annotations, the description fully discloses the use of headless Chromium, extraction of layout and computed styles, rebuilding into frames with specific node types, reporting of warnings, and support for dryRun. It also mentions mutual exclusivity of input parameters.

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

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

The description is well-structured, starting with a clear main purpose, but it is somewhat lengthy (around 200 words) and includes details that are also in the schema. It could be more concise while retaining essential information.

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

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

Given the tool's complexity (19 parameters, no output schema), the description covers the main inputs, process, and output (warnings array). It provides a high-level understanding, though not every parameter is explained in the narrative; the schema covers those details. The description is sufficiently complete for an agent to use the tool effectively.

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 89%, so the schema already describes most parameters. The description adds value by explaining the relationship between parameters (e.g., mutual exclusivity of htmlUrl, htmlPath, spec, specPath) and the overall flow, which goes beyond individual parameter 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 imports an HTML page or replica spec into Figma as native frames. It distinguishes from siblings like get_html_replica_spec (which only extracts spec) and render_html_screenshot (which only renders a screenshot).

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 hints at using get_html_replica_spec to obtain a spec but does not explicitly state when to use this tool versus alternatives like render_html_screenshot or verify_html_parity. More explicit guidance would improve clarity.

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 using Playwright chromium, waiting for images, hiding fixed/sticky elements, and supporting full-page or selector captures. However, it omits details like performance impact or side effects (e.g., file system writes).

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, information-dense sentence that front-loads the core purpose. It is concise but could benefit from slight restructuring to improve readability (e.g., list key features).

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 13 parameters and no output schema or annotations, the description covers the main functionality and key options. It is fairly complete but could include notes on error handling or output format (PNG is implied) to fully inform the agent.

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

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

Schema description coverage is 62%, and the description adds context for key behaviors (waiting for images, hiding fixed elements, full-page vs selector). For parameters like 'settleMs' and 'viewportWidth', the description does not provide additional meaning beyond the schema defaults.

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 creates a Playwright (chromium) screenshot of HTML content, specifying local/remote pages and element selectors. This distinguishes it from sibling tools like 'get_screenshot' and 'compare_html_to_image'.

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 details capabilities (image loading, hiding elements, full-page/selector captures) but does not explicitly state when to use this tool versus alternatives like 'get_screenshot'. No exclusions or prerequisites 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?

The description discloses that it uses a local index and consumes no extra API quota beyond one file fetch, which is useful behavioral context. However, it does not address other behaviors such as error handling, sorting, or pagination. With no annotations, the description carries the full burden and is only partially adequate.

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, front-loading the main purpose and adding a key behavioral note. Every sentence adds value, though it could be slightly more structured.

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

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

Given the tool has 6 parameters and no output schema or annotations, the description is insufficient. It does not explain how parameters like types, nodeId, or fileKey interact, nor does it describe the output format or error scenarios.

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 83%, so most parameters are already described in the schema. The description adds only the high-level search context, not additional parameter details. Baseline of 3 is appropriate.

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

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

The description clearly states the tool searches a file's design system for components, component sets, and published styles, which is a specific verb+resource. It also distinguishes from siblings like get_design_context or get_metadata by mentioning local index and quota.

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 searching design system elements but does not explicitly state when to use this tool versus alternatives like get_variable_defs or get_design_context. No exclusion criteria or 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?

Without annotations, the description adequately discloses behavioral traits: it compares HTML vs Figma spec with tolerances, outputs JSON report and diff images. It does not mention side effects, rate limits, or auth needs, but the read-only nature is implied. The output format is clearly stated.

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 (4 sentences) and front-loaded with the main purpose. It packs many details efficiently, though a bullet list for the three gates could improve scannability. 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?

Given the complexity (18 params, no output schema, no annotations), the description explains the tool's core function and output well. However, it omits input requirements (e.g., need for either url or html) and does not mention edge cases or resource consumption, leaving minor 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 description coverage is 78%, so baseline is 3. The description does not add meaning beyond the schema; it focuses on overall behavior rather than parameter interactions (e.g., precedence rules for url, html, or spec). No parameter-specific details are provided.

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 an 'acceptance gate' that compares rendered HTML against a Figma replica spec, detailing three specific gates (content, structural, visual) with tolerances. This distinguishes it from siblings like compare_html_to_image or get_html_replica_spec, which are more limited in scope.

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

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

The description implies usage for final validation but does not explicitly state when to choose this tool over alternatives (e.g., compare_html_to_image). There is no guidance on prerequisites or exclusions, leaving the agent to infer 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?

Discloses the action (GET request) and additional outputs (rate-limit and disk-cache). Implies non-destructive read operation. No annotations to contradict.

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 efficiently conveys purpose and scope. 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?

Describes both the operation and expected outputs without an output schema. Provides sufficient context for an AI agent to understand what the tool returns.

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 no param info, but none needed. Baseline 4 applies.

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

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

Clearly states it performs a token sanity check via a specific endpoint (GET /v1/me) and adds extra functionality (rate-limit observations, disk-cache status). Distinct from sibling tools, which are all design/UI related.

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?

Implied usage as a sanity check for token validity and system status. No explicit when-not-to-use, but context makes it obvious. Could be improved with a note about typical use cases.

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