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

Annotations indicate destructiveHint: true, so the tool is known to be destructive. The description adds no further behavioral context (e.g., what gets destroyed, authorization needs, or side effects).

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

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

The description is a single sentence, which is concise. However, it lacks structure (no front-loading of key info or use of additional sentences to clarify details).

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

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

Given the destructive annotation, the description should explain implications (e.g., whether adding a mode is irreversible). No output schema exists, so return value expectations are missing. Incomplete for a mutation 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% (no parameter descriptions). The description does not explain the meaning, format, or constraints of collectionId or modeName beyond their 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?

The description 'Add a mode to a collection' clearly states the action and target resource. It distinguishes from siblings like figma_create_variable_collection and figma_rename_mode, though it lacks details about what a mode is in this context.

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

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

No guidance on when to use this tool versus alternatives (e.g., figma_rename_mode). No prerequisites (e.g., collection must exist) or exclusion conditions 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?

Annotations already indicate destructiveHint=true, so the description's burden is reduced. However, it does not clarify that original nodes are replaced or that the operation is irreversible beyond the annotation. Returns a nodeId but no detail on side effects.

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

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

Extremely concise: one sentence for purpose, one for params, no redundancy. Front-loaded with the core action.

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

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

For a simple tool with one parameter and an output schema hint, the description covers the essential use. Could mention where the new component set is created, but not critical given low complexity.

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

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

Schema coverage is 0%, so description must compensate. It adds that nodeIds should be 'component node IDs' (not generic strings) and requires at least 2, providing meaning beyond the schema's type definition.

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: combining multiple component nodes into a Figma component set, using the action 'combineAsVariants'. This is specific and differentiates 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?

No guidance on when to use this tool vs alternatives. While parameter constraints are mentioned, there is no explicit context for when to choose this over other component-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?

Annotations already mark destructiveHint=true. The description adds return format (created and failed lists) and max 100 items, enhancing transparency beyond annotations.

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

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

Two sentences: first states purpose and limit, second lists fields and return. 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?

Covers main functionality and return, but missing details on value formats per type and atomicity/partial failure 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?

With 0% schema coverage, description lists key fields but does not explain value format per resolvedType (e.g., RGBA for COLOR, number for FLOAT) or the optional valuesByMode.

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

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

The description clearly states the tool creates up to 100 variables in one call, lists required fields (collectionId, name, resolvedType, value, modeId), and distinguishes from siblings like figma_create_variable and figma_batch_update_variables.

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

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

The description implies use for batch creation, but does not explicitly state when to use over alternatives (e.g., figma_create_variable for single variable) or when not to use (e.g., for updates).

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 indicate destructiveHint=true, so the description correctly signals a write operation. It adds that up to 100 variables can be updated and that the response includes success/failure lists. No contradictions. Could mention behavior on errors.

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

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

Two concise sentences with no redundancy. Immediately states capacity and item structure, then return format. 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?

With one parameter (items array) and no output schema, the description covers usage and return format. Missing details like default modeId or validation rules, but adequate for a batch update 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 must compensate. It explains each item's structure (variableId, modeId, value) but does not define what these IDs refer to or how to obtain them. Medium helpfulness.

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 updates variables in batch, specifies the components of each item (variableId, modeId, value), and mentions return behavior (lists of updated and failed). This distinguishes it from single-update sibling figma_update_variable and batch-create sibling figma_batch_create_variables.

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

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

The description implies batch use for multiple variables but does not explicitly state when to use this tool versus figma_update_variable, nor does it provide prerequisites or exclusions. More guidance would help an agent decide.

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

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

The annotation already indicates destructiveHint: true, and the description adds value by disclosing internal methods (setBoundVariableForPaint, setBoundVariable) and explaining the dynamic update behavior when the design token changes. This goes beyond the annotation.

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 (3 sentences) and front-loaded with the main action. Each sentence adds essential information without redundancy. It efficiently covers the primary behavior, categories, prerequisite, and outcome.

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 moderate complexity and absence of an output schema, the description adequately covers the binding behavior, property categories, and dynamic updates. It could be improved by addressing error cases (e.g., invalid variable key) but overall is sufficiently 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?

Since schema description coverage is 100%, the description adds limited new meaning beyond the schema. It provides context for property categories (colors vs spacing) and references the prerequisite, but the core parameter semantics are fully covered by the schema.

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

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

The description clearly states the action ('import a library variable by key and bind it to a node property') and specifies the resource (node property). It distinguishes from sibling tools like figma_get_library_variables by explaining the prerequisite and from other variable manipulators by focusing on binding to properties.

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 mentions a prerequisite ('Get variableKey from figma_get_library_variables') but does not provide explicit guidance on when to use this tool versus alternatives (e.g., figma_update_variable or directly setting properties). It implicitly suggests usage for binding design tokens to node properties, but lacks 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?

Annotations declare readOnlyHint: true, which is consistent with taking screenshots. The description details behavioral traits like token cost for base64 (~30K tokens), automatic fallback to summary when context usage >80%, and region splitting strategies (children vs slices). This goes well beyond annotations.

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

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

The description is compact and front-loaded with the core concept. However, it mixes English and Turkish (e.g., 'dosyaya yazar, base64 context'te YOK') which may reduce clarity for non-Turkish agents. Still, every sentence provides value and it's structured logically.

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 only readOnlyHint annotation, the description comprehensively covers all modes, fallback behavior, region strategies, and parameter details. It is sufficient for an agent to correctly invoke the tool without additional context.

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

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

Despite 73% schema description coverage, the description adds crucial context for parameters like returnMode (explains each enum value beyond the schema description), regionStrategy (distinguishes children vs slices), and parameters like maxRegions, sliceHeight, requestedSlices—all clarified with concrete usage. The decision tree and token cost info are additive.

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 defines the tool as a screenshot capture tool with 4 return modes, distinguishing each mode's purpose. It goes beyond just stating the name by providing specific use contexts (planning, delivery, scroll screens) and contrasts with siblings through explicit mode selection guidance.

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 an explicit decision tree (planning→summary, delivery→file, scroll→regions, last resort→base64) and mentions context-aware fallback when context usage is high. This gives clear when-to-use and when-not-to-use guidance, fully addressing usage guidelines.

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 already mark the tool as read-only; the description adds context about the output categories and the optional parameter, without contradicting annotations.

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

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

The description is two sentences plus an example, directly stating purpose and parameters without extraneous 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?

The description covers all essential aspects: what the tool does, the optional parameter format, and the return categories, making it complete despite the lack of 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?

The schema has no description for the sole parameter, but the description provides a clear explanation and example of the expected JSON format, fully compensating.

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

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

The description clearly states the tool compares Figma and code tokens and returns categorized differences, which distinguishes it from sibling tools that manage individual tokens or variables.

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

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

The description labels the tool as critical for design-code gap analysis, implying its use case, but 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?

The description does not add behavioral context beyond the destructiveHint annotation. It does not explain irreversibility or side effects, but it does not contradict the annotation.

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, short sentence that is immediately understandable. It is front-loaded and uses no unnecessary words.

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

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

For a parameterless tool with no output schema, the description sufficiently explains the tool's purpose. It could mention return value or confirmation, but it is not strictly necessary.

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

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

There are no parameters, and the schema coverage is 100%. The description adds no parameter information, but none is needed.

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

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

The description clearly states the action 'clear' and the resource 'console log buffer'. It is distinct from sibling tools like figma_get_console_logs and figma_watch_console.

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 information is provided about when to use this tool or when to avoid it. No alternatives or conditions are mentioned.

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

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

No annotations are provided, so the description bears full burden. It mentions clearing from memory but omits side effects like impact on future API calls, reversibility, or required permissions.

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

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

The description is a single, concise sentence with no superfluous information, 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?

Given the tool's simplicity (no parameters, no output schema), the description adequately covers its purpose. However, a brief note on consequences would improve completeness.

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

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

With 0 parameters, the input schema inherently provides full coverage. The description adds minimal value beyond the schema, which is acceptable for parameter-free tools.

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 ('Clear the stored Figma REST API token from memory') with a specific verb and resource. It distinguishes from sibling tools like figma_set_rest_token and figma_get_rest_token_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 provides no guidance on when to use this tool versus alternatives, such as when clearing before setting a new token or implications of clearing authentication.

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 warns that cloning copies existing mistakes (hardcoded rectangles, missing token bindings, non-responsive layouts), adding behavioral insight beyond the annotations (destructiveHint: true). No contradiction with annotations.

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

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

The description is informative but somewhat lengthy. However, it is well-structured with a warning prefix, bullet-point-like conditions, and clear sections. Every sentence serves a purpose.

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

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

Given 7 parameters, no output schema, and only destructiveHint annotation, the description covers the critical use case, exclusions, and important behavioral notes. It could mention return behavior but is adequate for selection.

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

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

Schema coverage is 100% with good parameter descriptions. The tool description adds value by listing device presets and explaining targetDevice format, slightly improving clarity beyond the schema.

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

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

The description explicitly states the narrow use case: 'Device migration ONLY' to clone a Figma screen to a target device dimension, preserving library instances, bound variables, and auto-layout. It clearly distinguishes from figma_execute for creating alternatives, variations, or new designs.

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 conditions: 'USE ONLY WHEN: same design system + same layout structure + only screen size changes.' Specifies when NOT to use and directs to figma_execute + Step 5 for other cases, including specific keywords like 'alternatif', 'varyasyon', etc.

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

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

No annotations are present, so the description must fully cover behavioral aspects. It mentions auto-layout defaults and return value, but does not disclose idempotency, side effects, error conditions, or permissions. The version note is helpful but insufficient for complete transparency.

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

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

The description is concise: two sentences front-loaded with the core purpose. The version note is appended. No unnecessary words, but could be slightly better structured by separating version info into a note.

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

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

With no output schema and no annotations, the description must compensate. It covers core functionality and key defaults but lacks guidance on prerequisites (e.g., parentId context), error handling, and the many variable-related parameters. For a 23-parameter tool, this is incomplete.

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

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

Schema description coverage is 65%, meaning many parameters already have descriptions. The description adds overall context about defaults and versioning but does not elaborate on each parameter beyond what the schema already provides. It partially compensates for uncovered parameters by giving examples but not fully.

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 'Create a new frame node with optional auto-layout. Returns the created node ID.' This is a specific verb+resource combination that distinguishes it from sibling tools like figma_create_rectangle or figma_create_text. The mention of auto-layout and return value adds clarity.

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 version-specific defaults and mentions auto-layout vs legacy, but does not explicitly guide when to use this tool over alternatives (e.g., when to create a frame vs a group or rectangle). No direct comparison or context for selection.

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

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

No annotations provided, and the description does not disclose behavioral traits beyond the obvious creation. Missing details about side effects (e.g., node removal from original parent, positioning) or mutability.

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 filler. The core purpose is 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 simple tool with two parameters and no output schema, the description is adequate but lacks information about return values or how the group is created (e.g., location, parent). More context would help the agent understand the result.

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 50%; the description adds value for nodeIds ('Provide node IDs to group') but not for name parameter. It does not fully compensate for the coverage gap.

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

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

The description clearly states the action (group) and the resource (existing nodes), using specific verbs and nouns. It distinguishes from sibling tools like creating frames or rectangles.

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

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

No guidance on when to use this tool vs alternatives (e.g., figma_create_frame, figma_arrange_component_set). No prerequisites or exclusions mentioned.

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

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

With no annotations, the description provides key behavioral details: use of getMainComponentAsync for deprecation safety, schema constraint on SMART_ANIMATE (matchLayers not needed), and version limitations (v1, DirectionalTransition not applicable). It does not cover auth, rate limits, side effects like overwriting existing interactions, or return 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 concise at three sentences, front-loading the main purpose. Each sentence adds unique information (action, technical detail, version constraints) without redundancy or fluff.

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

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

Given 7 parameters and no output schema, the description covers the core functionality and some constraints but omits prerequisites (e.g., node must be part of a COMPONENT_SET), error handling, and what happens if no target variant is found. It is adequate for basic understanding but incomplete for full autonomy.

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 43%, so the description adds value: it clarifies targetVariantName resolution within COMPONENT_SET and explains the transitionType restriction. However, it does not elaborate on duration, easing, or trigger beyond schema basics. The description compensates moderately but not fully for the coverage gap.

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

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

The description clearly states it creates a variant state-change interaction on INSTANCE/variant nodes, specifying the mechanism (reactions API, CHANGE_TO) and constraints (target within same COMPONENT_SET). It distinguishes itself from general interaction tools by focusing on variants, but does not explicitly contrast with sibling tools like figma_create_prototype_connection.

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 variant interactions by specifying supported node types and transitions. However, it lacks explicit guidance on when to use this tool versus alternatives (e.g., figma_create_prototype_connection for screen-to-screen navigation) and does not mention 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?

Annotations set destructiveHint: true, and the description aligns by describing creation of many elements in one call. It adds behavioral context by listing what is created (colors, text styles, components) and notes that it works on a blank file. It could be more explicit about overwriting behavior, but given the blank file context, it 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 concise, using 3 sentences to convey purpose, usage condition, parameters, and result. Every sentence earns its place, and the most critical information (what the tool does) is front-loaded.

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

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

Given no output schema, the description provides a result structure ({ success, dsName, ... }) and suggests subsequent use of figma_execute. It explains the tool's role in a workflow. Could mention prerequisites (blank file) explicitly, but it is implied from the usage guideline.

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

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

Schema coverage is 100% with descriptions for all 6 parameters. The description reinforces defaults and meaning (e.g., primaryColor default, includeComponents effect) and adds result structure. While it adds some extra context, the schema already does adequate documentation, so score is baseline.

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

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

The description clearly states the tool creates a minimal design system for an empty Figma file, listing exactly what it creates (12 color variables, 8 sizing variables, 3 text styles, and components). It is distinct from atomic siblings like figma_create_variable or figma_create_frame, making its macro-purpose unambiguous.

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

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

The description specifies usage context: when the user selects 'Mini DS' in a 'Blank File 4-option dialog'. It also mentions a follow-up with figma_execute. However, it does not explicitly state when not to use or compare to alternatives beyond one sibling.

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 fully bears the burden of disclosing behavioral traits. It covers API methods used (setReactionsAsync), readonly restrictions (reactions property, overlay background), internal conversions (ms to seconds), and specific mapping details (INSTANT maps to null, matchLayers always injected for directional transitions). This level of detail meets the highest standard.

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, but every sentence adds value. It is front-loaded with the core purpose. While it could benefit from bullet points for readability, it avoids fluff and remains efficient given the parameter count.

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 high parameter count, the description covers scope limitations, API behavior, and mapping to Figma UI. It lacks explicit error handling or side effect info, but is otherwise thorough for a creation 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?

The description adds substantial meaning beyond the input schema. For example, it explains that BACK action ignores transition and auto-reverses direction, that INSTANT transition maps to null, and that matchLayers is invalid for SMART_ANIMATE. These insights are not derivable from the schema alone, and with 82% schema coverage, the description compensates well for any 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?

The description clearly states the tool's purpose: 'Create a prototype reaction between two nodes (source -> destination).' It maps to the Figma Prototype panel and enumerates trigger, action, and transition types, making the function highly specific and distinguishable from siblings. The explicit exclusion of certain actions (SET_VARIABLE, etc.) further clarifies scope.

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

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

The description provides implicit guidance on parameter requirements (e.g., direction for directional transitions, destinationNodeId for specific actions) and notes on limitation (readonly properties best configured in Figma UI). However, it does not explicitly state when to use this tool over siblings like figma_create_interaction, nor does it provide clear when-not-to-use 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, the description bears full weight but only states 'create' (mutation) without disclosing side effects, required permissions, or behavior like whether the rectangle is selected after creation. It adds minimal behavioral context beyond the obvious.

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

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

A single, front-loaded sentence that delivers the core purpose without extraneous words. Every word earns its place.

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

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

Despite having 8 parameters and no output schema or annotations, the description provides no information about return values, default behavior, error conditions, or interactions with the Figma page. It is severely incomplete for an agent to use effectively.

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

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

Schema description coverage is only 25% (only fillColor has a description). The description does not explain any parameters, defaults, or their relationships, leaving agents to infer meanings from schema names alone.

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 'Create a new rectangle node on the current page,' specifying the action (create), resource (rectangle node), and location (current page). This distinguishes it from sibling tools like figma_create_frame or figma_create_text.

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

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

No guidance on when to use this tool versus alternatives like figma_create_frame or figma_create_text. There is no mention of prerequisites, context, or scenarios where this tool is inappropriate.

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 fontFamily, return value, and suggests an alternative for DS text, which adds behavioral context beyond the basic action. However, it does not cover other important behaviors such as side effects (e.g., selection changes), permissions required, or error handling. Without annotations, more behavioral detail would be beneficial.

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

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

The description is concise with four sentences, each serving a purpose: stating the action and return, highlighting an important default, and providing an alternative. 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 the tool has 9 parameters, no output schema, and no annotations, the description covers the primary use case and important caveats but lacks details on many parameters and return format. It is adequate for basic usage but not comprehensive for all scenarios.

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

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

The description adds meaningful context for the fontFamily parameter by emphasizing its default and relation to design system fonts, and it hints at parentId by mentioning 'current page'. However, with only 56% schema coverage, the description does not compensate for undocumented parameters like x, y, fontSize, fillColor, and fontStyle, leaving significant 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?

The description clearly states the tool creates a new text node on the current page and returns the node ID. It differentiates from sibling tools like figma_create_frame and figma_create_rectangle by specifying the text node creation, and it explicitly mentions an alternative (figma_execute) for design system text with token binding, which further distinguishes its intended use.

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 explicit guidance on when to use this tool (creating simple text nodes) and when to use an alternative ('For DS text with proper token binding, prefer figma_execute...'). It also advises to specify the DS font from active-ds.md when using a design system, offering clear context for correct 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?

The annotations already indicate destructiveHint=true, alerting the agent to creation. The description adds no further behavioral details (e.g., error handling, idempotency, or permissions), so it meets the baseline but provides no extra value.

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 very short (two sentences) and front-loaded, but the brevity sacrifices necessary detail. It is concise but not optimally 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?

Given the tool has 4 parameters, one nested object, and no output schema, the description is too sparse. It lacks explanation of parameter semantics, return values, and usage context, leaving significant gaps for the agent.

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

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

The schema description coverage is 0%, meaning no parameter descriptions exist in the schema. The description only mentions collectionId indirectly; it does not explain name, resolvedType, or options. This is insufficient for a 4-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 explicitly states 'Create a variable in a collection,' clearly identifying the verb and resource. It also hints at how to obtain the collectionId, which distinguishes it from sibling tools like figma_create_variable_collection.

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 specific usage hint ('Get collectionId from figma_get_variables') but does not explicitly state when to avoid this tool or mention alternatives like figma_batch_create_variables. However, the context is clear for a single variable creation.

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 annotation destructiveHint:true suggests the tool may modify or delete data, but the description merely says 'Create', which is typically additive. The description does not explain the destructive behavior, such as whether creation overwrites existing collections or affects other data. This leaves ambiguity.

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

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

The description is a single sentence, making it concise. However, it sacrifices essential information, resulting in an under-specified tool definition that fails to provide adequate guidance.

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 presence of sibling tools and lack of output schema, the description is incomplete. It does not explain what a variable collection is, its relationship to variables, or the outcome of creation. The agent is left without enough context 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?

The input schema has 2 parameters (name, options) with 0% description coverage. The description does not explain what 'name' represents or what 'options' can contain. For a creation tool, this is insufficient; the agent cannot determine how to populate the parameters.

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

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

The description clearly states the action 'Create' and the resource 'variable collection', matching the tool name. However, it does not differentiate from sibling tools like figma_create_variable or figma_batch_create_variables, leaving ambiguity about what a variable collection is.

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

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

The description provides no guidance on when to use this tool versus alternatives such as figma_create_variable or when not to use it. No context about prerequisites or suitability is given.

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

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

Annotations already provide destructiveHint=true, so description 'Delete a variable.' adds no new behavioral information. Missing details like whether deletion is reversible or what happens to variable references.

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, efficient and to the point. No unnecessary words, though some added context could be beneficial without harming 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?

For a simple delete tool with one parameter and no output schema, the description is minimal but lacks essential context like irreversibility, prerequisite variable existence, or relationship to collections. The agent may proceed with incomplete understanding.

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

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

Schema coverage is 0%, yet description adds no explanation for the 'variableId' parameter. The parameter name is somewhat self-explanatory, but no format or source guidance is given, making it hard for the agent to know how to obtain a valid ID.

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 'Delete a variable.' clearly states the action and resource, and distinguishes from sibling tools like 'create_variable' or 'rename_variable'. However, it lacks specificity about what a variable refers to in Figma context.

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

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

No guidance on when to use this tool versus alternatives. For example, it doesn't mention that variables belong to collections or when to use 'delete_variable_collection' instead. Agent must infer usage from name alone.

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

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

Annotations provide destructiveHint=true, so the agent knows it's destructive. However, the description adds no additional behavioral details (e.g., irreversibility, side effects on contained variables, error conditions). It merely restates the action.

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

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

A single sentence with no unnecessary words, but it borders on underspecification. Concise yet lacking essential context.

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

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

For a simple deletion tool, the description is incomplete: no mention of behavior, side effects, or expected input format. Even with annotations, the agent lacks guidance on safe usage.

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

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

Schema coverage is 0% (no description on collectionId). The description provides zero parameter information—no format, example, or constraints—leaving the agent to guess the required 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?

Clearly states it deletes a variable collection, distinguishing from sibling tools like figma_delete_variable (deletes a variable) and figma_create_variable_collection (creates). The verb-resource pair is specific and unambiguous.

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

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

No guidance on when to use this tool vs. alternatives, or any prerequisites (e.g., collection must exist, cannot delete if in use). The agent receives no context for correct invocation.

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 already declare readOnlyHint=true and destructiveHint=false. Description adds that it is 'LIVE', 'always fresh', and 'zero local cache dependency', providing useful behavioral context beyond the annotations. However, it does not discuss performance, error scenarios, 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 paragraph but well-structured: action statement, prerequisite, return format, parameter tips, and usage scenario. It is concise with no superfluous information, though could benefit from bullet points for clarity.

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 describes return items and fields. It covers prerequisites and multi-library usage. Absence of pagination or limit info is acceptable for a live enumeration tool. Overall, it provides sufficient context for agent 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 description coverage is 100%, so the baseline is 3. The description reinforces the parameter matching behavior and references figma_list_connected_files for context, but does not add significant new information beyond the 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 enumerates all published components and component sets from a library Figma file. Specifies return format and distinguishes between component and component set kinds. However, it does not explicitly differentiate from the sibling tool 'figma_enumerate_published_components', leaving some 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?

Provides explicit prerequisite: library file must be open in FMCP plugin, and references figma_list_connected_files for setup. Offers guidance on using libraryName vs libraryFileKey parameters and multi-library usage. Does not specify when NOT to use this tool or mention alternatives, but covers key usage context well.

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 indicate readOnlyHint=true and destructiveHint=false. The description adds valuable context: response shape is compact by default, descriptions stripped to keep <10KB, and large libraries (1000+) require filter to avoid overflow. 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?

Single paragraph, front-loaded with purpose, no wasted words. Every sentence adds value. Efficient 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?

Despite no output schema, the description explains response shape and version (v3.4+). Covers all key aspects: purpose, usage, parameters, limitations. Very complete for this 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% with decent descriptions. The description adds extra meaning: explains limit hard cap (500), filter's substring nature, libraryFileKey extraction, and includeDescription warning about length. Adds value 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?

The description uses a specific verb ('List') and resource ('published COMPONENT + COMPONENT_SET of a library via the Figma REST API'), clearly distinguishing it from siblings like figma_enumerate_library_components. It also notes the tool works without the library file being open.

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 library is subscribed but tabs aren't open. Mentions prerequisite (figma_set_rest_token) and gives guidance for large libraries (use filter). Lacks explicit alternatives but still 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?

Annotations only provide destructiveHint: true. The description extensively discloses behavioral traits: static analysis for design-system violations (with SEVERE warnings promoted), gotchas (FILL/ABSOLUTE before appendChild, sync API usage, loadFontAsync), and post-execute scanning for unbound properties that can invalidate execution. This far exceeds the annotations.

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

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

The description is relatively long but well-structured with version markers (v1.8.1+, v1.9.6+), bullet-like lists (gotchas), and clear separation of concerns (execution, static analysis, post-execute scan). A few sentences could be trimmed (e.g., Turkish text for post-execute scan) but overall efficient for the 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 tool's complexity (code execution, scanning, design-system checks), the description is remarkably complete. It covers version-specific behaviors, error handling (SEVERE warnings, POST_EXECUTE_SCAN_BLOCKING), and practical gotchas. No output schema exists, but the description explains expected response additions (_designSystemViolations, _postExecuteScanBlocking, etc.).

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% (2/4 params have descriptions: figmaUrl and fileKey). The description adds valuable context for code (main script), timeout (default 15000ms), and the interplay between fileKey and figmaUrl. It compensates for missing schema descriptions by explaining 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 runs JavaScript in Figma plugin context with full API access, using fileKey or figmaUrl to target files. It distinguishes from sibling tools (e.g., figma_create_frame, figma_get_variables) by its execution nature and unique side-effects like design-system violation detection.

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 explicit context: when to use (run JS), how to target (fileKey/figmaUrl), and key behaviors (static analysis, post-execute scan). However, it does not explicitly state when not to use the tool or compare it directly to alternatives like figma_plugin_diagnostics or figma_scan_ds_compliance, which might overlap.

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 return format (base64), format-specific behavior (SVG preserves vectors, PNG/JPG rasterize), and scale version change (v1.8.0 default scale=1 for safety). It could mention if any side effects occur, but as an export tool, it is likely read-only.

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, consisting of 4 sentences front-loaded with the main action. Each sentence adds distinct information (formats, batching, authentication, format details, version history) 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 tool's complexity (5 parameters, 1 required) and no output schema, the description covers key aspects: formats, batch, scale, version note, and return type (base64). It omits error handling or performance details, but for an export tool the information is sufficient.

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

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

Schema coverage is 100% but description adds significant value: explains format differences, batch limit (max 50), default scale reasoning (context safety override), and SVG-specific parameters (outline text, include id). This enriches understanding beyond schema names and descriptions.

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

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

The description clearly states the tool exports nodes in SVG, PNG, JPG, or PDF formats, returns base64 data, and supports batch export up to 50 nodes. It uniquely identifies the tool's purpose among siblings, which include creation, modification, and retrieval tools but no other export tool.

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 indicates when to use the tool (exporting nodes) and provides context like 'no REST API token needed' and 'uses plugin exportAsync'. It does not explicitly state when not to use it, but given no sibling tools offer similar functionality, the guidance 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?

Annotations declare readOnlyHint=true, and the description aligns with that by saying 'Reads' and 'no REST API', so no contradiction. It adds significant behavioral context: the tool falls back to the current Figma selection when nodeId is omitted, returns a structured { success, contract, report } object, and flags that the contract status is 'draft' with anchors.code requiring manual verification. These details go well beyond the annotation and are crucial for correct invocation and interpretation.

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 paragraph of about 80 words, but every sentence contributes value: it lists the extracted data, the selection fallback, the return shape, the draft status, and the use cases. It is front-loaded with the core purpose ('Extract a complete design contract JSON spec'). For a tool of this complexity, the length is appropriate, though it could be slightly more scannable with bullet points.

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

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

The tool is complex with no output schema, yet the description covers the key aspects: the input node type, the data sections included, the top-level return shape, the contract status caveat, and the intended use cases. It does not describe the internal structure of each section (e.g., anatomy), but the enumerated list of sections gives an agent enough to know what to expect. Given the read-only annotation and the rich description, it is quite complete but not exhaustive.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning for one parameter by explicitly stating 'nodeId omitted → current Figma selection', which clarifies the optionality and behavior beyond the schema description. It also mentions the importPathTemplate default indirectly via 'anchors.code.importPath template', but that is already in the schema. Overall, it provides meaningful augmentation, justifying a 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 a specific verb ('Extract') and a precise resource ('a complete design contract JSON spec from a COMPONENT_SET'). It enumerates the exact data read (props, anatomy, variantOverrides, resolvedTokens, baseSpecs, a11y pairs), which distinguishes it from sibling tools like figma_get_component_for_development or figma_get_design_context. The mention of 'DS-agnostic; no REST API' further differentiates it from figma_rest_api.

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 provides use cases: 'design-to-code handoff, DS documentation, or as the source of truth for component codegen.' This gives clear context for when to employ the tool. It does not explicitly name alternative tools to use instead for other scenarios, but the use-case framing is sufficiently informative for an agent to decide.

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

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

Annotations declare readOnlyHint=true, consistent with 'get' operation. Description adds beyond annotations: notes that only plugin-accessible hints are returned, not the full source map. Discloses limitation clearly. No contradiction.

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 plus a short note. Front-loads key information: what it returns and alternatives. Every sentence adds value. No redundancy.

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

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

Given no output schema, description sufficiently covers return fields (documentationLinks, componentKey, name, description). Explains both usage modes (nodeIds vs scanCurrentPage). With 5 parameters and no output schema, the description is complete and leaves no ambiguity.

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

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

Schema coverage is 100% with explicit descriptions, but description adds value: explains scanCurrentPage scans for COMPONENT/COMPONENT_SET/INSTANCE nodes and mentions maxNodes default (40) and cap (120). Does not explain figmaUrl/fileKey beyond schema, but these are straightforward. Adds meaningful context.

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

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

Description clearly states the tool returns Code Connect hints for components/instances, listing specific fields. It distinguishes itself from sibling tools like figma_get_component and mentions alternative sources (figma.config/CLI, official MCP). Verb+resource+scope is specific.

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

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

Explicitly states when to use this tool (get hints) and what it does not cover (full source map). Provides alternative: 'Use Figma's official MCP get_code_connect_map for native repo paths.' Clear guidance on when-not-to-use.

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

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

Annotations already declare readOnlyHint=true, and the description confirms read behavior. Adds context with 'No REST API' indicating it's a local plugin call, but does not detail error handling or edge cases.

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. Efficient 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 read-only annotations and simple purpose, the description covers targeting and basic usage. Lacks return format details but is complete enough for a straightforward tool.

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

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

Schema description coverage is 67% (2 of 3 parameters described). Description adds context that figmaUrl and fileKey are for targeting, but nodeId (required) lacks schema description and relies on the description's implication.

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 (Get), resource (component metadata by node ID), and scope (from open Figma file). Distinguishes from siblings by noting 'No REST API' and targeting nuances.

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 context for when to use (get metadata by node ID) and targeting options (fileKey/figmaUrl), but lacks explicit when-not-to-use or comparison with similar siblings like figma_get_component_for_development or figma_get_component_image.

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 indicate readOnlyHint=true, and the description adds the default behavior specifics: 'Defaults to JPG@1x q70 (v1.8.0 context-safe).' This goes beyond annotations by disclosing default format, scale, quality, and version safety, fully informing the agent of 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 extremely concise with two sentences. It front-loades the purpose and immediately provides key details. Every word earns its place, with 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 tool's moderate complexity (4 parameters, no output schema), the description covers the main purpose and default behavior. However, it could be more complete by briefly explaining the metadata fields or indicating the screenshot format details. Still, it is adequate for an agent to understand the core function.

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 description coverage is 0%, so the description must compensate. The description provides default values for format, scale, and quality, but does not explain the meaning or usage of each parameter (e.g., nodeId, scale, format, jpegQuality). This adds some value but is insufficient to fully compensate for the lack of parameter descriptions.

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

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

The description clearly states that the tool retrieves component metadata and a base64 screenshot in one call, specifying its use for design-to-code workflows. This distinguishes it from sibling tools like figma_get_component and figma_get_component_image, which handle these tasks separately.

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 'For design-to-code workflows,' providing clear context for when to use this tool. However, it does not explicitly mention when not to use it or list alternative tools, but the use case is well-defined.

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 declare readOnlyHint=true, consistent with description. Description adds value by disclosing default format, scale, and quality, which informs agent of expected 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?

Two concise sentences, front-loaded with purpose, followed by key default and targeting information. No unnecessary words.

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

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

With 6 parameters, no output schema, and low schema coverage, the description omits important details such as nodeId requirement, parameter constraints, and how the base64 output should be used. Incomplete for guiding correct 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 low (33%), but description only mentions fileKey and figmaUrl without detailing other parameters like nodeId (required) or scale/format. Defaults are stated but not explicitly linked to schema parameters.

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

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

Clearly states 'Get screenshot of a node (component/frame)' with return type 'base64 image'. However, does not distinguish from sibling tool 'figma_capture_screenshot', which likely performs a similar function.

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 context on defaults (JPG@1x q70) and targeting specific files via fileKey or figmaUrl. Lacks explicit when-to-use or when-not-to-use guidance relative to siblings.

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

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

Annotations declare readOnlyHint=true. Description adds that it uses no CDP, default limit 50, and targeting options. No contradictions, and extra context provided.

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

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

Three sentences, each adding distinct value: purpose, technical note (No CDP), and usage details. No fluff, 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?

Adequate for a read-only fetch with no required params. Missing output format description since no output schema, but not critical. Overall complete for usage.

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

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

Schema describes fileKey and figmaUrl, but description adds 'Limit default 50' and clarifies targeting for multiple plugins. Schema coverage 67%, but description compensates for limit parameter.

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 'Get plugin console logs (log/warn/error) from the F-MCP plugin buffer', specifying the verb, resource, and log types. It distinguishes from siblings like figma_clear_console and figma_watch_console.

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 guidance on when to use fileKey or figmaUrl for targeting specific files. However, it does not explicitly contrast with alternatives like figma_watch_console, though the purpose 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?

Disclosures caching behavior (60s per session) and safe defaults. The debug parameter to bypass cache is mentioned. Annotations (readOnlyHint) are consistent. 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?

Three concise sentences: purpose, defaults/safety, and explicit overrides + caching. Front-loaded with no wasted words.

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

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

Given 12 parameters and no output schema, the description covers core purpose and key defaults but omits details on many optional parameters and the structure of the response. Incomplete for a full 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 low (33%). Description adds meaning for depth, verbosity, and caching, but many parameters (includeLayout, includeVisual, includeTypography, includeCodeReady, outputHint) remain unexplained. This partially compensates but not fully.

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

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

The description clearly states the tool retrieves design context including structure, text, layout, visual, and typography for a node or whole file. It distinguishes from siblings specializing in specific data like components or file data.

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 guidance on default depth and verbosity for context safety, and recommends explicit overrides for deeper data. Caching info is also given. However, it lacks explicit when-not-to-use or alternatives among siblings.

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

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

Annotations already mark readOnlyHint=true. Description adds that it is 'compact' and 'minimal tokens', which informs agent behavior. No contradictions. Could mention error cases or rate limits, but sufficient for a read-only 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?

Description is concise (around 50 words) and front-loaded with key action. Includes pre-flight and a negative usage case. Every sentence adds value, though formatting could be slightly more structured.

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

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

Covers purpose, parameters, and usage guidance. Lacks explicit return format or effect description, but for a minimal read-only overview with no output schema, it is reasonably complete given low complexity.

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

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

Schema coverage is 50% (limit and currentPageOnly lack schema descriptions). Description clarifies fileKey and figmaUrl usage ('target a specific file'), but does not explain limit or currentPageOnly parameters, leaving 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?

Description clearly states it provides a compact overview with specific content (variable collection names and component counts). Distinguishes from sibling tools by being a summary rather than detailed variable/component retrieval.

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 when to target a specific file via fileKey/figmaUrl, and gives pre-flight instructions including reading specific files before calling. Also explicitly states when NOT to call (if DS identity known, use cache instead of empty target file).

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

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

The description adds behavioral details beyond the annotation (readOnlyHint=true), such as caching (60s per session) and default parameter values. It aligns with the annotation, reinforcing the non-destructive, read-only 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 concise (4 sentences) and front-loads the main purpose. It efficiently covers key points without redundancy, though it could be slightly more structured with bullet points for defaults.

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 (10 parameters, no output schema), the description lacks details about the return format (document tree structure) and how parameters affect it. The caching behavior is mentioned, but the overall output shape is unclear.

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 30% schema coverage, the description partially compensates by explaining fileKey/figmaUrl and defaults for depth and verbosity. However, it omits explanations for the six boolean include parameters and outputHint, leaving 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 action ('Get file structure and document tree'), specifies the resource ('the open Figma file'), and distinguishes it from sibling tools by highlighting its read-only nature and the use of fileKey/figmaUrl for multi-file scenarios.

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 guidance on when to use fileKey vs figmaUrl ('when multiple plugins are connected') and notes default values. However, it does not explicitly advise against using this tool in other contexts 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?

Beyond the readOnlyHint annotation, the description discloses the API used (figma.teamLibrary), the scope (target file, no need to connect DS source), and the return fields (variable name, key, resolvedType, collection, library name). It also documents the pre-flight caching behavior, providing rich behavioral context.

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

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

The description is fairly concise but packed with useful information, front-loaded with purpose, followed by usage guidance and caching instructions. Every sentence adds value, though it could be slightly more terse without losing meaning.

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 compensates by listing the return fields and explaining the caching flow. It provides complete guidance for a read-only list tool, covering what the tool returns and when to use it.

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

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

Schema description coverage is 100%, so all parameters are already described in the schema. The description does not add new semantic information about parameters beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists variables from team library collections with import keys, using a specific API, and distinguishes it from sibling tools like figma_get_variables by emphasizing it works in the target file without needing the DS source file.

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 on when to use this tool (cache miss or stale) and when to use a cache instead, along with instructions on using the returned keys with other tools (figma_bind_variable, figma.variables.importVariableByKeyAsync). This clearly differentiates from 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?

Annotations declare readOnlyHint=true, and the description reinforces 'Read-only audit'. It adds implementation details (getReactionsAsync, fallback) and lists returned fields, providing transparency beyond annotations.

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

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

Four sentences, well-structured with purpose first. Every sentence adds value, though it could be slightly more concise. 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 lists the fields returned (trigger, action, etc.) and explains the two scanning methods. It is complete for a read-only audit 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 80%, and the description adds meaning to the interplay between nodeId and pageScope, and clarifies the default for includeFlowStartingPoints. It adds value beyond the 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 reads prototype reactions on a node subtree or the whole current page, using specific verbs like 'Read' and 'returns'. It distinguishes from siblings like figma_create_prototype_connection, which creates connections.

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

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

The description explains when to use nodeId vs pageScope, and that at least one is required. It provides clear context for usage but does not explicitly state when not to use this tool or compare to alternatives beyond the 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?

Annotations already declare readOnlyHint: true, covering the safety profile. The description adds context about checking token status and rate limits but does not disclose details like response format or error behavior. Minimal added value beyond annotations.

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

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

Single sentence, front-loaded with the verb and resource, zero wasted words. Highly concise and structured effectively.

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

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

Given no parameters and high schema coverage, the description is adequate but does not specify what exactly is returned (e.g., boolean for token set status, rate limit numbers). With no output schema, this gap reduces 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?

No parameters exist, so baseline 4 applies. The description is sufficient as there are no parameter semantics to supplement.

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 specific verbs 'Check' and 'view' with clear resources 'Figma REST API token status' and 'rate limit usage'. It clearly distinguishes from siblings like figma_set_rest_token and figma_clear_rest_token by focusing on status inspection.

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 purpose is inferred from the description and sibling names, but there is no statement of when-not-to-use or prerequisites. Adequate but lacks explicit boundaries.

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 indicate readOnlyHint=true, so the description's claim of non-destructive listing aligns. It adds the important constraint 'No REST API or token' which differentiates it from other tools, but does not disclose return format or behavior details.

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

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

Two sentences: first states purpose, second adds a key constraint. No filler, front-loaded with essential information.

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

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

Given no output schema, the description fails to specify what 'list all connected files' returns (e.g., file names, IDs, or full objects). Ambiguity about the boolean check for plugin connection. Adequate for a simple tool but lacks clarity on return value.

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?

Tool has zero parameters, so schema coverage is complete. Baseline of 4 is appropriate as no additional parameter information 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 checks plugin connection and lists connected files. However, it does not distinguish from sibling 'figma_list_connected_files' which likely overlaps in functionality.

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

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

No guidance on when to use this tool versus alternatives like 'figma_list_connected_files' or 'figma_get_rest_token_status'. No prerequisites or context provided.

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

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

The annotations already declare readOnlyHint=true, so the read-only nature is clear. The description adds that it operates on 'local' styles and 'No REST API', which provides context beyond annotations. However, it does not disclose any additional behavioral traits like what happens if the file is not open or performance implications. The description is adequate but not extensive.

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: first states purpose, second provides targeting context and distinguishes from REST API. Every word is necessary, no fluff. It is front-loaded and appropriately sized.

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

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

Given the tool's simplicity (3 parameters, no output schema, annotations present), the description covers the essential aspects: what it does (get styles), targeting options, and operational context (local, not REST). It does not describe return values, but the tool name implies style objects. For a read-only retrieval tool, this is nearly complete.

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

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

The input schema has high coverage with descriptions for all three parameters (figmaUrl, fileKey, verbosity). The description adds 'Use fileKey or figmaUrl to target a specific file,' which is redundant with schema descriptions. For high schema coverage, a baseline of 3 is appropriate as the description adds minimal new meaning.

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

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

The description clearly states the tool retrieves local paint, text, and effect styles from the open Figma file. It specifies the resource ('styles') and the action ('get'). The mention of 'No REST API' helps differentiate from other tools like 'figma_rest_api', and 'Use fileKey or figmaUrl' clarifies targeting. This provides specific verb+resource and distinguishes from siblings.

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 the open Figma file and mentions that fileKey or figmaUrl can target a specific file. However, it does not explicitly state when not to use this tool or provide alternative tools for similar purposes (e.g., 'figma_get_variables' for variables). The guidance is implied but not 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?

Annotations indicate readOnlyHint=true, which is consistent with the description. The description adds that it returns specific data types (variable collections, variables, modes, paint/text styles) and notes it uses no REST API, providing additional context beyond annotations.

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

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

The description is two sentences long, front-loading the purpose and then providing usage guidance. 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?

Given the tool has three parameters with relatively straightforward semantics and no output schema, the description provides enough context about the tool's function and return types. However, elaborating on the hierarchical structure or the verbosity options would improve completeness.

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

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

The schema covers two of three parameters with descriptions (fileKey, figmaUrl). The description adds that these are used to target a specific file, but does not explain the verbosity parameter (enum: summary/full). Since schema coverage is 67%, the description modestly compensates but could be more informative.

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

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

The description states it returns a hierarchical view of design tokens, including variable collections, variables, modes, and paint/text styles. However, it could more explicitly distinguish itself from closely related siblings like figma_get_variables and figma_get_styles.

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

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

The description suggests using it for exploring and auditing tokens, and specifies using fileKey or figmaUrl for targeting files when multiple plugins are connected. It does not provide explicit alternatives or conditions for when not to use this tool.

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

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

Annotations already declare readOnlyHint=true; description adds context about no REST API/token needed and that it works on the open Figma file, providing useful behavioral cues.

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 the purpose front-loaded; no unnecessary words.

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

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

For a simple read-only tool with annotations, the description covers purpose, targeting, and a key behavioral trait. Missing return details but not required per rules.

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 67% (2 of 3 parameters described). The description reinforces the parameter usage but does not add new semantic information 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 'Get design tokens and variables' as a verb+resource, and distinguishes itself from sibling tools that perform write operations or retrieve other entities.

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 guidance on using fileKey or figmaUrl for targeting specific files, but does not explicitly compare with other get tools or state when not to use it.

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

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

Annotations already mark destructiveHint=true, so the bar is lower. The description adds behavioral details: it imports from published libraries, and for different style types it applies via specific methods (setTextStyleIdAsync, fillStyleId, effectStyleId). It does not elaborate on side effects or reversibility, but adds useful context beyond the annotation.

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 structured with a clear purpose sentence, an important note, guidance on obtaining keys, and a breakdown by style type. It is informative but somewhat lengthy; however, every sentence adds value and the structure is logical.

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 does not explain the return value or success/failure indicators. It covers the tool's purpose, usage constraints, and parameter details well, but lacks information on what the tool outputs, which is important for an agent to handle the result.

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

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

Schema coverage is 100% with descriptions. The description adds meaning beyond the schema by explaining how to obtain styleKey (from cache or REST API) and detailing how each style type is applied. This provides actionable context for 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 the verb 'import' and the resource 'style from a team library', with optional application to a node. It distinguishes from siblings like figma_get_styles by focusing on importing and applying from published libraries.

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 that this tool only works with published library styles, not local file styles, and provides alternative methods for local styles via figma_execute. Also guides on obtaining style keys from cache or REST API, giving clear when-to-use and when-not-to-use 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?

Beyond the destructiveHint annotation, the description explicitly states it creates an instance and supports both library and local components. Also warns about modifying instance text incorrectly, adding valuable behavioral context.

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

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

Two sentences, front-loaded with purpose, no redundant information. Every sentence adds value, making it efficient and easy to parse.

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

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

Given no output schema and moderate complexity, the description covers creation flow and a key post-creation instruction. However, it omits details for sub-parameters like position and parentId, and does not describe return value or errors. Somewhat incomplete for a comprehensive understanding.

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

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

The input schema has 0% description coverage, so the description carries the burden. It explains componentKey's source and links overrides to setProperties, but does not elaborate on nodeId, position, or parentId. Partially compensates but leaves 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 'Create a component instance' with specific verb and resource. Mentions key sources from sibling tools, distinguishing it from search or other creation tools. No 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?

Provides clear guidance on obtaining componentKey from specific tools and warns against using findAll(TEXT) after creation. Does not explicitly state when not to use, but context is sufficient for an AI agent.

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 already declare readOnlyHint=true, so the description's 'List' aligns. It adds value by describing the return values (fileKey, fileName, connection time) and confirms no destructive 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?

Three sentences, no filler. First sentence states purpose and output, second gives usage context, third explains chaining. Front-loaded and efficient.

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

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

For a simple list tool with no parameters and no output schema, the description covers all essential information: what it does, what it returns, when to use it, and how to use the output. No 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?

Tool has zero parameters, so baseline is 4 per guidelines. The description does not add parameter semantics beyond the schema (which is empty), but it appropriately explains how to use the output with other tools.

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 verb 'list' and the resource 'connected Figma/FigJam plugin instances', and details the returned fields (fileKey, fileName, connection time). This distinguishes it from sibling tools that modify or create entities.

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 suggests using the tool 'when multiple windows or agents are active' and explains how to chain the output (fileKey or figmaUrl) with other tools. It does not explicitly state when not to use, but the guidance is clear and useful.

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 indicate read-only (readOnlyHint: true). The description adds specific behavioral details (uptime, connected clients, pending requests, bridge version, memory usage) that go beyond the annotation, providing a clear picture of the tool's output.

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

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

The description is a single sentence that efficiently lists the key diagnostic fields, with no fluff. It is front-loaded with the action and resource.

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 the tool's return value with specific metrics. No additional context is needed for a simple diagnostic retrieval 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?

The tool has zero parameters, so the schema fully covers them. The description adds value by explaining what the tool returns, compensating for the lack of an output schema. Baseline score of 4 applies.

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

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

The description uses a specific verb ('Get') and resource ('diagnostic info about plugin connection health'), listing exact metrics. It clearly distinguishes from sibling tools that focus on editing, creating, or retrieving design data.

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

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

The description implies the tool is for checking connection health, but it does not explicitly state when to use it versus other diagnostic tools (e.g., figma_get_status) or provide any when-not-to-use 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?

Annotations indicate the tool is neither read-only nor destructive, but the description fails to explain the behavioral implications of 'refresh.' It does not disclose side effects, permissions, or what changes occur, leaving the agent uninformed.

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

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

The description is a single sentence with no unnecessary words. It is maximally 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?

Despite no parameters or output schema, the description is too vague given the context of many variable-related sibling tools. It does not specify how 'refresh' differs from other operations, making it incomplete for proper selection.

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, so the description does not need to elaborate on them. The baseline for zero parameters is 4, and the description adequately conveys the action and resource.

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

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

The description states 'Refresh variables from the file,' which combines a verb and resource but lacks specificity on what 'refresh' entails. It does not differentiate from sibling tools like figma_get_variables or figma_update_variable, leaving 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 no guidance on when to use this tool versus alternatives or when not to use it. No context or prerequisites are mentioned.

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

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

The destructiveHint annotation indicates this operation may have side effects, but the description does not elaborate on what those are (e.g., breaking references). Without additional context, the agent cannot assess risks.

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

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

The description is extremely concise—just one sentence. It is front-loaded and to the point, but the lack of structure or elaboration for a destructive operation makes it less helpful.

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 destructive hint and three required parameters with no output schema, the description is insufficient. It does not explain the renaming process, potential impacts, or return value, leaving significant gaps for an agent.

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

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

With 0% schema description coverage, the description should explain the parameters. It does not; the parameter names (collectionId, modeId, newName) are only partially self-explanatory, and the tool's behavior with these IDs remains unclear.

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 (rename) and object (mode in a collection). It is concise and unambiguous, though it could benefit from specifying what a mode is in the context of Figma collections.

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

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

No guidance is provided on when to use this tool versus alternatives like figma_add_mode or figma_rename_variable. The description lacks context for appropriate usage scenarios.

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

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

The description provides no behavioral details beyond the action. The annotation 'destructiveHint: true' is present, but the description does not explain the nature of the destructiveness (e.g., irreversible, affects references). No contradiction with annotations.

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

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

The description is extremely short, but this is under-specification rather than conciseness. It lacks essential details about usage and behavior, making it too minimal.

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 lack of output schema, the description is incomplete. It does not specify return values, side effects, or how renaming relates to other variable operations. The context from siblings is not leveraged.

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 should explain the two parameters (variableId, newName). It only says 'Rename a variable,' adding no semantic meaning to the parameters.

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

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

The description 'Rename a variable' clearly states the action and resource. However, it does not distinguish from the sibling tool 'figma_update_variable', which might also perform renaming. The purpose is clear but lacks differentiation.

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

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

No guidance is provided on when to use this tool versus alternatives like 'figma_update_variable' or other variable-related tools. There is no mention of prerequisites or context for renaming.

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?

Description adds behavioral details beyond annotations, such as requiring a token and supporting API operations. Annotations already indicate non-read-only nature, so description builds on that.

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?

Extremely concise, two sentences with examples. Every part is informative and front-loaded.

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

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

Given no output schema, description covers main aspects but lacks details on return values. However, it provides sufficient context for an API 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% and description provides endpoint examples but adds little beyond schema. Baseline 3 is appropriate.

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

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

The description clearly states 'Call Figma REST API directly' with specific use cases like file export, comments, version history, and distinguishes from sibling tools by mentioning 'anything not available through the plugin bridge'.

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 (e.g., file export, comments) and prerequisite (requires token via figma_set_rest_token). Lacks explicit alternatives but gives good 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?

Explicitly declares 'Read-only — never mutates the file', consistent with annotations. Discloses threshold behavior and return value structure (samples, overflow). 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?

Concise yet detailed, uses numbered list for clarity, front-loads purpose. Every sentence adds value with 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?

Covers tool purpose, behavior, return data (including samples and overflow), and usage instructions. No output schema needed given comprehensive description.

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 covers all 5 parameters with descriptions. Description adds minimal extra value (e.g., default threshold, expectedDs purpose). Baseline 3 is appropriate as schema does the heavy lifting.

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

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

Description clearly states it performs a 'Full DS compliance scan for a completed screen' and lists specific return values (coverage, samples, overflow). It distinguishes from sibling figma_validate_screen by noting stricter threshold and granular gaps.

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?

States it's a 'FINAL GATE' for completed screens and instructs Claude to fix violations if passed: false. Implicitly differentiates from validate_screen via default threshold (85 vs 80). Lacks 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?

Annotations mark the tool as readOnlyHint=true. The description goes far beyond by detailing how library components are discovered (via instance scanning), version-specific behavior (v1.8.0+, v1.9.8+), the prerequisite of at least one DS instance, and the fallback hint mechanism. No contradictions with annotations.

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

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

The description is moderately verbose, especially with version-specific details (v1.8.0+, v1.9.8+) embedded in a single paragraph. It front-loads the main purpose but becomes dense. While all information is useful, some restructuring (e.g., bullet points or separate version notes) could improve 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 the tool's complexity (three asset types, six parameters, version dependencies, and no output schema), the description covers all necessary context: return types, version-specific behavior, parameter usage, and a fallback mechanism. It fully compensates for the lack of an output schema by explaining what each search returns.

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

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

Schema coverage is 100% (all 6 parameters described in input schema). The description adds value by explaining parameter effects: currentPageOnly controls page scanning, assetTypes filters results, query filters by name, and limit default is mentioned. This enhances understanding beyond the schema.

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

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

The description clearly identifies the tool as searching for design system assets in the current Figma file, enumerating three specific asset types (variables, local components, remote library components). It distinguishes itself from sibling tools like figma_search_components and figma_get_library_variables by explicitly covering multiple asset categories and referencing version-specific behaviors.

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 extensive usage context: when to use (searching assets), parameter guidance (e.g., currentPageOnly, assetTypes), and a fallback hint (_restFallbackHint) for empty results. It implies alternatives (REST API) but does not explicitly state when not to use this tool vs. siblings, though the detail compensates.

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 indicate readOnlyHint=true, and the description adds that the tool returns nodeIds and names, plus notes the limitation of no REST API. This provides useful behavioral context beyond the annotation, such as the non-REST nature and return data shape.

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

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

The description is extremely concise, using three short sentences that front-load the core purpose, return type, and key usage parameters. No redundant information is present.

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

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

Given 5 parameters and no output schema, the description covers purpose and two key parameters but omits details on currentPageOnly and limit. It also doesn't specify pagination or result format beyond nodeIds and names. While the core intent is clear, the lack of completeness for all parameters reduces its utility for agent 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?

The description adds meaning to the query parameter by stating search is by name, and clarifies the role of fileKey and figmaUrl. However, it does not explain currentPageOnly or limit parameters, and schema coverage is 40%, so the description only partially 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 the tool searches local components by name and returns nodeIds and names. It distinguishes from siblings like figma_search_assets by specifying 'local components'. However, it could be more explicit about the scope of search (e.g., within a file or project).

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

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

The description advises using fileKey or figmaUrl to target a specific file, which provides clear usage context. Mentioning 'No REST API' implicitly guides agents away from using this tool for REST API purposes, serving as an alternative indicator. It does not, however, explicitly contrast with similar search 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?

The annotations indicate destructiveHint=true, and the description confirms a write operation ('set'). It adds specific node types, which is helpful. However, it does not disclose other behaviors like overwriting behavior or whether the operation is reversible.

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 is concise and front-loaded with the core purpose. It could be slightly more detailed without becoming verbose.

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

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

Given the tool is destructive with 3 parameters and no output schema, the description lacks completeness. It does not explain return values, side effects, or constraints on nodeId. A more complete description would help the agent 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?

With 0% schema description coverage, the description should explain parameter semantics. It mentions markdown support for descriptionMarkdown, but fails to clarify the difference between 'description' and 'descriptionMarkdown', and does not describe 'nodeId'. The explanation is insufficient.

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 (set), the resource (description), and the target node types (component, component set, style). This distinguishes it from sibling tools like 'figma_get_component' or 'figma_instantiate_component'.

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

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

The description provides no guidance on when to use this tool vs. alternatives, nor does it mention any prerequisites or exclusions. It leaves 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?

The description discloses the API fallback mechanism and data storage via pluginData, explaining the shape of FlowStartingPoint. However, it does not fully explain behavioral effects of the 'replace' parameter (e.g., whether it overwrites other starting points).

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

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

Two well-structured sentences: first states purpose clearly, second explains implementation details. No redundancy or excess.

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