figma-mcp-go
Server Quality Checklist
- Disambiguation4/5
Tools are generally well-differentiated with clear, specific purposes. While there are multiple retrieval tools (get_document, get_design_context, get_node, search_nodes, scan_nodes_by_types), their descriptions clarify distinct use cases (full tree vs depth-limited vs specific node vs filtered search). Similarly, export tools target different outputs (PDF vs base64 vs filesystem). Minor potential confusion between set_fills, apply_style_to_node, and bind_variable_to_node, but context helps distinguish these.
Naming Consistency4/5Strong adherence to snake_case verb_noun pattern (create_*, get_*, set_*, delete_*). Minor inconsistencies exist: 'add_variable_mode' uses 'add' instead of 'create', 'bind_variable_to_node' uses 'bind' while 'apply_style_to_node' uses 'apply' for similar linking concepts, and plurality varies (delete_nodes vs delete_style vs rename_node). However, the pattern is predictable enough for agents to navigate.
Tool Count2/5With 58 tools, this significantly exceeds the threshold where tool sets feel heavy (25+). While Figma is a complex domain requiring broad surface coverage (nodes, styles, variables, components, prototyping, exporting), the sheer volume approaches 'tool bloat' and may overwhelm agent context windows or selection accuracy. Several tools could potentially be consolidated (e.g., various get_* retrieval methods with filter parameters).
Completeness4/5Excellent coverage across the Figma domain: full CRUD for nodes, styles (paint, text, effect, grid), and variables; component lifecycle (create, swap, detach); prototyping (reactions); and exporting (PDF, screenshots, tokens). Minor gaps exist: no explicit create_instance (though clone_node may substitute), missing update_* operations for text/effect/grid styles (only update_paint_style exists), and no boolean operations. Core design workflows are well-supported.
Average 3.5/5 across 58 of 58 tools scored. Lowest: 2.2/5.
See the tool scores section below for per-tool breakdowns.
This repository includes a README.md file.
This repository includes a LICENSE file.
Latest release: v1.0.5
Tools from this server were used 2 times in the last 30 days.
This repository includes a glama.json configuration file.
- This server provides 58 tools. View schema
No known security issues or vulnerabilities reported.
This server has been verified by its author.
Add related servers to improve discoverability.
Tool Scores
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate this is a destructive, non-idempotent write operation, but the description adds no context about what makes it destructive or what side effects occur. It does not explain whether renaming breaks references, affects linked components, or if the change 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While brief, the description is insufficiently informative for a destructive operation. The single phrase fails to front-load critical behavioral information (e.g., destructive nature, scope of impact) that would help an agent invoke the tool safely.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a destructive mutation tool with no output schema, the description should explain behavioral implications (e.g., 'changes the layer name displayed in the layers panel'). Currently, it provides only the minimal function identification despite the operational complexity implied by destructiveHint=true.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema adequately documents both nodeId (including the colon format example) and name parameters. The description adds no additional semantic context, meeting the baseline expectation for high-coverage schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Rename a node' is a tautology that restates the tool name. While it identifies the resource (node) and action (rename), it fails to distinguish this tool from sibling operations like set_text, clone_node, or delete_nodes, all of which also operate on nodes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this tool versus alternatives. For example, it does not clarify whether to use this versus set_text for text layers, or whether this affects the display name versus the layer name in the design tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations declare destructiveHint=true and idempotentHint=false, the description adds no context about what destruction entails (overwriting existing fills), the implications of non-idempotency, or side effects. The schema describes the 'mode' parameter behavior, but the main description omits this critical behavioral nuance entirely.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is efficient and front-loaded with the core action. However, extreme brevity contributes to under-specification; while no words are wasted, the description lacks necessary qualifying information for a destructive operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation tool with no output schema, the description is insufficient. It lacks explanation of error states, return behavior, side effects on node appearance, or warnings about data loss (existing fills being overwritten), despite the operation's destructive nature indicated in annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema adequately documents all parameters including the 'nodeId' format and 'mode' options. The description adds no semantic value beyond the schema ('fill color' restates the 'color' parameter), warranting the baseline score for high-coverage schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Set') and resource ('fill color of a node'), but fails to distinguish from siblings like 'set_strokes', 'set_opacity', or 'apply_style_to_node'. It doesn't clarify whether this replaces existing fills or handles multiple fills, leaving functional ambiguity despite the basic action being clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this tool versus alternatives like 'apply_style_to_node' or other 'set_' tools. No prerequisites mentioned (e.g., node existence verification), and no exclusions or error conditions described.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description contradicts the annotations: it uses the verb 'Get' implying a safe read operation, but annotations declare 'destructiveHint: true' and 'readOnlyHint: false'. The description fails to explain why retrieving reactions would be destructive or non-idempotent, creating serious ambiguity about 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of exactly two sentences with zero redundancy. The first states the core function; the second provides context. Every word earns its place with no filler or structural waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the presence of complex behavioral annotations (destructive, open-world) and no output schema, the description offers no insight into return values, error conditions, or why a retrieval operation is marked destructive. It inadequately covers the tool's behavioral contract.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage for the single 'nodeId' parameter (including format example '4029:12345'), the schema carries the full semantic load. The description adds no parameter-specific guidance, meeting the baseline expectation for high-coverage schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves 'prototype/interaction reactions on a node' using the specific verb 'Get'. It effectively distinguishes itself from siblings 'set_reactions' and 'remove_reactions' by positioning itself as the read/inspect operation for prototype interactions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
While the description notes the tool is 'Useful for understanding interactive prototypes,' it provides no guidance on when to use this specific tool versus alternatives like 'get_node' or 'get_nodes_info', nor does it mention prerequisites such as needing a valid nodeId from prior operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'Create a new text node,' indicating an additive, non-destructive operation. This directly contradicts the destructiveHint: true annotation, which indicates the tool performs destructive operations like deletion or irreversible modification. This contradiction creates serious ambiguity about the tool's safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no redundant words. It front-loads the action ('Create') and specifies the target resource ('text node') and location context immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 100% schema coverage and present annotations, the description is minimally adequate. However, it does not compensate for the missing output schema (does it return the node ID?), nor does it explain error conditions or side effects beyond the annotation contradiction.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline score is 3. The description reinforces the parentId parameter by mentioning 'current page' and 'parent node' placement, but does not add semantic details beyond what the schema already provides (e.g., coordinate system details for x/y, or formatting behavior).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does 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 and specifies the location context ('current page or inside a parent node'). However, it does not explicitly differentiate from sibling creation tools like create_rectangle or create_frame, relying solely on the 'text' keyword in the name to distinguish the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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. It fails to mention when to prefer create_text over set_text (which likely updates existing text nodes) or how to choose between creating different node types (text vs frame vs shape).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations indicate destructiveHint=true and openWorldHint=true, the description does not explain what makes this destructive (e.g., potential name collisions, overwriting existing styles) or what side effects occur beyond the return value. The addition of 'local' provides minimal scope context but fails to elaborate on the mutation's impact or persistence model.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The single six-word sentence is efficiently structured with no redundancy, immediately stating the core operation. However, it errs on the side of under-specification for a 10-parameter destructive tool, leaving substantial room for additional clarifying information without sacrificing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex creative tool with numerous typography parameters and destructive annotations, the description is inadequate. It fails to explain the return behavior (no output schema exists), the scope of 'local' styles within the document hierarchy, or how this integrates with the broader design system workflow suggested by sibling tools like export_tokens.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the structured data already documents all 10 parameters including defaults and formats. The description adds no parameter-specific guidance, syntax examples, or interaction notes (e.g., how letterSpacingUnit affects letterSpacingValue), warranting the baseline score for high-coverage schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description provides a clear verb ('Create') and resource ('text style'), distinguishing it from sibling tools like create_paint_style or create_effect_style. However, it leaves the term 'local' unexplained, which could clarify scope (document-level vs. shared library) to better differentiate from potential team library alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 such as apply_style_to_node (for direct application) or how it relates to delete_style. There are no prerequisites mentioned (e.g., requiring an active document) and no exclusions or failure modes described.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While not contradicting annotations, the description adds no behavioral context beyond the basic action. It fails to explain what 'destructive' entails, the side effects of creation, or the implication of idempotentHint:false (duplicate creation attempts).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single sentence with no filler. However, given the tool's complexity and destructive nature, the brevity may be excessive rather than optimally informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Minimum viable for the tool's complexity. The input schema is fully documented, but the description lacks guidance on the variable system ecosystem (modes, collections) and omits return value information despite having no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema carries the full burden of parameter documentation. The description adds no parameter semantics, meeting the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
States specific verb (Create) and resource (variable) with scope ('in a collection'), distinguishing it from sibling create_variable_collection. However, it omits the domain context (design tokens) that would make it fully clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this versus alternatives like set_variable_value (updating existing) or create_variable_collection (prerequisite). No mention of prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fails to disclose critical behavioral traits revealed in annotations. It uses the verb 'Get' which implies safe retrieval, but annotations indicate destructiveHint=true and readOnlyHint=false. The description does not explain what data is destroyed or modified during this 'get' operation, creating a dangerous ambiguity for agent selection.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no redundant words. It front-loads the verb and immediately scopes the operation, achieving maximum information density.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having only one parameter and no output schema, the description is incomplete because it omits the destructive side effects indicated by annotations. For a tool marked as destructive, the description must explain what changes occur, which is absent here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the baseline is 3. The description adds valuable semantic context by clarifying that omitting nodeId retrieves annotations for the 'current document' rather than requiring explicit enumeration, effectively documenting the default behavior beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Get') and resource ('dev-mode annotations'), and specifies the scope ('current document or specific node'). However, it does not differentiate from siblings like get_node which might also return annotation data in their outputs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks explicit guidance on when to use this tool versus alternatives like get_node or get_document. While it implicitly explains the optional nodeId parameter by mentioning 'current document or specific node', it provides no warnings or prerequisites despite the destructive nature of the operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description contradicts the annotations: it uses 'Get' implying a safe read operation, but annotations declare 'destructiveHint: true' and 'readOnlyHint: false'. The description fails to explain why retrieving a document tree would be destructive or mention the 'openWorldHint: true' indicating external system interaction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no filler words. It is appropriately front-loaded with the action verb and maintains focus on the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having annotations that indicate destructive behavior, the description provides no explanation for this trait. With no output schema provided, the description should ideally clarify the return structure or side effects, especially given the destructive annotation flag.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters. According to the baseline rules, 0 params warrants a baseline score of 4. The description correctly implies no parameterization is needed for this operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and identifies the resource as 'current Figma page document tree'. However, it does not clearly distinguish from siblings like 'get_node' or 'get_nodes_info' which also retrieve document data, leaving ambiguity about when to use the full tree vs specific nodes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 like 'get_node' or 'get_nodes_info'. There are no prerequisites, exclusions, or workflow context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only retrieval ('Get'), but the annotations declare destructiveHint=true and readOnlyHint=false. This creates a serious safety ambiguity that the description fails to resolve or explain (e.g., whether this clears selection, modifies history, or consumes the selection buffer).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no filler. The most critical information (action + target) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no input parameters, the tool has destructive annotations that demand explanation, and no output schema is provided. The description fails to clarify what data structure is returned (node IDs, objects, etc.) or why the operation is marked destructive, leaving critical gaps for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema contains zero parameters. Per the baseline rules for zero-parameter tools, this earns a score of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('currently selected nodes') with clear scope ('in Figma'). The qualifier 'currently selected' implicitly distinguishes it from siblings like get_node or get_nodes_info which likely retrieve by ID or query, though explicit contrast is absent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 like get_node or scan_nodes_by_types. It lacks prerequisites (e.g., requiring an open document) or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare readOnlyHint=false and destructiveHint=true, indicating this operation modifies or destroys state. The description 'Get all local styles' implies a safe retrieval, creating a severe mismatch. It adds no explanation of what gets destroyed or why this 'get' operation is destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the action. The colon-delimited list of style types provides dense information without verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the surprising destructive annotation and lack of output schema, the description is dangerously incomplete. It fails to explain the side effects, return format, or safety considerations necessary for an agent to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema contains zero parameters, so baseline 4 applies. The description correctly implies no filtering parameters are available by stating 'all local styles', which aligns with the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the verb ('Get'), resource ('local styles'), and scope ('in the document'), including specific style types (paint, text, effect, grid). However, it fails to distinguish this from sibling 'get' tools (e.g., get_document, get_nodes_info) by not indicating its non-read behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 versus alternatives like create_*_style or delete_style. Critically, it fails to warn against using this when a safe read is expected, which is dangerous given the destructive annotations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description claims this is a 'Find' operation (implying read-only), but annotations indicate destructiveHint=true and readOnlyHint=false. This is a serious contradiction. The description fails to explain what gets destroyed during a 'find' operation, what the 'subtree' scope entails, or what the return format is.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the verb. No words are wasted; the examples are specific and illustrative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the destructive annotation, the description is dangerously incomplete as it provides no warning about side effects. Without an output schema, it should also describe what gets returned (node list, IDs, full objects?), but it does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description adds value by specifying 'within a subtree' which contextualizes the nodeId parameter's role as a root. However, it mostly repeats the type examples already present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Find[s] all nodes matching specific types' and identifies the scope ('within a subtree'). It distinguishes itself from scan_text_nodes by focusing on types rather than text content. However, it does not clarify how this differs from search_nodes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 similar discovery tools like search_nodes, get_nodes_info, or scan_text_nodes. No prerequisites or conditions are mentioned despite the specific nodeId format requirement shown in the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations indicate destructiveHint=true and idempotentHint=false, the description adds no context explaining WHY the tool is non-idempotent (the append mode stacking strokes) or what gets destroyed (existing strokes in replace mode). It misses the opportunity to explain that multiple strokes can exist on a node, which is critical behavioral information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. However, it is arguably too concise for a destructive, non-idempotent tool with four parameters, as it omits crucial behavioral details (the append/replace distinction) that should have been included.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic operation but leaves significant gaps. Given the destructive nature and the presence of a 'mode' parameter that controls stacking behavior, the description should explicitly address the replace/append behavior. As written, it is minimally viable but incomplete for safe usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description mentions 'color and weight', reinforcing two parameters, but completely omits the 'mode' parameter despite its significant behavioral impact. It adds no syntax details or examples beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Set') and identifies the resource ('stroke color and weight') clearly. It distinguishes from siblings like 'set_fills' or 'set_corner_radius' by specifying 'stroke'. However, it fails to mention the 'mode' parameter's functionality (append vs replace), which is central to how strokes are managed, preventing a score of 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 (e.g., 'set_fills' for interior color vs 'set_strokes' for borders). It also fails to explain when to use 'append' mode versus 'replace' mode, leaving users without decision-making context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description claims this is a 'Get' operation implying read-only behavior, but the annotations specify readOnlyHint=false and destructiveHint=true. This is a serious contradiction—the description suggests a safe retrieval while annotations warn of destructive 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence with no redundant words. It immediately states the operation and scope without filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers the basic operation, the contradiction with annotations creates ambiguity about the tool's actual behavior. Without an output schema, it also omits what format the components are returned in (e.g., IDs, names, full objects).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and 100% schema coverage. With no parameters to document, the baseline score applies as per rubric guidelines for 0-param tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb ('Get') and resource ('components'), and specifies scope ('defined in the current Figma file') which distinguishes local components from library components. However, it does not explicitly differentiate from sibling retrieval tools like get_styles or get_nodes_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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. It does not mention prerequisites (e.g., requiring an open file) or when to prefer this over get_node for specific component lookups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description contradicts the annotations. It describes a 'Get' operation implying a safe read, but annotations declare `readOnlyHint: false` and `destructiveHint: true`. This is a serious inconsistency—metadata retrieval should not be destructive, making the behavioral profile unsafe or misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficiently structured sentence that front-loads the action ('Get metadata') and follows with a colon-delimited list of specific return values. No words are wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description compensates by listing return values (file name, pages, current page). However, the annotation contradiction creates a critical gap in understanding the tool's safety profile, and there's no explanation for why a metadata retrieval would be marked destructive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, establishing a baseline score of 4. With no parameters to describe, the description appropriately focuses on the return value semantics rather than input requirements.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('metadata about the current Figma document'), and explicitly lists the returned fields (file name, pages, current page). This distinguishes it from siblings like `get_document` (likely full structure) and `get_pages` (likely just page list), though it doesn't explicitly state these distinctions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 like `get_document`, `get_design_context`, or `get_pages`. It states what the tool returns but not why an agent should choose this over other 'get' siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Aligns with annotations (destructiveHint=true matches 'Create'). The term 'local' adds some context about scope. However, it fails to disclose behavioral nuances like idempotency (creating duplicate names), return values, or the conditional parameter requirements visible in the schema (e.g., color only applies to GRID pattern).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single sentence with no redundant words. However, the brevity comes at the cost of omitting critical context about the tool's complexity and conditional parameter logic, preventing a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Inadequate for a 10-parameter tool with complex conditional logic (e.g., color/opacity only for GRID pattern; count/gutterSize only for COLUMNS/ROWS). The description gives no hint of these constraints, leaving agents to discover them through schema inspection or trial and error.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the structured schema carries the full burden of parameter documentation. The description mentions no parameters, so it adds no semantic value beyond the schema, warranting the baseline score for high-coverage schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
States specific verb ('Create') and resource ('local layout grid style'). Distinguishes from sibling tools like create_paint_style or create_text_style by specifying 'grid', though it doesn't explain what distinguishes grid styles from other style types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this tool versus alternatives like create_paint_style or apply_style_to_node. No mention of prerequisites or when-not-to-use conditions despite the complex parameter interdependencies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description presents a 'List' operation as read-only, but annotations declare readOnlyHint: false and destructiveHint: true. This is a serious contradiction—a listing operation should not be destructive. The description adds no context about what gets destroyed or why a getter has 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two well-structured sentences with no waste: first states the operation, second states the value proposition. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description explains what is returned (font list), it completely omits the destructive nature indicated by annotations. For a tool marked destructive with no output schema, the description must explain side effects, which it fails to do.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so baseline is 4. The description appropriately does not fabricate parameter explanations where none exist, though it could have mentioned the implicit 'current page' context as a conceptual input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it 'List[s] all fonts used in the current page' with specific sorting (usage frequency), providing a clear verb and resource. It implicitly distinguishes from sibling tools like scan_text_nodes by noting it works 'without scanning all text nodes.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence provides implied usage guidance ('Useful for understanding typography'), suggesting when to use it. However, it lacks explicit when-not guidance or named alternatives, and fails to mention prerequisites or side effects implied by the annotations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description contradicts the annotations: it uses the verb 'Get' implying a read-only retrieval operation, while annotations declare readOnlyHint=false and destructiveHint=true, indicating a destructive write operation. The description fails to disclose any destructive behavior, side effects, or mutation risks.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two highly efficient sentences with zero waste. It front-loads the purpose ('Get a specific Figma node') and immediately follows with the critical format constraint, placing the most important information first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the destructiveHint annotation indicates irreversible side effects, the description is dangerously incomplete. It fails to explain what gets destroyed or modified during a 'get' operation, and with no output schema provided, the agent lacks critical behavioral context for a destructive tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While the schema has 100% coverage and fully documents the nodeId parameter, the description adds valuable emphasis on the format constraint ('never hyphens') that reinforces the schema requirements and clarifies a common error case.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and resource ('Figma node') with clear identification method ('by ID'). However, it does not differentiate from similar sibling tools like 'get_nodes_info' or 'get_document'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit format guidance ('Must use colon format...never hyphens') which constrains usage. However, it lacks guidance on when to use this tool versus alternatives like 'search_nodes' or 'get_nodes_info', and mentions no prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description contradicts the provided annotations. It describes a read operation ('Get'), but annotations declare readOnlyHint: false and destructiveHint: true. A 'get' operation should not be destructive; this inconsistency could mislead the agent about side effects and safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the action ('Get') and immediately specifies the return value components. There is no redundant or wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description appropriately lists the specific data fields returned (scroll center, zoom level, visible bounds). However, it could be improved by noting the coordinate system or format of these values, and it fails to explain the destructive annotation flag.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and 100% schema coverage trivially. With no parameters to describe, the baseline score applies. The description does not need to compensate for missing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific resource (Figma viewport) and the specific attributes retrieved (scroll center, zoom level, visible bounds). However, it does not explicitly differentiate from similar 'get' siblings like get_screenshot or get_selection, though the specificity of 'viewport' provides implicit distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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. It does not mention prerequisites, exclusions, or scenarios where other viewport-related tools (if they existed) would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is a destructive, non-idempotent write operation. The description adds that the style is 'local' (scope) and 'solid fill' (type constraint), which is useful context beyond the annotations. However, it fails to disclose error behavior (e.g., what happens if the name already exists), side effects, or whether the created style ID is returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with zero redundancy. While admirably compact, its brevity contributes to gaps in sibling differentiation and behavioral context. It earns high marks for efficiency but could accommodate one more clause for usage guidance without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only three parameters with complete schema coverage and safety annotations, the description covers the minimal viable surface. However, for a destructive, non-idempotent operation, it should clarify conflict resolution (duplicate names) and return values to be complete. Without output schema documentation, the description bears more responsibility for explaining what the agent receives back.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema adequately documents all three parameters including examples for name and color. The description adds no additional parameter guidance beyond implying the color is for a 'solid fill.' Baseline score of 3 is appropriate since the schema carries the full semantic load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'Create' and identifies the resource as a 'local paint style with a solid fill color.' The 'local' and 'solid fill' qualifiers help distinguish it from global styles and sibling tools like create_effect_style or create_text_style. However, it does not explicitly distinguish from update_paint_style, which could confuse agents deciding between creation vs. modification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 like update_paint_style or set_fills. It lacks prerequisites (e.g., whether a document must be open) and exclusion criteria (e.g., when not to create duplicate styles). Agents must infer usage context solely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with annotations (destructive creation) and adds 'local' scope context not present in structured fields. However, it omits behavioral details like whether names must be unique, what the default 'Mode 1' implies (visible in params but not described behaviorally), or the effect of openWorldHint=true.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is efficiently structured with action front-loaded. However, given the destructive nature and lack of output schema, the extreme brevity leaves important behavioral questions unanswered, slightly undershooting the optimal information density.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with 2 parameters and no output schema, the description is minimally sufficient but incomplete. It fails to address return value implications, side effects (e.g., automatic creation of initial mode), or how this interacts with the sibling variable management tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage ('Collection name', 'Name for the initial mode'). The description provides no additional parameter semantics beyond the schema, meeting the baseline for high-coverage schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
States specific action (Create) and resource (local variable collection) clearly. The term 'local' helps scope the operation, though it could better distinguish from the sibling 'create_variable' tool by clarifying this creates a container/mode group rather than individual variables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this versus creating individual variables directly, or prerequisites such as whether a document must be open. No mention of error conditions like name collisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description claims a read operation ('Get'), but the annotations declare destructiveHint=true and readOnlyHint=false. This is a serious contradiction—the description fails to disclose what gets destroyed or modified during this seemingly read-only operation, or why it is non-idempotent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. The key differentiator ('in a single call') is positioned at the end, effectively distinguishing it from sibling tools without verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having only one parameter, the annotations indicate complex, dangerous behavior (destructive, non-idempotent, open-world) that the description completely ignores. For a tool marked destructive, the description must explain the side effects, which it fails to do.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the parameter 'nodeIds' is fully documented in the schema including format examples. The description does not add param-specific details, which is acceptable given the schema's completeness, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves 'detailed information about multiple Figma nodes' and explicitly distinguishes itself from the sibling 'get_node' (singular) by emphasizing 'multiple' and 'in a single call', indicating batch retrieval functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'in a single call' implies the batching use case (efficiency for multiple lookups), but it does not explicitly state when to prefer this over 'get_node' or warn against using it for single nodes. No alternative tools are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only operation ('Scan', 'extracting'), but annotations indicate destructiveHint=true and readOnlyHint=false. This is a serious contradiction—scanning and extracting typically imply observation, not destruction. The description fails to explain what gets destroyed or why this mutates state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences with zero waste. The first sentence front-loads the core capability, and the second provides immediate use-case context. No redundant or filler text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks output schema and fails to describe return values (what format do the scanned text nodes return?). Critically incomplete due to the unexplained destructive annotation—without knowing what gets destroyed, the tool is unsafe to invoke. Does not compensate for missing safety information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the nodeId parameter is already well-documented with format examples in the schema. The description mentions 'in a subtree' which aligns with the 'Root node ID' schema description but adds minimal semantic value beyond the structured definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Scan'), resource ('TEXT nodes'), and scope ('in a subtree'). The second sentence clarifies the use case ('extracting all copy'), effectively distinguishing this from generic node retrieval tools like get_node.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implied usage context ('Useful for extracting all copy from a component or frame'), indicating when to use it. However, it lacks explicit when-not guidance or mentions of alternatives like scan_nodes_by_types or get_nodes_info.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false. The description adds valuable context about optional repositioning and reparenting capabilities, but fails to clarify behavioral implications like whether child nodes are recursively cloned, what ID is returned, or the side effects of multiple invocations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with optimal structure: main action ('Clone an existing node') front-loaded, followed by optional modifiers ('optionally repositioning...'). No redundant words or tautology.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for basic operation but gaps remain regarding clone depth (children? styles? overrides?), return value structure, and how the new node relates to the original. Given destructive annotations and no output schema, more behavioral context would strengthen the definition.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description maps concepts ('repositioning' to x/y, 'new parent' to parentId) providing semantic grouping, but doesn't add syntax details, validation constraints, or examples beyond what's in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'Clone' with clear resource 'node', and distinguishes from sibling create_* tools by emphasizing 'existing node'. However, it doesn't explicitly contrast with alternatives like 'create_component' or 'move_nodes'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through 'optionally repositioning' and 'new parent' but provides no explicit guidance on when to prefer cloning over creating new nodes, nor does it mention prerequisites like source node visibility or permissions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true, idempotent=false, and openWorld=true, but the description does not explain what these imply for this specific tool (e.g., that creation permanently modifies the document or that repeated calls create duplicate ellipses). It adds value only by specifying the placement hierarchy (page vs parent node).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 12 words with zero redundancy. The action is front-loaded and every word serves a purpose. Appropriate length for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple shape creation tool with complete schema coverage. However, lacking an output schema, the description should ideally mention what the tool returns (e.g., the created node ID or object) or confirm the side effects of creation implied by destructiveHint=true.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already fully documents all 7 parameters including defaults. The description mentions 'parent node' which maps to parentId, but adds no additional semantic meaning beyond the schema for fillColor, dimensions, or positioning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Create) and resource (ellipse/circle/oval) and distinguishes from siblings like create_rectangle or create_text by specifying the geometric shape. The parenthetical '(circle/oval)' helpfully clarifies the shape variant.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions placement options ('current page or inside a parent node') but provides no guidance on when to choose this tool over sibling creation tools like create_rectangle or create_frame. No alternatives or exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructive=true and idempotent=false, which align with 'Create a new frame'. The description adds value by specifying placement behavior (current page vs parent node) not covered by annotations. However, it fails to disclose what the tool returns (e.g., node ID), error conditions, or side effects given the lack of output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 11 words is appropriately front-loaded with the action. No redundant or wasted text. However, given the high complexity (19 parameters, destructive mutation), the extreme brevity may underserve the agent's need for context, preventing a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive creation tool with 19 parameters and no output schema, the description is insufficient. It omits critical information about return values (what identifies the created frame?), error handling, and whether the created frame has default auto-layout or sizing behavior. Relies too heavily on schema alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage across 19 parameters, the baseline is met. The description mentions 'parent node' which loosely references the parentId parameter, but adds no additional semantic context about coordinate systems, auto-layout behavior, or parameter interactions beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Create' and resource 'frame' with scope 'on the current page or inside a parent node'. Accurately describes the hierarchical placement options. However, it does not explicitly distinguish from similar sibling tools like create_component that may also create frame-like containers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage context through mention of 'current page' and 'parent node', hinting at the parentId parameter behavior. However, lacks explicit guidance on when to use this versus create_component or group_nodes, and omits prerequisites like requiring valid parentId if specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description implies a read-only retrieval ('Get'), but annotations indicate destructiveHint=true and readOnlyHint=false. This contradiction fails to disclose the tool's mutating nature and creates false safety expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste: first defines the operation and return structure, second provides essential domain context (design tokens). Appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Explains return value structure well (collections, modes, values) compensating for missing output schema. However, incomplete due to failure to address the destructive behavior indicated in annotations, which is critical context for invocation safety.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters present, establishing baseline 4. The description mentions 'local' which provides useful scope context not captured in the schema, though no parameter semantics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb ('Get') and resource ('local variable definitions') with clear scope (collections, modes, values). The 'design token system' context distinguishes it from sibling get_styles (which handles styles, not tokens).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use versus alternatives like export_tokens or create_variable. While 'local' implies scope (vs. library variables), there are no explicit when/when-not statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with annotations (readOnlyHint=false, destructiveHint=true) by using 'Set', confirming it is a write operation. However, it adds minimal context beyond annotations: it doesn't clarify that setting overwrites previous values (destructive), explain the openWorldHint implication, or describe the effect on nodes using this variable in the specified mode.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It is appropriately front-loaded with the action and target resource, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple 3-parameter schema with full coverage and present annotations, the description is minimally adequate. However, given destructiveHint=true and lack of output schema, gaps remain: it should clarify the overwrite behavior and confirm no return value or side effects beyond the variable update.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already documents all parameters including value formats (COLOR hex, FLOAT number, etc.). The description adds conceptual grouping ('for a specific mode') but doesn't provide additional syntax, validation rules, or format details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Set') and identifies the resource ('variable's value') and scope ('for a specific mode'). It implicitly distinguishes from siblings like create_variable (which creates definitions) or bind_variable_to_node (which applies variables to nodes) by mentioning 'mode', though it doesn't explicitly contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 like create_variable or bind_variable_to_node. It does not mention prerequisites (e.g., that the variable and mode must already exist) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description uses 'Get' implying a read-only operation, which directly contradicts the annotations indicating destructiveHint=true and readOnlyHint=false. It fails to explain why a retrieval operation would be destructive or what side effects occur.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently convey purpose and comparative advantage without redundancy. The information is front-loaded with the core action in the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the destructive annotation and lack of output schema, the description inadequately explains behavioral outcomes or return structure. It mentions returning a 'tree' but omits critical safety warnings about the destructive nature implied by annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the description appropriately does not redundantly document parameters. It adds value by contextualizing the 'depth' parameter through the 'depth-limited' phrasing and explaining the token-efficiency implications of the deduplication feature.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly defines the operation as retrieving a 'depth-limited tree' and explicitly differentiates from sibling tool 'get_document' by highlighting token efficiency for large files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit comparison to 'get_document' indicating when to prefer this tool (large files), but lacks guidance regarding other sibling retrieval tools like 'get_node' or 'get_selection'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true and readOnlyHint=false, which is unexpected for a 'get' operation and suggests state modification or side effects. The description fails to explain this destructive nature or why it isn't read-only. It only adds that the function returns base64-encoded data, which is helpful but insufficient given the alarming annotation profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste: first defines the operation, second defines the return format. Perfectly front-loaded and appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description usefully specifies the return format (base64 image data). It covers the core functionality adequately, though it misses explanation of the destructive behavior flagged in annotations. Given the simple parameter structure, this is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema fully documents parameters (format options, colon-format nodeIds, scale defaults). The description adds no additional parameter semantics beyond implying the 'selected or specific' dichotomy for nodeIds, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
States specific action (export screenshot) and target (selected/specific nodes) clearly. However, it does not explicitly differentiate from sibling tool 'save_screenshots', which appears to have similar functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Lacks explicit 'when to use' guidance or comparison to alternatives. The mention of 'Returns base64-encoded image data' implicitly suggests this is for programmatic data retrieval versus file saving, but does not name alternatives like 'save_screenshots' or 'export_frames_to_pdf'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations establish the destructive, non-idempotent nature of the operation, so the description's primary behavioral addition is specifying that the target must be an existing TEXT node. However, it fails to disclose error behaviors, such as what happens if the nodeId does not exist, and does not address the openWorldHint implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of a single, efficient nine-word sentence that immediately communicates the core operation without redundant phrases or unnecessary elaboration. Every word earns its place in conveying the tool's essential function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple two-parameter input schema, the presence of comprehensive annotations covering safety and idempotency, and the lack of an output schema, the description provides sufficient context for an agent to invoke the tool correctly. It appropriately delegates parameter details to the schema, though it could benefit from mentioning validation constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline score is 3, and the description does not significantly expand upon the parameter semantics beyond implying through 'existing TEXT node' that nodeId requires a valid text node identifier. The schema already fully documents the colon format for nodeId.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Update' with the resource 'text content' and explicitly targets an 'existing TEXT node', which distinguishes it from the sibling tool 'create_text'. However, it does not explicitly name sibling alternatives or clarify when to use this versus other text manipulation tools like 'bind_variable_to_node'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to select this tool over alternatives such as 'create_text' for new nodes or text variable tools. There are no stated prerequisites, conditions, or exclusions to help the agent determine proper usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is destructive (creates new entity) and not idempotent. The description adds valuable behavioral context about placement scoping (page vs. parentId) not covered by annotations. However, it omits details about return values or side effects like node naming conventions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 11 words with zero redundancy. The core action ('Create a new rectangle') is front-loaded, with placement options following. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 fully-documented parameters and annotations covering safety hints, the description provides minimal viable context. However, for a destructive creation tool with no output schema, it should ideally mention what gets created (e.g., a node) or return behavior. Lacks sibling differentiation guidance present in high-quality examples.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema carries the full burden of parameter documentation. The description mentions 'parent node' which loosely references the parentId parameter, but adds no syntax details, format constraints, or usage patterns beyond the schema definitions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') with a clear resource ('rectangle') and scope ('current page or inside a parent node'). While it doesn't explicitly differentiate from sibling shape tools like create_ellipse, the specific resource type provides implicit distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by mentioning placement options (current page vs. parent node), but lacks explicit guidance on when to choose this tool over alternatives like create_ellipse or create_frame. No 'when-not-to-use' 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.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations declare destructiveHint=true, readOnly=false, and openWorldHint=true, the description fails to explain what gets destroyed/overwritten (likely external files) or that this writes to disk rather than returning data in-memory. It adds no behavioral context beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste: first defines the action and formats, second provides the use case context. Front-loaded with the most critical information and appropriately brief for a single-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for basic invocation but lacks critical context given the annotations: it doesn't specify whether the export writes to disk (openWorldHint) or returns content, nor does it warn about the destructive nature. For a tool with destructive potential, this omission is a significant gap despite the simple schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the baseline is met. The description mentions 'CSS custom properties' which slightly augments the schema's 'css' value, but otherwise relies entirely on the schema's parameter documentation without adding syntax examples or validation details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb (export), resource (design tokens, variables and paint styles), and output formats (JSON or CSS custom properties). It effectively distinguishes from siblings like get_variable_defs by emphasizing code-ready export formats versus raw metadata retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Ideal for bridging Figma variables into your codebase' implies the use case (developer handoff/integration), but lacks explicit guidance on when to prefer this over get_styles or get_variable_defs, and doesn't mention prerequisites like file system permissions implied by openWorldHint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is destructive and not read-only. The description adds the '(flex)' terminology to contextualize the auto-layout concept but does not elaborate on partial update semantics (only nodeId is required), error conditions for invalid node types, or side effects on child nodes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with zero waste. Front-loaded with action verb and immediately identifies the operation scope. No redundant phrases or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high schema coverage and presence of annotations, the description doesn't need to be exhaustive. However, for a 13-parameter mutation tool with complex domain semantics (flexbox behavior), it minimally suffices but could benefit from noting the partial update pattern or mentioning that omitted properties retain current values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema fully documents all 13 parameters including valid values for enums (e.g., 'MIN, CENTER, MAX'). The description adds no parameter-specific semantics beyond what the schema provides, meeting the baseline for high-coverage schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('Set or update') and identifies the target resource ('auto-layout (flex) properties on an existing frame'). It distinguishes from sibling 'create_frame' by specifying 'existing' frame, and from other property setters like 'set_fills' by specifying 'auto-layout'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'existing frame' implies a prerequisite that the frame must already exist, suggesting this is for modification rather than creation. However, it lacks explicit guidance on when to use this versus creating a new frame with layout properties, or what happens if the node isn't a frame.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover destructiveness and read-only status. Description adds scope context ('entire collection' implies breadth of deletion) but fails to disclose behavioral implications of idempotentHint=false or what happens to nodes bound to deleted variables.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. Front-loaded with the destructive action, followed immediately by parameter constraints. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for the complexity given rich schema and annotations, but gaps remain around return values (no output schema), error conditions (what if both IDs provided?), and side effects on bound variables.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage establishing baseline of 3. Description adds critical semantic constraint 'either...or' which clarifies the logical requirement that one parameter must be provided despite schema marking both as optional, preventing invalid empty calls.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb (Delete) and specific resources (variable/variable collection). Distinguishes from sibling tools like delete_nodes or delete_style by specifying 'variable' domain, though lacks explicit comparison to similar deletion tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides mechanical guidance ('Provide either variableId or collectionId') implying XOR logic, but lacks strategic guidance on when to delete a single variable vs an entire collection, or prerequisites like checking for bound nodes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
CRITICAL CONTRADICTION: Description portrays a read-only operation ('List'), but annotations declare readOnlyHint=false and destructiveHint=true. The description completely fails to disclose what gets destroyed or why this is not read-only, directly contradicting the safety annotations provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste: first establishes function and return values, second provides sibling differentiation. Efficiently front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the functional description is adequate for a zero-parameter listing tool, the failure to address the destructive annotation (or correct the apparent error) leaves critical behavioral context missing. No output schema exists to compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema contains zero parameters. Per evaluation rules, 0 parameters establishes a baseline score of 4. No parameter description is needed or provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States specific action ('List') and resource ('pages in the document') plus return values ('IDs and names'). Explicitly distinguishes from sibling 'get_document' by positioning as a 'Lightweight alternative'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides comparative context naming the sibling alternative ('get_document') and implies usage when a lightweight option is preferred. Lacks explicit 'when not to use' or specific trade-off details (e.g., what data is excluded vs get_document).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description confirms the destructive nature implied by annotations by stating it 'Switch[es] the active Figma page,' explaining what state changes. However, it doesn't elaborate on the non-idempotent behavior (annotation: idempotentHint=false), potential side effects of page switching, or error handling when pages don't exist, leaving gaps despite the rich annotations provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of exactly two efficient sentences with zero redundancy: the first establishes the action, the second provides input guidance. It is appropriately front-loaded with the core verb and wastes no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple parameter structure (two strings) and rich annotations covering safety and idempotency, the description adequately covers the core functionality. However, for a destructive navigation operation, it should mention failure modes (e.g., page not found) or whether the change persists across sessions, which would complete the picture without requiring an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While the schema has 100% description coverage documenting the format of pageId ('colon format') and pageName ('Exact page name'), the description adds critical semantic information that these are alternatives ('either...or'), which the schema doesn't enforce (both are optional). This compensates for the schema's lack of XOR constraint logic.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Switch[es] the active Figma page,' providing a specific verb and resource. However, it doesn't explicitly differentiate from sibling tool 'get_pages' (which likely retrieves page metadata without changing the active view), leaving slight ambiguity about whether this performs navigation or just selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides input constraints ('Provide either pageId or pageName'), clarifying the XOR relationship between identifiers. However, it lacks guidance on when to use this tool versus alternatives, prerequisites (e.g., whether the page must exist in the current document), or what happens if both parameters are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is destructive (destructiveHint=true) and not read-only. The description adds context about the parameter logic (uniform vs. individual values) but does not disclose what happens if both are provided simultaneously, nor does it address error handling, rate limits, or side effects beyond what annotations indicate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two efficient sentences with zero waste. The first establishes the core operation, and the second provides essential parameter guidance. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the comprehensive schema and annotations, the description covers the essential operation. However, it lacks completeness regarding edge cases (parameter precedence if both uniform and individual values are provided) and does not describe the return value or success behavior, which would be helpful given there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the baseline is 3. The description adds value by clarifying the relationship between the uniform 'cornerRadius' parameter and the specific corner parameters (topLeftRadius, etc.), suggesting they are alternative approaches. This semantic grouping is not explicit in the schema itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Set') and target ('corner radius on one or more nodes'). It is specific about the resource being modified. However, it does not explicitly differentiate from sibling styling tools like set_fills or set_strokes, relying on the tool name to provide that distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage patterns for the parameters ('uniform cornerRadius or individual per-corner values'), which hints at how to structure the input. However, it lacks explicit guidance on when to select this tool versus other styling tools or prerequisites for the nodes (e.g., must be rectangles/frames).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructive, non-idempotent write behavior, but the description doesn't elaborate on what gets destroyed (previous field values) or that partial updates are possible. It adds value by listing which specific fields are mutable, but doesn't address the behavioral traits beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with zero waste. 'Existing' earns its place by implying prerequisites, and the field list maps directly to the three optional parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a straightforward CRUD update with 100% schema coverage and rich annotations covering the safety profile. Could be improved by clarifying partial update behavior (whether omitted fields are cleared or preserved).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is appropriately 3. The description mirrors the schema's field list without adding syntax details (e.g., it doesn't explain the styleId format beyond what the schema provides).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb ('Update') and resource ('paint style') with specific field enumeration ('name, color, or description'). The word 'existing' helps distinguish from the sibling 'create_paint_style', though it doesn't explicitly name the alternative tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the word 'existing' (suggesting the style must already exist and thus distinguishing from creation workflows), but lacks explicit guidance on when to use this versus 'delete_style' or prerequisites like required permissions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (destructiveHint=true, readOnlyHint=false). The description adds valuable context that the style is 'local' (distinguishing from library styles) and clarifies the effect subtypes. However, it does not explain the implications of idempotentHint=false (duplicate creation) or openWorldHint=true, nor does it describe what gets returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. The parenthetical list of effect types is appropriately placed to clarify scope without redundancy. Every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 100% schema coverage and comprehensive annotations, the description adequately covers the tool's purpose. However, with no output schema provided, the description should ideally mention what the tool returns (e.g., the created style ID) or confirm the side effects, which is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the input schema fully documents all 9 parameters including defaults and constraints (e.g., 'shadows only' caveats). The description mentions effect types that map to the 'type' parameter but adds no additional syntax or semantic details beyond what the schema provides, warranting the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') with a clear resource ('effect style') and specifies the scope ('local'). It distinguishes from sibling tools like create_paint_style and create_text_style by specifying 'effect' and listing the specific effect types (drop shadow, inner shadow, blur) in parentheses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by listing the three effect types supported (drop shadow, inner shadow, blur), which helps agents understand when this tool is appropriate. However, it lacks explicit guidance on when to use this versus create_paint_style or prerequisites for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not contradict annotations (destructiveHint=true aligns with 'Resize'). It adds valuable behavioral context that partial updates are supported (width OR height), which annotations don't convey. However, it omits whether aspect ratio is preserved, how constraints are handled, or the idempotentHint=false implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two high-density sentences with zero redundancy. It front-loads the action in the first sentence and immediately follows with the critical usage pattern (optional dimensions) in the second. No words are wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 100% schema coverage and explicit annotations covering safety/destructive traits, the description adequately covers the core contract. However, for a design tool resize operation, it should mention whether aspect ratio is locked or how the resize affects nested content, which are common failure modes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already documents the colon-format nodeIds and pixel dimensions. The description adds semantic value by clarifying that width and height are independently optional ('or both'), reinforcing the schema's required/optional structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Resize') with a clear resource ('nodes') and scope ('one or more'). It effectively distinguishes from siblings like 'move_nodes', 'clone_node', and 'set_corner_radius' by specifying dimensional scaling rather than position, duplication, or styling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence ('Provide width, height, or both') implies parameter optionality, suggesting partial resizes are supported. However, it lacks explicit guidance on when to use this versus scaling tools, when to avoid it (e.g., for locked components), or prerequisites (e.g., valid node IDs).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true and readOnlyHint=false, which is unexpected for a 'search' operation. The description fails to explain why searching would be destructive, what side effects occur, or why openWorldHint is true. It adds no behavioral context beyond the scope limitation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences total. The first states the core function; the second provides the value proposition/constraint. No filler or redundancy—every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a search tool with no output schema, but gaps remain: it doesn't describe return values (list of node IDs? full objects?), doesn't explain the destructive annotation, and doesn't specify pagination behavior beyond the limit parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description maps concepts ('name substring', 'type', 'subtree') to parameters but adds no syntax details, format examples, or semantic constraints beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Search') with clear resource ('nodes') and scope ('within a subtree'). The second sentence distinguishes it from full-document retrieval tools, addressing sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Avoids dumping the entire document tree' implies when to use this tool (targeted searches) versus alternatives like get_document or scan_nodes_by_types. However, it doesn't explicitly name sibling alternatives or state prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover safety (destructiveHint=true, readOnlyHint=false) and idempotency. The description adds valuable behavioral context by specifying 'linking' (creating a reference relationship rather than embedding values), but omits what happens to existing node properties (e.g., whether direct fills are removed when a paint style is applied).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence (16 words) with zero redundancy. It front-loads the action verb, immediately qualifies the resource type, and ends with the critical behavioral detail ('linking'), making every word essential.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter mutation tool with complete annotations and no output schema, the description provides adequate conceptual coverage. It could be improved by noting whether applying a style replaces or merges with existing properties, but this is a minor gap given the richness of structured data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema fully documents all three parameters including the colon format for nodeId and the constraint that 'target' applies only to paint styles. The description adds no additional parameter semantics beyond the baseline, but none are needed given the comprehensive schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Apply') and resource ('local style'), enumerates the supported style types (paint, text, effect, grid), and distinguishes from siblings like set_fills and create_*_style by emphasizing 'existing' and 'linking' semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies prerequisites by stating 'existing local style,' suggesting the style must be retrieved first (likely via get_styles). However, it lacks explicit when-to-use guidance versus alternatives like set_fills/set_strokes or warnings about the destructive replacement of direct properties.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description specifies the four categories of styles that can be deleted, adding scope context beyond what the annotations provide. While annotations correctly flag the operation as destructive and non-idempotent, the description could enhance transparency by noting irreversibility or error behavior when invalid IDs are provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The single-sentence description is front-loaded with the action verb 'Delete' and efficiently qualifies the resource type without extraneous words. The parenthetical enumeration of style types is information-dense and necessary for scope clarification, resulting in zero wasted space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple single-parameter input, comprehensive annotations covering safety hints, and lack of output schema, the description adequately covers the tool's function. It appropriately omits return value descriptions while successfully conveying the core deletion capability and supported style categories.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage for the styleId parameter ('Style ID to delete'), the schema already fully documents the input requirements. The description's reference to 'by its ID' aligns with but does not substantially augment the schema's semantic meaning, meeting the baseline for high-coverage schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Delete' paired with the resource 'style' and clarifies scope with the parenthetical '(paint, text, effect, or grid)'. This effectively distinguishes the tool from siblings like delete_nodes and delete_variable by specifying it operates on style resources rather than document nodes or variables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly guides usage by defining what constitutes a deletable style (paint, text, effect, or grid), which helps differentiate it from delete_nodes or delete_variable. However, it lacks explicit guidance on when to use this versus other style-related operations or prerequisites like obtaining the styleId first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructive=true, but the description adds valuable specificity with 'replaced in place,' clarifying that the transformation happens at the same location in the hierarchy rather than deletion/creation elsewhere. It could improve by stating whether child nodes are preserved or if the nodeId changes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero redundancy: the first defines the operation (convert to component) and the second clarifies the replacement mechanism (in place). Information is front-loaded and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive conversion operation with no output schema, the description adequately explains the user-visible transformation but omits critical details like what is returned (the new component node?), whether the original nodeId remains valid, or what happens to attached styles and children.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the schema already documents that nodeId expects a 'FRAME node ID' and that name defaults to the frame's current name. The description reinforces the FRAME requirement but adds no additional syntax, format, or semantic constraints beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Convert') transforming a specific resource type ('FRAME node') into a specific output ('reusable COMPONENT'). It clearly distinguishes from siblings like create_frame (which creates new containers) by emphasizing conversion of existing frames.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies prerequisites by specifying 'existing FRAME node,' suggesting this requires a pre-existing frame. However, it lacks explicit guidance on when to use this versus create_frame or clone_node, and doesn't state limitations (e.g., cannot convert non-frame nodes).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, establishing this is a state-mutating operation. The description adds valuable context that positioning is 'absolute' (not relative/delta), but does not explain the non-idempotent behavior (idempotentHint=false) or coordinate defaults when x/y are omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 10 words. Front-loaded with the action verb, zero redundancy, and every word earns its place. Perfect density for a straightforward transformation tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the core action is clear, the description fails to address the optional nature of x and y coordinates (only nodeIds is required), leaving ambiguity about default behavior or error conditions. For a destructive mutation tool with no output schema, this gap in parameter optionality explanation prevents a higher score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the baseline is 3. The description adds meaningful semantic context by specifying 'absolute position,' clarifying the coordinate system for the x and y parameters beyond the schema's generic 'Target X/Y position' labels. It also correctly implies nodeIds accepts multiple items ('one or more').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description provides a specific verb ('Move'), clear resource ('nodes'), and scope ('absolute position on the canvas'). It effectively distinguishes from siblings like resize_nodes, clone_node, and group_nodes by specifying the absolute positioning behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through 'absolute position' (indicating coordinate-based placement rather than relative), but lacks explicit when-to-use guidance versus alternatives like set_auto_layout or resize_nodes. It also omits what happens when optional x/y parameters are excluded.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose destructiveHint=true and readOnlyHint=false. The description adds conceptual context via the Light/Dark examples but does not disclose behavioral specifics beyond annotations, such as whether existing variables automatically get null values for the new mode or if the operation can fail if the collectionId doesn't exist. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence of approximately 15 words. The parenthetical examples are high-value additions that don't add bulk. Every element earns its place with zero redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple 2-parameter schema and presence of destructive annotations, the description adequately covers the core concept. However, for a destructive operation affecting collection structure, it could improve by mentioning implications for existing variables in the collection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description earns an additional point by providing concrete semantic examples (Light/Dark, Desktop/Mobile) that implicitly guide valid modeName values, even though it doesn't explicitly describe the parameters themselves since the schema already does so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Add'), resource ('mode'), and target ('existing variable collection'). The parenthetical examples (Light/Dark, Desktop/Mobile) effectively distinguish this from sibling tools like create_variable_collection or set_variable_value by clarifying that 'mode' refers to thematic/responsive variants within a collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies prerequisite context by specifying 'existing' collection, suggesting the collection must already exist. However, it lacks explicit guidance on when to use this versus create_variable_collection, or warnings about side effects (e.g., that all variables in the collection may need new values for this mode).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations declare destructiveHint=true, the description adds critical behavioral context that the operation 'cannot be undone via MCP'—specific irreversibility semantics not captured in structured fields. It does not contradict annotations (destructiveHint matches 'Delete').
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste: first states the action, second provides the critical safety warning. Front-loaded and appropriately sized for a single-parameter destructive tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Sufficient for a destructive single-parameter tool without output schema. Covers the essential risk (irreversibility) and references the bulk nature ('one or more'). Could enhance by noting behavior regarding child nodes or references given openWorldHint=true, but not strictly required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema fully documents the nodeIds parameter format ('colon format e.g. ['4029:12345']'). The description mentions 'one or more nodes' but adds no syntax or semantic details beyond the schema, warranting the baseline score for high-coverage schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear specific verb ('Delete') and resource ('nodes'), explicitly distinguishing this from sibling creation tools (create_frame, create_text, etc.) and retrieval tools (get_node, get_nodes_info).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a safety warning ('use with care') and notes irreversibility ('cannot be undone via MCP'), which implies cautious usage. However, it lacks explicit guidance on when to use this versus sibling deletion alternatives like delete_style or detach_instance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a destructive, non-read-only operation. The description adds the critical behavioral constraint that nodes must share the same parent, and clarifies the output is a GROUP structure, though it could specify that nodes become nested children of the new group.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences with zero waste: first establishes the action and result, second states the critical constraint. Perfectly front-loaded and appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the good annotations and complete input schema, the description adequately covers the grouping operation and its primary constraint. It could be improved by describing the nesting behavior (that nodes become children of the new group) or error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema fully documents both parameters including the colon format example and minimum count. The description reinforces the 'two or more' constraint but adds no new semantic information beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Group'), target resource ('nodes'), and result ('into a GROUP'), clearly distinguishing this from sibling tools like ungroup_nodes, move_nodes, or clone_node.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The constraint 'All nodes must share the same parent' provides implicit usage guidance on prerequisites, but there is no explicit guidance on when to prefer this over alternatives like create_frame or how it differs from ungroup_nodes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is a destructive, non-idempotent write operation (destructiveHint=true, idempotentHint=false). The description confirms it modifies nodes but does not add significant behavioral context beyond the annotations, such as side effects, reversibility, or batch operation semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the action and target, with the parenthetical providing essential range clarification without verbosity. No extraneous information is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (2 primitive parameters, 100% schema coverage, no output schema) and comprehensive annotations, the description provides adequate context. It appropriately notes the batch capability ('one or more') and value semantics, though it could explicitly acknowledge the destructive modification aspect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the baseline is 3. The description adds valuable semantic context beyond the schema by mapping the numeric range to visual outcomes (0=fully transparent, 1=fully opaque), which helps prevent usage errors even though the schema documents the 0-1 range.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Set' with the clear resource target 'opacity of one or more nodes'. It effectively distinguishes itself from siblings like set_fills or set_strokes by explicitly focusing on transparency/opacity rather than color or stroke properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clarifies the valid input range (0-1) and its semantic meaning, which guides correct invocation. However, it lacks explicit guidance on when to use this versus alternatives like set_fills (which could handle opacity via RGBA values) or prerequisites for the operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds valuable behavioral context beyond annotations: explicitly states 'keeping position and size' (preservation semantics) which is critical for understanding the operation's non-destructive aspects despite destructiveHint=true. Aligns with annotations (destructive mutation confirmed by 'replacing'). Could improve by mentioning override behavior or return values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 19 words. Front-loaded action verb ('Swap'). Every clause earns its place: specifies target (INSTANCE node), operation (replacing component), and side-effect (keeping position/size). Zero redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a focused 2-parameter mutation tool. Annotations cover safety profile (destructive/non-readOnly), schema covers inputs completely, and description covers core behavioral nuance. Minor gap: no mention of return values or what happens to component overrides, but sufficient given tool scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions including format hints ('colon format') and cross-references to get_local_components. Description provides conceptual mapping ('INSTANCE node', 'component') but does not add syntax or format details beyond schema. Baseline 3 appropriate given schema carries full load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Excellent specificity: uses precise verb 'Swap' with clear resource 'main component of an existing INSTANCE node'. Explicitly distinguishes from siblings like 'detach_instance' (which removes component links) by emphasizing 'replacing it with a different component'. Domain terminology (INSTANCE vs COMPONENT) is precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides implicit guidance through 'keeping position and size' (suggesting layout-preserving replacement), but lacks explicit when-to-use vs alternatives. Does not mention prerequisites like obtaining component IDs via get_local_components first, or when to prefer detach_instance instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations declare destructiveHint=true, the description adds critical behavioral context by clarifying the scope of destruction: only the group container is removed while children are preserved and reparented. This explains the structural side effects beyond the annotation flag. Does not mention error handling for invalid node types.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 12 words with zero waste. Front-loaded with the action verb 'Ungroup' and immediately qualifies the scope. The second clause efficiently explains the dual mechanical effect (reparenting + removal) without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of annotations covering safety profile (destructive, non-idempotent) and 100% schema coverage, the description adequately explains the core operation mechanics. Minor gap: does not specify behavior when non-GROUP node IDs are passed, though openWorldHint=true suggests external validation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage for the nodeIds parameter, the baseline is 3. The description mentions 'one or more' which aligns with the array type, but adds no additional syntax details, validation rules, or format clarification beyond what the schema already provides ('colon format').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Ungroup') with clear resource targeting ('GROUP nodes') and explains the structural outcome ('moving their children to the parent and removing the group'). It clearly distinguishes from sibling tools like group_nodes (inverse operation) and delete_nodes (which would destroy children rather than reparenting them).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage constraints by specifying 'GROUP nodes' and explaining that children are preserved (moved to parent), which guides selection over delete_nodes. However, it lacks explicit 'when to use' guidance, prerequisites, or named alternatives like group_nodes for the reverse operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Strong supplement to annotations: explains exactly what 'destructive' means (the link to main component is broken) and what is preserved (all visual properties). Clarifies the mutation semantics beyond the annotations' destructiveHint=true without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with zero waste. First sentence states the transformation (detach/convert), second clarifies behavioral implications (link broken/properties preserved). Front-loaded with the action and appropriately scoped.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a single-parameter destructive operation. Explains the transformation outcome sufficiently despite lacking output schema. Minor gap: doesn't indicate return value (likely the new frame IDs) or error behavior for invalid instance IDs, though openWorldHint suggests external references are handled.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear description of nodeIds format. Tool description mentions 'one or more' which aligns with the array parameter, but adds no additional semantic details (e.g., what constitutes a valid INSTANCE ID) beyond the schema's example. Baseline 3 appropriate given schema completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Excellent specificity: 'Detach' (verb) + 'component instances' (resource) + 'converting them to plain frames' (outcome). Clearly distinguishes from siblings like swap_component (changes instance target) or delete_nodes (removes nodes) by emphasizing the conversion to plain frames while preserving visuals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context about the operation's effect—breaking the link to main component while preserving visual properties—allowing the agent to infer this is for decoupling instances from their master. However, lacks explicit comparison to alternatives like swap_component or when NOT to use this (e.g., when you want to maintain component links).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds critical behavioral detail beyond annotations: explains that 'Each frame becomes one page in order' (mapping/ordering behavior). Annotations already declare destructive/file-system hints, so description appropriately focuses on content structure rather than repeating safety warnings.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. First sentence delivers core functionality immediately; second sentence provides use-case context. Front-loaded and appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequately complete for a file-export tool: explains input-to-output mapping (frames→pages), file format, and use cases. No output schema exists; while description could mention return value or overwrite behavior given destructiveHint:true, the annotations sufficiently cover the safety profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with full descriptions for both nodeIds and outputPath. Description reinforces the 'ordered' aspect of nodeIds ('in order') but does not add syntax, validation rules, or examples beyond the schema itself. Baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb ('Export') + resource ('frames') + format ('multi-page PDF') clearly stated. Distinguishes from sibling screenshot tools via 'multi-page PDF' and 'pitch decks, proposals' use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear positive guidance ('Ideal for pitch decks, proposals, and slide exports') establishing when to use the tool. Lacks explicit negative guidance or named alternatives (e.g., not mentioning when to use get_screenshot instead).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true; description confirms 'save to local filesystem'. Adds crucial behavioral detail not in annotations: 'Returns metadata only (no base64)'. Missing: idempotency details (annotations say false) or overwrite behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences total. First establishes action and target; second clarifies return format. Zero redundancy—every clause adds distinct value (filesystem persistence vs base64 return distinction).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Good coverage for core functionality given comprehensive schema and annotations. Minor gap: doesn't specify file path handling (absolute vs relative, auto-created directories, overwrite behavior) which is relevant for destructive filesystem operations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3 is appropriate. Description references 'multiple nodes' mapping to items array, but doesn't add syntax/format details beyond what schema already documents for format, scale, and nested item properties.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear specific verb ('Export') + resource ('screenshots for multiple nodes') + scope ('local filesystem'). Distinguishes from sibling 'get_screenshot' by emphasizing file system persistence rather than data return.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage context via 'Returns metadata only (no base64)'—suggesting when to use vs get_screenshot. However, lacks explicit 'when to use' statement comparing to export_frames_to_pdf or other export tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare write/destructive/non-idempotent hints. Description adds valuable behavioral context beyond annotations: it specifies the node creation pattern (rectangle with image fill) and input constraints (PNG/JPG formats). It does not explicitly describe the non-idempotent nature (calling twice creates two nodes) but covers the creation side-effect well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. First sentence front-loads core functionality and mechanism; second sentence provides practical workflow guidance. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters with full schema coverage and annotations present, the description adequately covers the creation behavior and input sourcing. Minor gap: no output schema exists, and description doesn't mention what gets returned (e.g., node ID/object), though this is somewhat implied by the creation context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage, establishing baseline 3. Description adds format constraints (PNG/JPG) not explicitly stated in the schema's 'base64-encoded image data' description, and provides workflow context for sourcing imageData via get_screenshot. It elevates the parameter understanding beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description provides specific verb (Import), resource (base64-encoded image), target (Figma), and structural outcome (rectangle with image fill). It clearly distinguishes from siblings like create_rectangle (empty shape) and get_screenshot (capture only).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly references sibling tool get_screenshot as a workflow source for imageData ('Use get_screenshot to capture images'), establishing a clear tool pairing. Lacks explicit 'when-not-to-use' guidance against alternatives like direct file imports, but provides strong contextual workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is destructive and not read-only. The description adds valuable behavioral context not in annotations: the type constraints (COLOR vs FLOAT) and the ongoing 'driven by' relationship. Minor gap in not explaining the idempotentHint: false behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. The first states the binding concept, the second provides the field-type mapping. Information is front-loaded and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 3-parameter input with full schema coverage and available annotations, the description adequately explains the binding mechanism and type constraints. No output schema exists to describe. Slight deduction for not clarifying overwrite behavior implied by idempotentHint: false.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 100% schema coverage, the description adds essential semantic information: it clarifies that fillColor accepts COLOR variables while all other fields accept FLOAT variables. This type system knowledge is critical and absent from the schema's mere enumeration of valid strings.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the core action ('Bind a local variable to a node property') and the mechanism ('property is driven by the variable's value'), clearly distinguishing this from siblings like create_variable or set_variable_value.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides specific guidance on field selection based on variable type (COLOR for fillColor, FLOAT for others), which is crucial for correct usage. However, it lacks explicit contrast with alternatives like set_variable_value (static value assignment vs. dynamic binding).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Supports annotations (destructiveHint: true) by explaining that 'replace' overwrites all existing reactions. Adds valuable context about mutation behavior (append vs replace) and domain-specific constraints (supported triggers, action types, transition structures) not covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Lengthy but information-dense and well-structured. Front-loads the core purpose and mode behavior, followed by reference lists and necessary examples. Each sentence serves the goal of enabling correct reaction construction; no fluff present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Excellent coverage for a complex domain-specific tool. Compensates for lack of output schema by exhaustively documenting the input structure (nested reaction objects, transition configurations) needed to successfully invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While schema coverage is 100%, the schema only provides minimal type info. The description adds essential semantic depth: enumerated valid values for triggers (ON_CLICK, ON_HOVER, etc.), action types (NODE, URL, BACK), transition syntax, and 6 complete JSON examples showing proper object structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Opens with specific verb 'Set' and clear resource 'prototype reactions on a node'. Distinct from siblings 'get_reactions' (read) and 'remove_reactions' (delete) through its write-oriented vocabulary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use 'replace' vs 'append' modes (overwrite vs add). However, lacks explicit contrast with sibling tools like 'remove_reactions' or 'get_reactions' regarding when to choose this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true and readOnlyHint=false. The description adds valuable operational context beyond these annotations: specifically, the workflow recommendation to fetch current state via get_reactions before selective removal, and the behavioral distinction between omitting vs providing an empty array for 'remove all'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three tightly constructed sentences with zero redundancy. Front-loaded with purpose ('Remove prototype reactions...'), followed by usage patterns for bulk vs selective removal, and ends with actionable prerequisite. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter destructive mutation tool with 100% schema coverage and comprehensive annotations, the description is complete. It covers purpose, parameter semantics via workflow guidance, and operational prerequisites. No output schema exists requiring description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, establishing a baseline of 3. The description adds practical context about how to populate the 'indices' parameter (via get_reactions first) and reinforces the 'omit vs empty array' behavior for removing all items, providing usage semantics beyond raw schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with specific verb 'Remove' + resource 'prototype reactions' + target 'from a node'. Clearly distinguishes from siblings like set_reactions (which adds/modifies) and get_reactions (which reads), and from delete_nodes (which removes the node itself).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly guides when to use which mode: 'Omit indices to remove all reactions' vs 'Provide a zero-based indices array to remove specific reactions'. Critically, it instructs to 'use get_reactions first to see current indices', establishing a clear workflow prerequisite with a sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
How to claim the server?
If you are the author of the server, you simply need to authenticate using GitHub.
However, if the MCP server belongs to an organization, you need to first add glama.json to the root of your repository.
{
"$schema": "https://glama.ai/mcp/schemas/server.json",
"maintainers": [
"your-github-username"
]
}Then, authenticate using GitHub.
Browse examples.
How to make a release?
A "release" on Glama is not the same as a GitHub release. To create a Glama release:
- Claim the server if you haven't already.
- Go to the Dockerfile admin page, configure the build spec, and click Deploy.
- Once the build test succeeds, click Make Release, enter a version, and publish.
This process allows Glama to run security checks on your server and enables users to deploy it.
How to add a LICENSE?
Please follow the instructions in the GitHub documentation.
Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear on the server after some time, you can manually trigger a new scan using the MCP server admin interface.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Latest Blog Posts
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/vkhanhqui/figma-mcp-go'
If you have feedback or need assistance with the MCP directory API, please join our Discord server