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

No annotations are provided, so the description must cover behavioral traits. It mentions the scope and data returned but does not state that the tool is read-only, requires no destructive actions, or has specific authentication needs.

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: the first clearly states what it does, and the second provides use cases. No redundant information, 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 and two parameters, the description sufficiently explains purpose, parameters, and usage. It does not detail return format, but that is acceptable for a statistics 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 0%, so the description adds value by explaining the 'nodeId' parameter's scope and listing the 'kind' enum values (colors, typography, spacing, all). It clarifies their meaning beyond the enum labels.

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 specifies the tool's purpose: providing usage statistics for colors, typography, and spacing from the live canvas. It clearly distinguishes from sibling tools like 'canvas_audit' or 'inspect_node' by focusing on statistical counts of design primitives.

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

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

The description gives explicit use cases: spotting hard-coded values for tokenization and deriving palettes. It implies when to use this tool but does not explicitly state when not to use it or list alternatives.

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

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

The description details key behaviors: it sets plugin data, writes resolved values, supports multiple token types (color, spacing, typography, shadow), evaluates math expressions, follows references with cycle protection at depth 16, skips hidden nodes by default, and offers a dryRun mode. However, it does not mention error handling for missing themes or that writing resolved values is destructive and irreversible.

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 dense single paragraph of about 150 words. Every sentence adds value, but it could be more scannable by breaking into sections (e.g., overview, supported properties, parameters). It is not overly verbose given the tool's complexity.

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 high complexity (10 params, no output schema, no annotations), the description covers core functionality (token resolution, dry run, supported types) but lacks parameter descriptions and usage guidance. It provides a solid baseline but leaves important gaps for an agent to select and invoke the tool correctly.

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

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

With 10 parameters and 0% schema description coverage, the description only explains 'dryRun' ('Pass `dryRun: true`...') and implicitly mentions 'themeName' as required. The other eight parameters (url, scope, nodeId, fileKey, onlyColor, setActive, skipHidden, bindingMode) are not described, leaving the agent to infer their meaning solely from names and schema enums.

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

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

The description opens with a specific verb+resource: 'Switch the file to a theme and resolve every applied token to its concrete value.' This clearly states the tool's primary action and scope, distinguishing it from siblings like 'apply_token_remap' which remaps tokens without applying a full 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 specify when to use this tool versus alternatives such as 'apply_token_remap' or 'apply_to_variants'. It implies usage for applying themes but gives no guidance on scenarios where a different tool would be more appropriate.

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

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

Discloses plugin requirement, dryRun behavior, and single undo entry for batch. Given no annotations, the description provides good behavioral context, though missing potential side effects like overwriting existing tokens.

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: purpose, prerequisite, usage details. No unnecessary words. Front-loaded with key 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?

Covers plugin dependency, relationship with propose_token_remap, dryRun, and undo behavior. Lacks error handling or confirmation details, but adequate for nested-object tool with no output schema.

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

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

Explains plan and dryRun parameters with context (plan from propose_token_remap, dryRun for validation). But planId parameter is not described, and schema coverage is 0% so description partially compensates.

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 ('Apply a remap plan'), the target ('live Figma file'), and the mechanism ('via the companion plugin'). It distinguishes from sibling tools like propose_token_remap and 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?

Explicitly mentions prerequisites (plugin running and connected) and recommends calling bridge_status first. Also instructs to pass plan from propose_token_remap with chosen decisions. No explicit when-not-to-use, but context is clear.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It explains that the tool writes tokens, can clear properties via clearProperties, offers a dry run mode, and targets descendants by layerName and layerType. This provides good transparency about side effects and behavior.

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

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

The description is a single paragraph that front-loads the main purpose and then adds details. It is fairly concise for the complexity, though it could be broken into shorter sentences. No waste, but could be slightly more streamlined.

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 (9 parameters, no output schema), the description covers the core functionality well but lacks details on several required parameters and does not describe the return value. It is adequate but has clear 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 0%, so the description must explain all parameters. It explains template, layerName, layerType, clearProperties, and dryRun, but fails to describe url, nodeId, fileKey, and property (which is required). The property parameter is mentioned but not defined. This leaves significant gaps for the agent.

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 'bulk-apply tokens to every variant of a Figma component_set in a single call', using a template with placeholders. It is specific about the resource (component_set variants) and the action (applying tokens), and distinguishes it from sibling tools like set_token which apply to individual nodes.

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

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

The description gives explicit context for when the tool is useful: 'Solves the tab bar / button / chip / icon-set shape' and mentions it works for any naming convention. It also describes the dryRun feature for testing. However, it does not explicitly state when not to use it or mention alternative 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 are provided, so the description carries the full burden of disclosing behavior. It states the tool checks connections and returns file info, which implies a read-only operation, but it does not explicitly confirm that the tool has no side effects or destructive actions. More transparency about the non-destructive nature would improve the score.

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

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

The description is concise with two sentences, no redundant information. The key information is front-loaded with 'Diagnostic:', making it easy for an AI agent to quickly understand the tool's purpose and what it returns. Every sentence adds value, including the troubleshooting advice.

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

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

Given the tool has no parameters, no output schema, and no annotations, the description covers essential aspects: purpose, return values, and a failure response action. It is complete for a simple diagnostic tool. However, without an output schema, more details about the exact format of the returned file key/name could enhance 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?

The tool has no parameters, and the schema description coverage is 100% (empty schema). According to guidelines, with high coverage the baseline is 3. The description adds no parameter-specific information, which is acceptable since no parameters exist. The score reflects adequate handling for a parameterless tool.

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 diagnostic: it checks if the WebSocket bridge is running and the Figma plugin is connected, and it returns the connected file's key/name. The 'Diagnostic:' prefix and specific verb 'check' make the purpose unambiguous. It distinguishes itself from sibling diagnostic tools like 'debug_resolve_token' or 'get_design_context' by focusing on the bridge/plugin connection 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 includes actionable advice for when the plugin is not connected ('make sure the 'Tokens Studio MCP Bridge' plugin is open in Figma'), which guides the user on next steps. However, it does not explicitly state when to use this tool versus alternatives (e.g., other diagnostic tools), nor does it mention scenarios where the 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 provided, but description discloses key behaviors: dryRun returns counts without modification, scopes for live and files, and pattern syntax. Lacks details on reversibility 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?

Concise, well-structured with bold emphasis and an example. Every sentence adds value 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?

Covers main functionality comprehensively given no output schema, but omits return details for non-dry runs and optional parameters. Slight gap for a tool with 6 parameters.

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?

Explains the rules parameter with pattern syntax and scope/dryRun. Does not cover nodeId or fileKey, but core parameters are well-addressed despite 0% 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?

Clearly states verb (rename) and resource (tokens) with specific pattern matching and scopes. Distinguishes from sibling tools by referencing apply_token_remap and rename_token.

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 clear context on when to use (bulk renaming) and explains scopes and dry run. Does not explicitly exclude single rename or list alternatives, but the detail is sufficient.

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 explains the scope (nodeId → selection → current page), the checks performed, and the return format (counts + failing nodes). It does not mention auth needs or rate limits, but for a read-only audit, the key behaviors are disclosed.

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

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

The description is a single, dense paragraph that front-loads the main purpose. Every sentence contributes essential information without redundancy. It is well-structured and readable.

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 (5 optional parameters, no output schema), the description adequately covers the tool's behavior, scope, checks, and return format. It is complete enough for an agent to understand and invoke the tool correctly.

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

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

The schema has no descriptions for its 5 parameters. The description adds meaning for 'check' by explaining each enum value (contrast, touch, text, all) with criteria. 'level' is implied in the contrast check but not explicitly linked. 'minTouch' and 'minFontSize' are referenced but not explicitly as parameters. Overall, it adds significant value but could be more explicit about parameter 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?

The description clearly states it performs an accessibility audit on the live canvas, listing specific checks (contrast, touch, text, all). This distinguishes it from sibling tools like analyze_design or get_canvas_tree, which serve other 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 implies use for accessibility auditing but does not explicitly state when to use it versus alternatives, nor does it provide when-not-to-use guidance. The context is hinted but not fully explicit.

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

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

With no annotations, the description carries the full burden. It discloses conflict-checking behavior and remote interaction, and it states the GitHub-only limitation. However, it does not explicitly confirm that a remote push occurs (though implied by 'commit_and_push' and conflict-checking) nor describe side effects on the local working copy.

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 filler. The first sentence states the primary action and parameters; the second adds critical conflict and support details. Every sentence earns its place.

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

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

Given 3 parameters, no output schema, and no annotations, the description covers the core action and a key constraint (GitHub only) but omits return value details and prerequisites (e.g., having staged edits). It is minimally adequate but leaves 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 0%, so the description must compensate. It mentions 'branch' and 'asNewBranch' but does not explain them thoroughly; the required 'message' parameter is only implied via 'single commit', not described. The description adds some context but is insufficient for all 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 ("Flush") and resource ("every staged edit") to indicate a commit and push action. It clearly distinguishes from sibling tools like discard_pending_edits or list_pending_edits by describing a write operation that synchronizes with a remote.

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 through context (e.g., conflict-checking and retry guidance), but it does not explicitly state when to use this tool versus alternatives. The mention of 'Currently supports GitHub only' provides a constraint, but no direct exclusions or sibling comparisons 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. Discloses remote creation, default branch, optional override switching, and provider limitation. Lacks details on potential destructive actions but overall transparent.

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 redundancy. Each sentence serves a distinct purpose: core function, optional behavior, and scope limitation.

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 key aspects: what it does, default behavior, optional switch, and provider limitation. Lacks return value or error specificity, but adequate for a simple creation tool with no output schema.

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

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

Schema has 3 parameters with 0% description coverage. Description effectively explains 'from' defaults to current branch, 'name' is required, and 'switchTo' toggles override. Adds 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?

Description clearly states 'Create a new branch on the active token source's remote', specifying verb and resource. Differentiates from sibling tools like commit_and_push or discard_pending_edits which serve different 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?

Explains default branching behavior, optional switchTo, and explicitly states GitHub-only support with error for others. Missing explicit alternatives but sufficient context given sibling list.

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 that the server fetches SVG from api.iconify.design, the plugin renders as vectors, and options like tinting with color and placing inside parentId. However, it does not cover error handling, rate limits, or what happens if the icon is not found.

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 consists of two well-structured sentences, front-loaded with the main purpose, and every word adds value. No unnecessary 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 7 required/optional parameters and no output schema, the description covers the core behavior: fetching SVG, rendering, tinting, and placement. It could mention the return value or confirmation of creation, but overall it is sufficiently complete for an agent to 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 description coverage is 43% (icon, size, color described). The description adds context for color (tinted), parentId (placed inside), and default size (24). But it does not clarify x, y, or name parameters beyond what the schema provides.

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 the tool creates an icon on the canvas from the Iconify catalog, which is a specific verb+resource combination. It distinguishes itself from siblings like create_node and create_image_from_url by mentioning the Iconify catalog and the SVG fetching process.

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 adding icons from Iconify's catalog (200k+ icons), but does not explicitly state when to use this tool versus alternatives like create_node or create_image_from_url. 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.

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

No annotations exist, so the description must carry this burden. It discloses server-side fetching and native image sizing unless dimensions are given, but omits details on URL validation, failure handling, authentication needs, or size limits. The behavior is partially transparent but lacks important safeguards.

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 redundancy, efficiently front-loading the core action and size behavior. Every word adds value, making it a model of conciseness.

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 hint at return value (e.g., created node ID). It covers the operation well but omits output details and doesn't contrast with siblings like 'create_node'. The explanation of size behavior partially compensates.

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 only 14% schema description coverage, the description adds minimal value: it explains that width/height default to native size, but does not clarify x, y, name, or parentId. The url parameter description already exists in schema. This is insufficient for a 7-parameter tool.

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 fetches an image from a URL server-side and places it as a rectangle with image fill on the canvas, using examples like screenshots and logos. This specific verb+resource pairing effectively distinguishes it from siblings like 'create_icon' or 'create_node'.

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 examples of when to use (reference screenshots, logos, photos) but does not explicitly contrast with alternatives like 'create_icon' or export functions. Guidance on when not to use or prerequisites is absent, 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?

With no annotations, the description reveals key behaviors: auto-positioning unless x given, recursion via children, support for many types (svg, image, section, etc.), and returns root node id. However, lacks details on error handling, permissions, or limitations.

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 long but well-structured: begins with basic function, lists supported types, then details properties per type, and ends with nesting. Every sentence adds value, though some redundancy could be trimmed.

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 28 parameters and no output schema, the description covers the core purpose and property behavior. Missing details on required type and its enum values, but overall it equips an agent to use the tool correctly.

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

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

Schema coverage is low (21%), but the description adds significant meaning: explains auto-positioning for x, padding CSS-style notation, children recursion, and sub-properties for each type (e.g., text: characters, fontSize). This compensates for missing 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 creates nodes in a live Figma file, listing many node types (frame, rectangle, ellipse, etc.). It distinguishes from sibling tools which are mostly tokens/themes/analysis 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?

The description explains auto-positioning and property support but does not explicitly state when to use this tool versus alternatives like node_action or canvas_audit. No when-not 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?

No annotations are provided, so the description carries full burden. It implies the tool is read-only and diagnostic, and explains the return format and how missing sub-properties indicate unresolved references. However, it does not explicitly state that it does not modify data, nor does it discuss authorization 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?

The description is two sentences, concise and front-loaded with the word 'Diagnostic'. It efficiently communicates the purpose and diagnostic guidance without filler 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 explains the return value (full resolved value tree) and how to interpret results, which is appropriate for a diagnostic tool. However, it does not mention possible error conditions, result size limits, or performance considerations, leaving some gaps for a complete 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 schema already documents the parameters. The description adds an example token path format and use case context, but does not provide additional semantic meaning beyond what the schema offers.

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 is a diagnostic tool to resolve a specific token path under a given theme and return the full resolved value tree. It specifies the verb 'resolve' and the resource, and provides a concrete use case for debugging composition tokens, which distinguishes it from sibling 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 gives a clear context for usage ('useful for debugging why a composition token doesn't produce the expected writes') but does not explicitly state when not to use it or name alternative tools for other scenarios. It provides interpretation hints for results but lacks exclusions.

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

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

Discloses that deletion is staged and not immediate, which is important behavioral context. No annotations provided, so description carries full burden; could mention more about destructive nature or prerequisites.

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 unnecessary words, highly 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?

For a simple tool with no output schema and few parameters, the description covers the action and critical staging behavior. Could mention that this is a mutation, but overall adequate.

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

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

With 0% schema description coverage, the description adds value by explaining that `path` and `set` refer to the token path and the named set, providing meaning beyond the bare property names.

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 stages a token deletion and specifies the resource (token at path from set). Differentiates from siblings like set_token or rename_token.

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 by mentioning staging and accumulation until commit_and_push, but does not explicitly state when to use or not use this tool compared to alternatives.

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

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

No annotations are provided, so the description carries full burden. It fails to disclose important behavioral traits such as mutation side effects (add/delete are mutating), permission requirements, or what happens on failure. The mention of 'via the plugin' is vague.

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 single-sentence description is very concise, front-loading the purpose and action details without any waste. Every part 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 (4 parameters, 3 actions, no output schema), the description covers the main operations and target options. However, it omits return values, edge cases, and does not confirm that listing returns a list or that add/delete are mutating.

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 0% schema description coverage, the description adds meaning by explaining which parameters are needed for each action (url required for add/delete, name optional). However, it does not fully explain the target node parameter or how current selection works.

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 manages dev resource links on a node with explicit actions (add, list, delete) and target specification, distinguishing it from sibling tools which are largely design or token operations.

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 the three actions with parameter syntax and target options (nodeId or current selection), providing clear context for when to use the tool, though it does not explicitly state when not to use it or mention alternatives.

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

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

No annotations are provided, so the description must convey behavioral traits. It correctly indicates the destructive nature of the operation ('throw away,' 'reset'). However, it does not mention potential side effects like irreversibility or impact on other branches, leaving some gaps.

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

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

Two concise sentences with no wasted words. The key action is front-loaded, making it easy to parse quickly.

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 no parameters and no output schema, the description is complete enough. It explains the operation and when to use it. Sibling tools provide related context, and the description aligns with the expected behavior.

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

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

The input schema has zero parameters, so schema description coverage is 100%. The description adds no parameter details because none exist. Baseline for no 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 it discards staged edits and resets to the last fetched base catalog. The verb 'throw away' and resource 'staged edits' / 'working copy' are specific. It distinguishes from siblings like 'commit_and_push' (which commits) and 'list_pending_edits' (which lists).

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 'Useful when you want to start over,' providing clear context for when to use the tool. While it does not list when-not or alternatives, the single-sentence guidance is sufficient for a simple destructive operation.

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 return types (inline image for PNG/JPG, text for SVG) but omits side effects, error conditions (e.g., missing nodeId and empty selection), permissions, or limits. Coverage is moderate.

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 purpose, no unnecessary words. Could be more structured (e.g., bullet points for params and return types), but remains concise and clear.

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 3 parameters, no annotations, and no output schema, the description covers the core purpose and return behavior. It lacks details on parameter defaults, error handling, and explicit constraints (e.g., maximum file size, read-only nature). Adequate but not 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?

Schema description coverage is 0%, so description must compensate. It explains nodeId can be omitted when using selection, and mentions format and scale implicitly via the export action. However, it does not explain scale defaults (e.g., 1x), format default, or the meaning of scale values beyond the schema constraints.

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 tool exports a node as an image (PNG/JPG/SVG) and distinguishes between inline image vs text return. It specifies node identification via nodeId or current selection, setting it apart from sibling tools like analyze_design or get_canvas_tree.

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 mentions 'via the plugin' but lacks explicit guidance on when to use this tool vs alternatives. It does not state prerequisites, when not to use it, or compare with other tools. The context is adequate but not detailed.

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 that code runs in async IIFE, last expression is result, nodes returned as stubs, and each call is one undo step. No annotations present, so description carries full burden; covers major behavioral traits but omits 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?

Concise at ~100 words, well-structured with clear sections: purpose, execution model, usage guidance. No redundant 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?

Covers execution model, result format, and usage context well. Lacks mention of error behavior or security implications, but given no annotations or output schema, this is fairly 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 has two params with 50% coverage. Description adds context for 'code' (JavaScript in async IIFE) but does not explain 'timeoutMs' behavior, partially compensating for schema gaps.

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 'Execute JavaScript inside the connected Figma plugin sandbox' with specific verb and resource. Distinguishes from siblings by suggesting structured tools for common operations.

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 advises using structured tools for common operations and reaching for eval when they don't cover the need. Also describes execution context (async IIFE, await, return).

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

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

Annotations are absent, so the description must carry the full burden. It mentions mutation sub-ops like 'create', 'setValue', 'bind', and notes color format acceptance, but fails to disclose important behavioral traits such as error handling, permissions required, side effects (e.g., on variables or binding), or output format. The description is insufficiently transparent for a tool with multiple complex sub-operations.

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

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

The description is a single dense sentence listing multiple sub-operations without structure. While it front-loads the purpose, the lack of bullet points or clear separation makes it hard to parse. It could be more concise by grouping related sub-ops and using formatting.

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 11 parameters, no output schema, and no annotations, the description is incomplete. It does not explain return values for any sub-op (e.g., whether 'list' returns an array, or 'create' returns an ID). Behavioral context is missing. The description covers the basic sub-ops but lacks the depth needed for an agent to use it 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 description coverage is 0%, so the description must compensate. It partly does by listing required parameters for each sub-op in curly braces (e.g., 'createCollection' {name}), but not all 11 parameters are covered (e.g., nodeIds, variableId, modeId are mentioned but not fully described). The description adds some meaning but is far from exhaustive, leaving many parameters poorly documented.

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 handles 'Figma Variables CRUD + binding via the plugin' and lists specific sub-operations with details on what each does. While it doesn't explicitly differentiate from sibling tools like 'set_token' or 'inspect_bound_variables', the focus on variables (as opposed to tokens) and the enumerated sub-ops provide a clear 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?

No explicit guidance on when to use this tool vs alternatives. The description lists sub-operations but does not explain scenarios or prerequisites for each. Given the many sibling tools related to tokens and design, the lack of usage context is a significant gap.

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 return fields (id, name, type, bounds) and a cap on matches (default 50). However, it does not confirm whether the operation is read-only, which is important for a search 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 a single sentence that front-loads the core purpose. Every word is informative without redundancy. It efficiently covers search criteria, return fields, and the default limit.

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 and 3 parameters, the description provides sufficient details: current page scope, substring name matching, type examples, return fields, and match limit. It could optionally mention read-only nature but remains adequate.

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

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

The input schema has 0% description coverage. The description compensates by explaining that 'name' is a substring match, 'type' takes values like FRAME, TEXT, etc., and 'max' is an integer defaulting to 50. This adds meaningful context 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 'Find' and the resource 'nodes on the current page'. It specifies the search criteria (name substring, type) and lists example types. This distinguishes it from sibling tools like inspect_node or get_canvas_tree.

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

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

The description implies use when searching for nodes by name or type, but does not explicitly state when not to use it or mention alternatives. No exclusion criteria or context for when to prefer this over other node-related 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 discloses the root selection priority, depth limits (default 6, max 12), and the data fields returned (id/name/type, geometry, auto-layout props, etc.). Does not mention auth or side effects, but mutation is not implied.

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, all essential. Front-loaded with the tool's unique advantage (no fileKey needed). Each sentence serves a distinct purpose: scope, root logic, and returned data. 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, description fully covers return values and constraints. It lists all key node attributes and depth limits. For a tree retrieval tool with two simple parameters, this is 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 0%, so description must add meaning. It explains the depth parameter's default and maximum, and clarifies the nodeId parameter's role in root selection. This significantly aids correct parameter usage.

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 the 'Live node tree from the plugin', explains the scope (works in ANY file), and specifies the root node selection logic. This distinguishes it from siblings like 'find_nodes' or 'inspect_node'.

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 contexts by noting it works in drafts, branches, files without REST access, and does not require a fileKey. While it does not explicitly state when not to use, the context signals and sibling tool names help differentiate.

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 returns two pieces of data (pinned and selection) from the Figma plugin. It doesn't mention side effects or error cases, but as a read-only query the behavior is implicitly safe and clear.

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 short sentences front-load the purpose. Every sentence adds value: first states what it does, second gives usage context, third provides a preference hint. 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 explains return values: pinned target and live selection. Combined with usage guidelines, it provides complete context for a simple tool. No missing information for an agent to use it correctly.

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

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

The tool has zero parameters, so schema coverage is 100%. The description doesn't need to add parameter info; baseline for 0 params is 4. No extra semantics required.

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 returns the designer's currently pinned target and live selection from Figma. The verb 'returns' and resource 'pinned target and live selection' are specific. It distinguishes from siblings by focusing on current selection, unlike get_design_context or inspect_node which are broader.

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 when to use: when the user says 'this', 'here', 'the current selection', or doesn't specify a URL. Also advises to prefer 'pinned' if present, which is a clear usage hint. No when-not needed as it's implied.

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?

Despite lacking annotations, the description is highly transparent about the tool's behavior, detailing exactly what the returned markdown tree contains: auto-layout, colors, gradients, effects, typography, tokens, etc. It also notes that defaults are omitted and it's one line per node. However, it does not discuss error handling, permissions, 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?

The description is a single, dense sentence that front-loads the purpose. It efficiently packs a long list of features into a readable format using dashes and commas. While verbose due to the extensive feature list, it remains well-structured and avoids 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 absence of an output schema, the description compensates thoroughly by enumerating every design property returned. It covers complexity well but lacks input parameter explanations and usage constraints. Overall, it provides sufficient context for an agent to understand what the tool delivers.

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 only 43% schema description coverage, the description adds no additional meaning over the schema's parameter descriptions. It does not explain parameters like url, nodeId, fileKey, or withTokens, which are left to the schema's minimal or missing descriptions. The description focuses entirely on output, not input.

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 this tool is for building code from a Figma design, positioning it as the primary tool and distinguishing it from a separate Figma MCP. It details a comprehensive set of design properties it returns, making its purpose specific and well-defined.

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 claims it's 'THE tool' for code generation but provides no explicit guidance on when to use this tool vs siblings like inspect_node, get_canvas_tree, or analyze_design. No when-not-to-use scenarios or alternatives are mentioned, leaving the agent to infer 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, so description carries full burden. It details token decoration, empty tokens, untokenized attribute, layout omission, composition stripping, and format options. Lacks explicit idempotency statement but is otherwise transparent.

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 dense paragraph with key info front-loaded. Efficient but could be broken into bullet points for readability.

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

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

Given 11 parameters and no output schema, description is fairly complete on behavior but misses parameter details. Adequate for a read operation but 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?

Schema description coverage is 0%. Description explains layout, format, includeComposition, but leaves url, nodeId, fileKey, onlyGaps, withVectors, onlyWithTokens, withComponents undocumented – 7 of 11 parameters not described.

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

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

The description clearly states it returns an XML tree with tokens, identifies itself as step 2 of a recommended flow, and distinguishes from list_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?

Explicitly says 'STEP 2 of the recommended flow (call list_tokens first...)' and explains when to use various parameters like layout, format, includeComposition.

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 output format and behavior for untokenized nodes (returns '<tokens applied="none"/>'), which is helpful. However, lacks details on safety (read-only), permissions, side effects, 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 redundancy, front-loaded with core purpose and output format. 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 low complexity (3 params, no output schema), the description lacks parameter documentation and does not cover prerequisites or interpretation of the XML output. Incomplete for reliable invocation.

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 0% and description provides no explanation for any of the three parameters (url, nodeId, fileKey). Does not indicate which parameter identifies the node or how they relate, leaving the agent without guidance.

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

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

Description clearly states verb 'Return', resource 'tokens for a single Figma node', and output format 'tiny XML snippet'. Differentiates from sibling tools like get_token_catalog (which returns all tokens) by specifying it's for a single node.

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 context (single node tokens) but no explicit guidance on when to use over alternatives like list_tokens or get_token_catalog, and no exclusions or prerequisites.

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

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

Describes behavior: fetch from remote sync source or local cache, credentials from env vars, returns parsed token tree, themes, metadata. Without annotations, the description carries the full burden and adequately discloses that it is a read operation (fetch) but does not explicitly state non-destructive nature or potential failures.

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 paragraph with clear structure: core purpose, then specific behaviors (override, credentials, filtering). Front-loaded with main action. No redundant sentences, but could be slightly more 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?

Given no output schema, the description covers return type (parsed token tree, themes, metadata). For a complex tool with nested parameters and multiple sources, it is fairly complete. Could mention error cases or what happens if sync is misconfigured, but still strong.

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 50% (only setFilter and pathPrefix have descriptions). The description adds significant meaning: explains `override` as pointing to different repo/branch/file path, mentions auto-discovery, and clarifies credential sourcing. Compensates well for missing 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?

Clearly states it fetches the canonical Tokens Studio token catalog from various remote sync sources or local cache. Distinguishes from siblings by mentioning related tool `get_token_storage_config` and implies difference from `list_tokens` which likely lists without fetching full catalog.

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 guidance to call `get_token_storage_config` first to check secrets, and indicates when to use `override` for different repo/branch/path. Mentions filtering for large catalogs. However, does not explicitly state when to avoid this tool or how it differs from `list_tokens` for listing 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?

Discloses what is returned (storageType blob, metadata), what is NOT returned (credentials), and null case. Lacks explicit statement of read-only nature but 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?

Three sentences with all essential information, front-loaded purpose, 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?

Explains return structure and null case despite no output schema; pairs with sibling tool. Lacks detail on permissions or side effects, but adequate for 0-param 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?

No parameters in schema (100% coverage), description adds context that tool requires no input by stating 'auto-discovers' from the live file, going beyond 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?

Clear verb 'auto-discover' and specific resource 'sync provider config from the live Figma file'. Distinguishes from sibling tools like 'get_token_catalog' by stating pairing and different 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?

Explicitly states when to use (auto-discover config) and when to pair with 'get_token_catalog'. Also explains null case and alternative approach for local cache.

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 that boundVariables override raw writes, that insideInstance nodes silently reject writes, and that the tool dumps specific state fields. However, it does not explicitly state read-only nature, side effects, or auth requirements. The disclosed behavioral traits are useful and accurate.

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

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

The description is concise and well-structured. A single sentence delivers the diagnostic purpose, a list of dump items, and a concrete use case. Every word is informative; 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?

Given 2 parameters with full schema coverage and no output schema, the description sufficiently explains what the tool returns (per-node state with specific fields) and when to use it. The use case provides practical context. It could benefit from mentioning pagination or output format, but overall it is complete for a diagnostic 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 does not add any additional meaning beyond the schema's parameter documentation. The schema already clearly defines 'scope' enum and 'nodeIds' array. No further elaboration 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's purpose: a diagnostic that dumps per-node state including boundVariables, style IDs, and insideInstance status. It explicitly indicates that it helps diagnose why a layer doesn't re-theme despite apply_theme reporting success, which distinguishes it from sibling tools like inspect_node or debug_resolve_token.

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 clear use case: determining why a layer visually doesn't re-theme when apply_theme claims the write was applied. While it implies when to use this tool, it does not explicitly mention when to avoid it or list alternative tools. The context is sufficient but not exhaustive.

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 weight. It discloses the inspection behavior, return structure, and side effects (none implied). It could explicitly state it is read-only, but 'inspect' strongly implies no mutation.

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 packs the core functionality and output, second provides actionable scope guidance and use-case. 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 6 parameters, no output schema, and no annotations, the description covers the tool's purpose and behavior but omits parameter details and exact output format (e.g., 'style gaps' not explained). Middle-of-the-road 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 0%, but the description adds context for scope and maxSuggestions (via 'top remap suggestions'). Other parameters (url, nodeId, fileKey, themeName) are not explained, though they may be inferred from typical Figma node identification. The description partially compensates for low 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 deep-inspects a Figma node with a specific verb and resource, enumerates return values (applied tokens, broken references, remap suggestions, style gaps), and distinguishes itself from siblings like get_node_tokens by mentioning it backs the Inspect tab for end-to-end audits.

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 tells when to use it ('audit a frame's token coverage end-to-end') and how to set scope='subtree'. It does not list alternatives or when-not-to-use, but the context is clear enough among the sibling set.

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 the return value structure and behavior when no edits are staged (returns null). However, it does not explicitly state that the operation is read-only or mention any side effects, but for a list-like tool this is sufficient.

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

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

The description is two sentences, front-loading the key purpose and listing return fields. Every word adds value with no 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 parameters and no output schema, the description adequately covers what the tool returns (branch, base commit SHA, source description, full edit log) and the null case. This is complete for a simple list operation.

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

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

The input schema has zero parameters, so schema description coverage is 100%. Per the guidelines, this yields a baseline of 4. The description does not add parameter information because none exist.

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 specifies a clear verb ('show') and resource ('staged edits in the working copy'), listing specific return fields (branch, base commit SHA, source description, full edit log). This clearly distinguishes it from sibling tools like 'commit_and_push' or 'discard_pending_edits' which perform different actions.

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 reviewing staged edits but does not explicitly state when to use this tool versus alternatives like 'commit_and_push' or 'discard_pending_edits'. While the context is clear, no direct guidance on exclusions or prerequisites 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 provided. Description adds behavioral context (auto-fetch, enabled sets) but does not explicitly state read-only nature or authentication needs.

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 clear, informative sentences. Could be slightly more concise, but structure is good 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?

For a zero-parameter list tool without output schema, the description fully covers purpose, behavior, and sibling relationship.

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

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

No parameters exist; baseline score of 4 as per instructions. Description does not need to add parameter info.

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 themes from the active token catalog and reports enabled token sets, distinguishing it from siblings like apply_theme and list_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?

Provides clear context for pairing with apply_theme, but does not explicitly state when not to use this tool or mention alternatives.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It describes the tool as a 'Cheap pre-flight' that returns grouped tokens with layer names and a style-gap report, and notes special behavior for composition tokens (surface hint, need includeComposition). It does not explicitly state it is read-only or mention permissions, but the read-like nature is implied.

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 front-loaded with a clear purpose statement, then concisely covers key points: pre-flight nature, comparison to sibling, and composition token caveat. Every sentence earns its place 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 the absence of an output schema, the description does a good job describing the return format (grouped tokens, layer names, style-gap report). However, with 7 parameters and no explanations for most, completeness is lacking. The overall context is adequate but not thorough for a tool of this complexity.

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

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

The input schema has 7 parameters with 0% documentation. The description only explains includeComposition (via a hint about composition tokens) and implicitly refers to url/fileKey/nodeId as identifying a subtree. The other parameters (depth, withVectors, withComponents) are not described at all, so 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 starts with 'START HERE for any question about which design tokens a Figma frame uses,' clearly stating the verb (list/return) and resource (design tokens from a Figma frame). It distinguishes itself from the sibling tool get_metadata_with_tokens by noting it is 'Much smaller' and should be called first.

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 says 'call this first to decide whether you actually need the full tree' and warns about composition tokens, guiding when to use this tool versus alternatives. It provides clear context for usage.

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

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

With no annotations provided, the description carries the full burden of disclosure. It details specific behaviors for each action (e.g., clone offset, select scroll into view, combine-variants naming requirement). It also mentions default values for gap and offset. However, it does not explicitly state that delete is destructive or discuss permissions/error states.

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

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

The description is a single sentence that efficiently covers all actions and input methods. It is front-loaded with the verb and main purpose. While it is dense, there is no extraneous information, making it concise but slightly harder to parse due to length.

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 (8 parameters, no output schema), the description covers the main actions and their parameters. However, it lacks details on return values, error handling, prerequisites (e.g., selected nodes), and behavior when no nodes are specified. These gaps reduce completeness for an AI 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 63%. The description adds context on how parameters like nodeId and nodeIds are used (by ID or current selection) and explains action-specific parameters (e.g., parentId for append). However, it does not add significant detail beyond the schema's descriptions; the baseline of 3 is appropriate.

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

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

The description clearly states the tool runs structural actions on nodes and enumerates all 9 actions (delete, clone, etc.). It specifies the input methods (by nodeIds, nodeId, or current selection), making the purpose unambiguous. This distinguishes it from sibling tools like create_node or delete_token, which focus on different operations.

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. It neither states when not to use it nor mentions sibling tools. The user must infer usage from the listed actions, but no exclusion criteria or context-based recommendations 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?

With no annotations provided, the description carries the burden of behavior disclosure. It explicitly states 'Read-only — does NOT touch the Figma file,' which is a critical behavioral trait. It also mentions the return format (candidate tokens with scores and reasoning, plus ambiguous list). No contradictions.

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

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

The description is three sentences, front-loading purpose and key behavioral information. It is reasonably concise, though the sentence about newTokens could be slightly shorter. Overall, it is well-structured 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?

No output schema exists, so the description explains the return value adequately. However, with 7 parameters (1 required), only 'newTokens' is described in detail. Parameters like 'url', 'depth', and 'hints' are left unexplained, making the tool incomplete for an agent to use correctly without additional knowledge.

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

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

Schema description coverage is 0%, and the description only elaborates on 'newTokens' by stating it accepts any reasonable shape (Tokens Studio export, single-set object, DTCG, or flat list). The other six parameters (url, depth, hints, nodeId, fileKey, preferredTheme) are not described at all, leaving their semantics ambiguous.

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: 'Plan a token remap for a Figma subtree against a NEW token set the user pasted as JSON.' It specifies the resource (Figma subtree) and distinguishes from the sibling tool 'apply_token_remap' by directing the agent to pass the plan to that tool after resolving ambiguity.

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

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

The description provides usage context: 'Read-only' and 'Pass the returned plan to apply_token_remap once you've resolved ambiguity.' It implies when to use this tool (planning phase) and what to do next. However, it does not explicitly state when not to use it or compare with other sibling tools like 'suggest_tokens' or 'get_token_catalog'.

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

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

The description discloses the default reference update behavior and the option to disable it. However, it does not explain the 'stage' concept, whether changes are reversible, required permissions, or if it's a direct mutation.

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 clear front-loading. The first sentence states the core action, the second adds critical detail about reference rewriting and the optional parameter. Every sentence is informative.

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 output schema or annotations, the description should provide more context on side effects, staging semantics, return values, and error conditions. The unexplained 'set' parameter is a notable gap.

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

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

The description mentions 'from', 'to', and 'updateReferences' implicitly or explicitly, but does not explain the 'set' parameter. With 0% schema description coverage, the description fails to fully compensate for all 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 stages a rename and moves a token path. It mentions the default behavior of updating references, which adds specificity. However, it does not explicitly differentiate from bulk_rename_tokens or other sibling 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?

There is no guidance on when to use this tool versus alternatives like bulk_rename_tokens or creating/deleting tokens. The description focuses on mechanics, not decision support.

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 changes apply to every target node, returns per-node ok/error, and that fonts are auto-loaded for text properties. It does not mention whether properties are overwritten or merged, or if there are authorization or rate limit implications, which would have pushed it to 5.

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 moderate length. It front-loads the core purpose and then details properties. While efficient, it could be more structured (e.g., bullet points for properties) for easier scanning.

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

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

For a mutation tool with no output schema and no annotations, the description covers targeting, property surface, and return format. It lacks information on error handling specifics, reversibility, or concurrency, but is mostly complete given the complexity.

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

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

The schema has only 33% description coverage (only props has a description). The description compensates by listing all property categories (fill, stroke, strokeWeight, etc.) and explaining targeting logic and return format. This adds substantial meaning beyond the sparse 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 'Edit properties on existing nodes' and specifies the resource (nodes). It distinguishes from the sibling tool 'create_node' by noting the same property surface but for existing nodes. Targeting via nodeIds, single nodeId, or selection is explicitly outlined.

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 implicitly indicates when to use this tool (edit existing nodes) versus create_node (create nodes). However, it does not explicitly state when not to use it or mention alternatives like analyze_design for reading properties. The context is clear but lacks exclusionary 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?

With no annotations provided, the description carries the full burden. It discloses that writes are staged and not committed immediately, and that the type can be inferred. This provides reasonable transparency about the tool's behavior.

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

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

The description is two sentences with no redundant information. The first sentence states the core purpose, and the second adds critical workflow context. Every sentence earns its place.

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

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

For a tool with 4 parameters, no output schema, and no annotations, the description is fairly complete. It explains the staging workflow, parameter functions, and type inference. Missing output details are acceptable given no output schema.

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

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

Schema coverage is 0%, but the description explains set, path, type (with examples), and the value parameter's role. It adds meaning beyond the raw schema by describing the inference behavior for type.

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: 'Stage a token write' and specifies it adds or replaces a token at a path in a named set. It distinguishes itself from sibling tools like commit_and_push and delete_token.

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 that edits accumulate until calling commit_and_push, indicating when to use this tool as part of a staging workflow. It does not explicitly cover when not to use it or list alternatives, but the context is sufficient.

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 explains the tool reads context, scores tokens, and returns top N with reasoning. It implies a read-only operation, though it lacks explicit mention of side effects or safety, which is acceptable given the nature.

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, each earned: first states the core function, second provides usage guidance. It is front-loaded with the main action and contains zero redundant or vague language.

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 (5 parameters, no output schema), the description is incomplete. It omits details about parameter usage and return value structure. The tool likely needs parameter context for correct invocation, which is missing.

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

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

Schema coverage is 0% meaning no parameter descriptions. The description does not explain any of the five parameters (max, url, nodeId, fileKey, propertyKey). The tool requires understanding these fields, and the description provides no help, failing to compensate for the lacking 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 uses a specific verb ('Suggest'), identifies the resource ('tokens from the loaded catalog'), and specifies the context ('that fit a Figma node, ranked'). It clearly distinguishes from sibling tools like 'debug_resolve_token' by emphasizing ranking and reasoning.

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

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

The description explicitly states when to use this tool: when naming convention isn't obvious or when user says 'tokenize this'. This provides clear contextual guidance, though it does not discuss when not to use it or mention alternatives.

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