figwright
Server Quality Checklist
Latest release: v0.1.3
- Disambiguation4/5
With 112 tools, there are a few clusters that could confuse an agent, such as the multiple node-reading tools (get_document, get_node, get_nodes_info, get_design_context, get_selection) and the mapping tools (component_map, icon_map, token_map). However, each tool's description clearly delineates its specific purpose and usage context, so the overlap is mostly resolvable. Overall, the tools are distinct enough for a careful agent.
Naming Consistency4/5The vast majority of tools follow a consistent verb_noun pattern (create_frame, set_fills, get_node, delete_nodes, rename_page, apply_animation_style). A few deviations exist, such as token_map, component_map, icon_map, design_diff, and the bare verb batch, but these are minor and do not significantly hinder predictability. The naming convention is coherent overall.
Tool Count1/5At 112 tools, this server is far beyond the typical well-scoped range and exceeds the 50-tool threshold for an extreme mismatch. While the Figma design-to-code domain is broad, the tool set could likely be consolidated or organized into sub-modules to reduce cognitive load. The sheer number makes it unwieldy for an agent to discover and select the right tool.
Completeness4/5The tool set covers the full lifecycle of Figma operations: node CRUD, styling, text, variables, styles, components, prototypes, motion, exports, and project mapping. Minor gaps exist, such as no delete_variable_mode or rename_variable_collection, and no explicit tool to read variable bindings in isolation (though get_design_context provides this). Overall, the surface is remarkably complete for the domain.
Average 4.5/5 across 100 of 112 tools scored. Lowest: 3.7/5.
See the Tool Scores section below for per-tool breakdowns.
- 4 of 5 community issues answered or closed in the last 6 months
- 243 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
Add related servers to improve discoverability.
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.
Tool Scores
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is not read-only and not destructive. The description adds the edge case that positionless nodes are skipped and the return shape { ok, affected }, providing useful behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the action, a caveat, and the return value. Every word earns its place, making it concise and well-structured.
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?
The tool is simple, and the description covers the operation, inputs, an edge case, and the return format. Without an output schema, mentioning { ok, affected } is valuable. It lacks explicit units or coordinate system details, but these are likely inferred from the Figma context.
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?
The schema already documents all parameters with descriptions (dx, dy defaults, nodeIds). The description repeats the dx/dy concept but does not add meaning beyond the schema, so the baseline of 3 applies.
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 verb 'Translate' with the resource 'nodes' and delta (dx, dy) clearly specifies a relative movement operation. It is distinct from absolute positioning tools like set_position, but the description does not explicitly name an alternative, so it does not fully differentiate from siblings.
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 this tool versus alternatives such as set_position or reorder_nodes. The note 'Nodes without a position are skipped' is a behavioral constraint, not a usage recommendation, so the agent lacks direction for tool selection.
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 readOnlyHint=false and destructiveHint=false, so the agent knows it's a non-destructive mutation. The description adds information about the field slot and the return value, but does not disclose whether applying a style overrides an existing one or whether the style must already exist.
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 concise sentences front-load the purpose, then explain the parameter and return value. There is no redundancy or fluff.
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 behavior is clear, the description omits potential constraints such as required compatibility between the style type and the selected field, or whether existing bindings are replaced. For a simple mutation tool with no output schema, this leaves some gaps for an agent to infer.
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 schema description covers 67% of parameters, missing the `field` parameter. The description explicitly explains that `field` selects the applicable slot (fill/stroke/effect/grid/text), providing meaning beyond the enumeration. nodeId and styleId are already described in the schema, so the description adds targeted value.
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's function with a specific verb ('Bind') and resource ('shared style to a node'). It also explains the `field` parameter's role and the return value, distinguishing it from sibling tools like set_fills or set_strokes.
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 does not provide guidance on when to use this tool versus alternatives such as set_fills, set_strokes, or create_paint_style. There is no explicit mention of prerequisites or when this approach is preferred over direct style application.
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?
The description discloses important behaviors: layoutMode NONE disables auto layout, it returns { ok, nodeId }, and it uses CSS analogues (row-gap, align-content) to explain cross-axis behavior. Since annotations only provide readOnlyHint=false and destructiveHint=false, this extra context is valuable. It does not cover error cases or side effects on existing layout properties, but it exceeds the minimum required.
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 dense sentence but uses semicolons and parentheses to organize the mode-specific parameter groups. It is front-loaded with the core purpose and delivers substantive detail without fluff. While it could be split into bullets for readability, every phrase serves a purpose.
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?
With 18 parameters and no output schema, this description needs to carry a lot of weight. It explains the main modes, return shape, and some parameter interactions, but it omits defaults, comprehensive enum explanations, and any mention of errors or prerequisites. The tool is complex enough that a longer description or examples would be warranted.
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 description coverage is low (22%), so the description compensates by grouping parameters by mode and adding CSS context for counterAxisSpacing, counterAxisAlignContent, itemReverseZIndex, and strokesIncludedInLayout. It clarifies which parameters apply to which layout modes, which is critical for correct usage. However, it does not explain every parameter (e.g., primaryAxisAlignItems, counterAxisAlignItems, padding values), so it stops short of full compensation.
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 action ('Configure a frame's auto layout') and clearly enumerates the three layout modes (NONE, HORIZONTAL/VERTICAL, GRID) and their associated parameters. However, it does not explicitly distinguish itself from the overlapping sibling tool set_layout_props, so it misses the top score for sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by detailing what each layout mode does, but it never explicitly states when to choose this tool over set_layout_props or set_layout_grids, nor does it mention any prerequisites (e.g., node must be a frame). The context is clear but no exclusions or alternatives 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 indicate readOnlyHint=false and destructiveHint=false, so the description's 'Create' aligns. The return shape '{ ok, nodeId, name, type }' adds value beyond annotations, but no deeper behavioral context (e.g., where the page is created, side effects) is disclosed.
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?
One concise sentence with an added return-type note. Front-loaded, zero waste, and appropriately sized for a simple tool with one optional parameter.
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 (1 optional parameter), annotations, and inclusion of return shape, the description is largely complete. However, it could benefit from context like 'in the current document' to clarify scope, though this is inferable from sibling tools and the domain.
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 the 'name' parameter described as 'Optional page name'. The description adds that the page is 'optionally named', which is essentially redundant with the schema. No additional parameter meaning is provided 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 explicitly states the action ('Create a new page') and the optional naming behavior, clearly distinguishing it from sibling tools like delete_page, rename_page, and navigate_to_page.
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 (when you want to create a page) but provides no explicit when-to-use guidance, exclusions, or alternatives. Context can be inferred from the tool name and sibling list, but it is not stated.
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 readOnlyHint=true, so the read-only nature is covered. The description adds the return structure but does not disclose additional behavioral traits such as error handling, permissions, or rate limits. While it provides value by explaining the output format, it does not go beyond the annotation'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 two sentences, front-loaded with the core purpose and return format, and every sentence adds value. It avoids unnecessary detail and is well-structured for quick comprehension.
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 simple read-only tool with one parameter and no output schema, the description fully explains the return value structure and the concepts involved. It covers all necessary context without being verbose, making it complete for this tool's complexity.
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 description coverage is 100% for the single nodeId parameter, which already defines it as a Figma node id. The description mentions 'on a node' but does not add meaningful semantics beyond what the schema provides, so it meets the baseline for high coverage.
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 returns prototype reactions on a node, with a specific verb ('Return') and resource ('prototype reactions on a node'). It provides the return shape, which distinguishes it from sibling mutation tools like set_reactions and remove_reactions.
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 for reading reactions, but it does not explicitly state when to use it versus alternatives or mention exclusions. The read-only intent is clear from the verb, but there is no direct guidance on when to prefer this over other reaction-related 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 only provide readOnlyHint=false and destructiveHint=false. The description adds meaningful behavioral context: it replaces any existing track on the field, returns `{ ok, nodeId }`, and notes the beta and Figma-Design-only restrictions. This exceeds what annotations reveal, though it could more prominently state the replacement side-effect.
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 well-structured sentences: purpose with examples, parameter walkthrough, and behavioral/return/platform note. Every sentence adds value and there is no 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?
For a complex tool with nested objects and no output schema, the description covers the return shape, replacement semantics, and platform/beta caveats. It lacks error/edge-case guidance, but the rich schema and sibling context make it reasonably 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?
Schema description coverage is 100%, with every parameter and nested property already described in the schema. The description's summary of `field` and `track` restates schema content without adding new meaning, so the baseline of 3 applies.
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 specific verb ('Set'), a clear resource ('hand-authored Figma Motion keyframe track'), and scope ('on a node for one field'), followed by concrete field examples. This makes the tool's purpose unambiguous and distinguishes it from siblings like `remove_manual_keyframe_track` and `apply_animation_style`.
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 scenarios through phrases like 'hand-authored' and 'Replaces any existing track on that field,' but it never explicitly says when to use this tool instead of `apply_animation_style` or when not to use it. The beta/Design-only note is a constraint, not a comparative guideline.
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 non-read-only and non-destructive behavior. The description adds valuable behavioral context: Figma auto-creates a default mode, and the return shape is explicitly given as { ok, collectionId, defaultModeId, name }. This goes beyond the annotation information and helps the agent understand side effects and output.
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 two sentences, concise and front-loaded with the main action. It includes only essential information about the default mode and return value, with no unnecessary detail or repetition.
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 tool's simplicity (one parameter, no output schema), the description covers purpose, side effect, and return value. It does not explain edge cases or error behavior, but such detail is not critical for this straightforward creation tool. The provided information is sufficient for correct invocation.
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?
The input schema fully describes the only parameter 'name' with an example ('Theme'). The description does not add additional parameter semantics beyond the schema, so the baseline score of 3 is 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?
The description clearly states the action: 'Create a variable collection.' It is specific to the resource and distinct from sibling tools like 'create_variable' and 'add_variable_mode.' The added note about Figma auto-creating a default mode further clarifies the tool's purpose.
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 the tool is used when creating a variable collection, but it does not explicitly state when to use it versus alternatives or provide exclusions. No mention of when not to use it or other contexts, leaving usage guidance somewhat implicit.
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 indicate this is a write operation (readOnlyHint=false) and not destructive. The description adds the return format and the non-empty list requirement, but does not disclose potential side effects such as reparenting or repositioning existing nodes. It provides some behavioral context beyond annotations but not extensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, with the purpose stated first and the requirement/return value second. There is no redundant phrasing, and it is well-structured for quick reading.
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 simple mutation tool with full schema coverage and annotations, the description covers purpose, a usage constraint, and the return value. It lacks details about error conditions or the effect on the original nodes, but these are not critical for basic understanding. Overall, it provides sufficient context for an agent to select and invoke the 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?
Schema descriptions cover both name and nodeIds, giving a baseline of 3. The tool description adds the constraint that nodeIds must be a non-empty list, which is not present in the schema. It does not further explain the name parameter beyond the schema, so the added value is moderate.
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 verb 'Group' with the resource 'nodes under their shared parent', clearly indicating the action and scope. It also mentions the return value for the new group, which distinguishes it from sibling tools like ungroup_nodes and 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage from its purpose and the requirement that nodeIds be non-empty, but it does not explicitly state when to use this tool versus alternatives like reparent_nodes or move_nodes. No exclusionary guidance is provided, so the usage context is only implied.
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 non-read-only, non-destructive operation. The description adds useful behavioral details beyond the annotations: nodes without rotation are skipped, and it returns { ok, affected }. This clarifies the tool's edge case behavior and return shape, though it does not mention permissions or undo 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 two sentences with no redundant content. The primary action is front-loaded in the first sentence, and the second sentence adds essential behavioral info. Extremely concise and well-structured.
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 simplicity of this tool (two required params, full schema coverage, annotations present), the description is nearly complete. It covers the core action, the skip behavior, and the return value. It does not discuss prerequisites or usage alternatives, but for a simple mutation tool this is not a significant gap.
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?
The input schema already provides full descriptions for both parameters ('Node ids to rotate' and 'Rotation in degrees'). The description adds the word 'absolute' but otherwise doesn't significantly enrich the parameter meaning beyond what is in 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 clearly identifies the tool's purpose: 'Set absolute rotation (degrees) on nodes.' It specifies the resource (nodes) and the action (setting rotation), and the mention of 'absolute rotation' distinguishes it from relative rotation or other transformation tools like set_position.
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 this tool is for rotating nodes but provides no explicit guidance on when to use it versus alternatives like set_position or resize_nodes. It lacks any exclusions or references to sibling tools, so usage context is only implied.
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?
Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses the return format `{ ok, nodeId }`, which is useful since no output schema exists. However, it does not state whether setting effects replaces existing effects, whether shadows require a visible flag, or any permission requirements. The return value adds some transparency, but key behavioral details are missing.
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 two sentences, front-loaded with the primary verb and resource. The first sentence states the action, the second clarifies parameter requirements and the return value. There is zero 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 tool's complexity (two parameters, one being a nested array), the description plus schema covers the essentials: what the tool does, required parameter details, and return value. It lacks explicit mention of behavior like replacing existing effects, but the provided information is sufficient for an agent to select and call the tool correctly in most cases.
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%, so the baseline is 3. The description adds meaningful information beyond the schema by clarifying that shadows need color + offset and blurs need radius. This is especially valuable because the schema lacks a description for the radius field, making the description's clarification necessary for correct invocation.
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 starts with a specific verb and resource: 'Set a node's effects.' It clearly distinguishes this from sibling tools like set_fills or set_text by naming the effect types (DROP_SHADOW, INNER_SHADOW, LAYER_BLUR, BACKGROUND_BLUR). The scope is unambiguous.
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 context of use is implied: it applies effects to a node. However, it does not explicitly state when to use this tool versus alternatives like set_reactions or set_fills, nor does it mention any exclusions or prerequisites. There is clear functional context but no direct comparison with sibling 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 already declare readOnlyHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond annotations by specifying that output preserves input order and missing ids yield null, which is not present in the schema or 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 concise at two sentences, with the primary action front-loaded. Every word adds value, and there is no redundant filler or repetition of schema information.
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?
Given the tool's simplicity (one parameter, clear annotations), the description is complete. It covers input behavior (multiple ids), output behavior (order preservation, null slots), and the read-only nature is already annotated, making this a fully self-contained description.
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?
The input schema provides 100% coverage for the sole parameter nodeIds, with a clear description 'Figma node ids to fetch'. The tool description adds no additional semantic detail about parameter formatting, but the schema fully documents it, so baseline 3 is 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?
The description clearly states the tool returns multiple Figma nodes by id, distinguishing it from the singular get_node tool. It also specifies behavioral details about output ordering and null handling, which further clarifies its purpose.
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 for batch node retrieval via 'multiple nodes by id', but it does not explicitly contrast with alternatives like get_node or mention when not to use this tool. Sibling tool names are given but not referenced in the description itself, so usage guidance is only implied.
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 not read-only and not destructive, but the description adds crucial behavioral details: per-platform semantics ('a non-empty string sets the declaration, null removes it, an omitted platform is untouched'), the return shape ('Returns { ok, variableId, name, codeSyntax }'), and the distinction between setting and removing. This goes beyond the bare annotation flags, though it doesn't discuss permissions or failure modes.
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 four sentences and packs a lot of information: the core purpose, per-platform behavior, a use-case scenario, and the return value. It is front-loaded with the action and resource, and every sentence contributes meaning. It is slightly long but not padded; the only minor redundancy is the example echoing the schema example.
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?
Even though there is no output schema, the description explicitly list the return fields and the effect on state. It covers the write operation's semantics, the three platform behaviors, and a motivating scenario. It doesn't address error conditions or prerequisites, but for a focused mutation tool with good annotations, this is sufficient. It earns a 4 rather than a 5 because it could briefly mention idempotency or what happens when an invalid variableId is provided.
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?
The schema already has 100% parameter coverage with descriptions for both 'variableId' and the nested 'codeSyntax' object, including the string/null/omitted semantics. The description essentially paraphrases the schema's own text ('Per-platform declarations: string sets, null removes, omitted is untouched'). The example adds a little color, but the description provides no new semantic information beyond what the schema already conveys, so it lands at the baseline for high schema coverage.
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 specific verb and resource: 'Declare a variable's code-side token name per platform (codeSyntax)'. It clearly distinguishes itself as the 'write half' of codeSyntax, explicitly referencing the read counterparts (get_design_context / get_variable_defs), and provides a concrete example (WEB: "--color-primary"). This leaves no ambiguity about what the tool does and differentiates it from sibling mutation tools like set_variable_value or rename_variable.
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 description provides a clear use case: 'When authoring design-system variables from existing code tokens, declare the source token name here so future codegen resolves to the exact token instead of deriving a name.' It also establishes context by naming the read counterparts, implying when you need to query codeSyntax you would use those instead. However, it doesn't explicitly list alternatives or state when not to use the tool, so it falls just short of a 5.
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?
Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses the return format, the plan-gating behavior (Starter allows 1 per collection), and the failure guidance. This adds significant behavioral detail that annotations don't capture, though it doesn't mention potential edge cases like duplicate mode names.
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 concise yet information-dense: it states what the tool does, what it returns, and how it behaves under plan constraints. No filler words; each sentence earns its place. Well-structured for AI consumption.
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 two-parameter tool with no output schema, the description covers the action, return value, and a key failure mode. It doesn't explicitly state prerequisites like collection existence or name uniqueness, but the core usage is sufficiently complete. A minor gap, hence 4.
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 both parameters (name and collectionId) having descriptions. The tool description adds only a minor example ("Dark") that repeats the name parameter's schema description, but does not add new meaning beyond the schema. Baseline 3 is 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?
The description clearly states the tool's action: 'Add a mode (e.g. "Dark") to a variable collection.' This is a specific verb+resource that distinguishes it from sibling tools like create_variable_collection or set_variable_value, and even includes the return shape for additional clarity.
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 description provides clear context for when to use the tool (when adding a mode to a variable collection) and includes a specific alternative guidance: when the plan blocks a new mode, fall back to a paired collection. While it doesn't explicitly enumerate exclusions, it offers a practical when-not-to and alternative.
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 readOnlyHint=false, so the description adds value by disclosing the side effect: 'The components are reparented into the new set under parentId.' It also states the return shape, which helps set expectations. Minor gaps exist (e.g., no mention of permission/undo), but it goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no fluff: the core action, a necessary prerequisite, and side-effect/return info. It is front-loaded and every sentence adds value.
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?
The description covers the action, prerequisite, side-effect, and return value. There's no output schema, so including the return format is beneficial. Minor edge-case behaviors (error conditions for non-COMPONENT nodes) are left to the schema, but overall it's sufficiently complete for a 3-parameter mutation tool.
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 each parameter described in the input schema. The description adds little beyond the schema, aside from restating the default parent behavior already present in the schema. Baseline 3 is appropriate given full schema coverage.
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 action: 'Combine two or more existing COMPONENT nodes into a single COMPONENT_SET (a variant set).' It uses a specific verb and resource, and differentiates from sibling tools like group_nodes or reparent_nodes by explicitly targeting variant-set creation.
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 clear context and a prerequisite: 'Name each component with Figma variant syntax... beforehand so the set derives its properties.' No alternatives or exclusions are mentioned, but the usage intent is well-understood.
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 readOnlyHint=false and destructiveHint=false, consistent with a creation operation. The description adds value by specifying the return shape ({ ok, styleId, name }) and conditional requirements (shadows need color+offset, blurs need radius), which are not in the annotations. This gives the agent more context about expected behavior and 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 sentences deliver the core purpose, the parameter requirements, and the return value. No filler or redundant phrasing; every sentence adds new information. Front-loaded with the action verb.
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 creation tool with no output schema, the description provides the return shape and parameter guidance, which is sufficient for basic invocation. It doesn't mention error conditions or whether the style is added to the current page or document, but 'local' implies current context. The complexity of the effects array is addressed by the shadow/blur distinction.
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 only 33% – only color and offset have descriptions. The tool description compensates by explaining the semantic distinction between shadow and blur parameters, which directly tells the agent when to provide color/offset vs radius. However, it doesn't explain 'spread' or the optional 'description', so some parameter semantics still rely on the schema field names.
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 'Create a local effect style' – a specific verb and resource that clearly identifies the operation. It distinguishes effect styles from other style types (paint/text/grid) via the 'effect' qualifier, and the 'local' scope differentiates from shared/team styles. The parameter note about shadows vs blurs further confirms this is specifically about effect styles.
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 for creating effect styles but does not explicitly contrast with sibling tools like update_effect_style or apply_style_to_node. It says 'local effect style', which suggests use for file-local styles, but no when-not guidance is provided. There's no mention of alternatives, so the agent must infer from sibling names.
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 indicate non-read-only and non-destructive behavior, so the description adds a return shape ({ ok, nodeId, name, type }) and default parent context. It does not disclose side effects on existing nodes, coordinate system details, or error behavior, but this is acceptable given annotation coverage and the simple creation task.
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, front-loaded with the core action, and every clause earns its place—covers default behavior, the circle condition, and a pointer to a related tool. No 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?
Without an output schema, the description provides the return shape, which is valuable. It covers the main functionality (create, optional attributes, parent default) and directs to set_arc for further shaping. It omits potential edge cases like invalid parentId or coordinate system units, but for a creation tool with a well-described schema, this is adequate and near complete.
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 covers 100% of parameters with descriptions, so baseline is 3. The description adds meaningful nuance: 'circle when width equals height' clarifies the relationship between width and height, and 'default: current page' reinforces the parentId default (already in schema but helpful to highlight). No parameter semantics are contradicted.
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 verb and resource: 'Create an ellipse', with a helpful clarification that equal width/height produces a circle. It distinguishes from sibling tools like create_rectangle and create_text by focusing on ellipse-specific behavior, including optional attributes and default parent.
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: the tool creates an ellipse with optional sizing/naming/positioning under a parent (default current page). It explicitly routes to set_arc for transforming into pie/arc/ring, giving an alternative for subsequent needs. It does not explicitly contrast with create_rectangle, but the resource type is unambiguous.
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?
The description adds value beyond the destructiveHint annotation by specifying the return payload (`{ ok, styleId, name }`). It confirms the destructive nature and scopes to local styles, though it does not detail side effects or error conditions.
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, front-loaded sentence that immediately states the action and resource, followed by the return value. No wasted words.
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?
With only one parameter, no output schema, and clear annotations, the description is largely complete for this simple tool. It covers what is deleted, by what identifier, and what is returned. Minor gaps like error handling or style-in-use behavior are not critical given the simplicity.
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 description coverage is 100%, so the parameter `styleId` is already well-documented in the schema. The description's mention of 'by id' confirms the parameter's purpose but does not add new meaning 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 clearly states the tool deletes a local style by id and enumerates the style types (paint/text/effect/grid). This specific verb+resource combination distinguishes it from sibling tools like delete_variable and delete_page.
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 description gives clear context that this deletes local styles by id, implying it is the appropriate tool for that action. It does not explicitly name alternatives or exclusions, but the context is sufficiently unambiguous.
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 readOnlyHint=true, so the read-only nature is known. The description adds that children are returned recursively and that geometry, rotation, opacity, cornerRadius, and fills are enriched, which is useful. However, it does not disclose potential limitations (e.g., handling of very large trees, what happens if no page is active) or output structure details.
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, front-loaded sentence that efficiently communicates the tool's action, scope, and output details. No unnecessary words or repetition.
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 no output schema, the description lists the enriched fields (base geometry, rotation, opacity, cornerRadius, fills), giving a good sense of the output. It is reasonably complete for a read-only tree retrieval tool, though it could mention error conditions or the exact shape of the returned tree.
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?
There are zero parameters, so the baseline is 4. The description clarifies that the tool operates on the 'active Figma page', which provides meaningful implicit context about what is being returned without needing schema parameters.
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 returns the full recursive node tree of the active Figma page, with specific enrichment fields. This distinguishes it from siblings like get_node (single node) and get_nodes_info (specific nodes) by explicitly targeting the entire tree.
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 description implies when to use this tool: when you need the complete page tree rather than specific nodes. It gives clear context but does not explicitly name alternatives or include when-not-to-use instructions, so it falls short of full guidance.
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?
The annotation readOnlyHint=true already signals a safe read operation. The description adds value by explaining the meaning of editorType modes ('dev' is read-only, 'figjam' lacks components/variables/styles), which is behavioral context beyond the annotation. No contradiction exists.
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, well-structured sentence that front-loads the verb and resource, uses a colon to list contents, and appends a clarifying parenthetical. Every clause earns its place with no 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?
For a zero-parameter tool with no output schema, the description adequately enumerates all return fields (fileName, current page, references, editor type/mode) and adds necessary context about editor modes. Minor ambiguity around 'all page references' prevents a perfect 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?
The tool has zero parameters, so the description correctly omits parameter syntax. Per the rubric, a 0-parameter tool receives a baseline of 4, and no additional parameter details 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?
The description opens with 'Return file metadata' and enumerates specific fields: fileName, current page, all page references, and editor type/mode. This clearly distinguishes it from sibling tools like get_document or get_node, which focus on document structure rather than file-level metadata.
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 when to use the tool—when you need file metadata or editor context—but does not explicitly name alternatives or exclusions. The note about 'dev' and 'figjam' provides some interpretive context but stops short of guiding tool selection among siblings.
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?
The readOnlyHint annotation already indicates a safe read operation. The description adds valuable behavioral context by specifying the return structure (center, zoom, bounds) and the meaning of zoom (1.0 = 100%). No contradiction exists, and the added detail goes beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence. It front-loads the main action and return type, then provides clarifying details. No unnecessary words or repeated information from the schema or annotations.
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 simple tool with no parameters and no output schema, the description covers the essential behavior: what is returned and what each field signifies. The only minor gap is not specifying the coordinate system or reference frame for 'bounds', but this is a reasonable omission for a viewport getter.
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 there is nothing to document. The baseline for no-parameter tools is 4, and the description compensates by explaining the output semantics in detail, which is especially useful given that no output schema exists.
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's purpose with a specific verb ('Return') and resource ('current page viewport'), and enumerates the exact return fields. This makes it easy to distinguish from sibling getters like get_selection or get_document, which target different aspects of the document state.
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 does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions. However, the purpose is self-evident as a read-only viewport query, so usage is implied. Absence of explicit sibling differentiation keeps this at a mid-range score.
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?
Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses key behavioral traits: partial updates via omitted fields, and the return payload shape { ok, styleId, name }. This adds useful context about idempotency and the response format, though it does not cover error cases or permissions.
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, concise sentence that immediately states the operation, then adds the key partial-update rule and return value. Every word earns its place with no fluff or repetition.
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 this is a straightforward single-entity update with one required parameter, the description covers the essentials: what is updated, how partial updates behave, and what is returned. It lacks detail on error handling or auth, but those are less critical for this tool's complexity, and the annotations fill 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 50%, with styleId and paints described in the schema, while name and description are not. The description clarifies that any of these three may be omitted to leave unchanged, adding value for the undocumented parameters. However, it does not elaborate on value formats or constraints beyond what the schema already provides for paints.
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 'Update an existing paint style by id', providing a specific verb, resource, and the identifier used to target the style. It clearly distinguishes this from sibling tools like create_paint_style or update_text_style by stating the resource and the partial-update semantics.
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 description clearly indicates the tool is for updating existing paint styles and explains that omitted fields remain unchanged, which guides use. However, it does not explicitly contrast with alternative tools (e.g., create_paint_style for new styles) or state when not to use it, stopping just short of the best-possible guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the readOnlyHint annotation, detailing the AST scan, the override mechanism with docs/figma-component-map.md, handling of staleOverrides degrading to fuzzy results, mapping each component once, and reporting matchedProps/unmatchedProps. This extensive disclosure gives the agent a deep understanding of the tool's behavior without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively long but every sentence contributes substantive detail about the tool's logic, edge cases, and outputs. There is minor repetition of the 'reuse' theme, but overall it is structured and information-dense without unnecessary fluff.
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 tool's complexity and the absence of an output schema, the description provides a comprehensive overview including the return structure ('{ mappings ... unmapped, staleOverrides, profile }'), the override mechanism, and how stale entries are handled. It is sufficiently complete for an agent to select and invoke the tool correctly, though more detail on the 'candidate' fields could be added.
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?
The input schema covers 100% of the parameters (nodeId, rootDir, threshold) with descriptive text. The tool description does not add significant parameter-level detail; it focuses on high-level behavior. Since schema coverage is complete, the baseline of 3 applies.
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's function: 'Map the Figma component instances in a selection/subtree to existing local code components, so they can be reused instead of regenerated.' This provides a specific verb (map), resource (Figma component instances to code components), and purpose. It also distinguishes itself from sibling tools like scan_components or get_local_components by focusing on mapping/reuse.
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 description gives clear context for when to use the tool: when you need to map Figma components to existing local code components for reuse. It implies the scenario ('so they can be reused instead of regenerated') but does not explicitly mention when NOT to use it or provide alternative tool names. Thus it meets the 'clear context, no exclusions' bar.
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?
The readOnlyHint annotation already declares a safe read operation, and the description adds valuable context by specifying the return structure and the conditional page-scan behavior. It does not disclose performance implications, but the annotation covers the safety profile adequately.
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, front-loaded sentence that efficiently conveys the core purpose and both usage modes without redundant wording or unnecessary detail.
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 simple read tool with one optional parameter and no output schema, this description fully covers the return format and both invocation paths. An agent can invoke it correctly without needing additional assumptions.
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?
The input schema fully documents nodeId, including the omit-to-scan-current-page behavior. The description echoes this but adds no new parameter-specific details beyond the schema, so the baseline of 3 is 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?
The description clearly states the tool 'Return[s] Dev Mode annotations' and specifies the exact output shape. It also distinguishes two modes (with or without nodeId), making its purpose unambiguous and differentiating it from sibling read tools like get_metadata or get_selection.
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 description gives clear context on when to use each mode: include nodeId for a specific node, or omit to scan the current page. It does not explicitly mention alternatives or when-not-to-use, but the dual-mode guidance is sufficient for effective usage.
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?
Beyond the readOnlyHint annotation, the description adds meaningful behavioral details: it returns a structured object, recursively scans a subtree, and only includes local components/sets. It also discloses what data each result type carries (variantProperties, variantGroupProperties, variant component ids), which helps the agent understand the operation's side-effect-free, read-only nature and output shape.
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 three dense sentences, each earning its place: the first states the purpose and return shape, the second explains scope and usage, and the third details the data carried by components and component sets. There is no filler or repetition of schema content.
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?
With no output schema, the description fully specifies the return structure ({ components, componentSets }) and the attributes of each component type. It also explains the nodeId selection fallback, making the tool's behavior complete for a one-parameter read-only operation.
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?
The schema already covers the single parameter nodeId with a clear description ('Root node id to scan within; omit to use the current selection'), giving 100% schema coverage. The description reinforces the 'pass nodeId or select frames' behavior but adds no new meaning beyond the schema, so a baseline score of 3 is 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?
The description uses a specific verb ('Return') and names a precise resource ('components and component sets within a node subtree or the current selection'). It clearly distinguishes itself from document-wide scanning tools by emphasizing 'Scans a subtree, not the whole document', which differentiates it from siblings like scan_components or component_map.
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 description provides clear usage context: it scans a subtree rather than the whole document, with two ways to scope the operation ('pass nodeId, or select the frames to scan'). It stops short of explicitly naming alternative tools for whole-document scans, but the 'not the whole document' note effectively communicates 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals safety, and the description adds useful edge-case context: returns motion: null for nodes without Motion, and playheadPosition only in the Design editor with an active timeline. This goes beyond the annotation without contradicting it.
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?
Four sentences densely pack purpose, timing, return shape, and edge cases without filler. The structure is logical: what it reads, when to call, what it returns, and when special fields appear. Every sentence 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?
Despite no output schema, the description provides a concrete return structure and covers the two main edge cases (motion: null, conditional playheadPosition). For a single-parameter read tool, this is complete enough for an agent to invoke correctly and interpret results.
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?
The input schema already documents nodeId with 100% coverage, so the description adds little about the parameter itself. It repeats the return object shape including nodeId, but this is output semantics, not added input meaning. Baseline 3 is 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?
The description clearly states the tool reads a node's Figma Motion state and enumerates specific data components (animationStyles, animations, manualKeyframeTracks, timelines). It distinguishes itself from sibling mutation tools by framing this as the discovery/read operation, and its 'Call it before editing' guidance reinforces its role.
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 explicitly says to call it before editing to discover styleIds, timelineIds, and existing keyframes. It also explains when the playheadPosition return is meaningful (when the user means 'here'). It doesn't name alternative tools, but the situational guidance is clear.
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 readOnlyHint=true, and the description adds context about the output format, including collections, modes, variables, resolvedType, and valuesByMode, which goes beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, efficient, and front-loads the main purpose while providing necessary detail about return types and special cases.
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?
Despite no output schema, the description fully specifies the return value structure, including aliases, RGBA colors, and easing curves, making it complete for a read-only tool with no parameters.
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?
There are no parameters, so the description doesn't need to explain parameter semantics. The baseline of 4 applies.
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 action ('Return') and the resource ('the document's local variables'), and details the output structure, distinguishing it from sibling tools that handle other resources or mutations.
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 the tool is for retrieving local variable definitions, but it does not explicitly state when to use it over alternatives or provide exclusions, like naming a sibling tool for different contexts.
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 declare readOnlyHint=false and destructiveHint=false. The description adds behavioral context by noting that subsequent tools operate on this page and that it returns { ok, nodeId }, which is useful side-effect and return-value information.
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, no waste, key information front-loaded.
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 simple one-parameter navigation tool with annotations and full schema coverage, the description provides sufficient context about behavior and return value.
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 description coverage is 100%, with pageId described as 'Page id to navigate to'. The description adds the context of switching the active page, but no additional parameter semantics.
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's function with a specific verb ('Switch') and resource ('active page'), and distinguishes it from sibling tools like delete_page or add_page by its role in context-setting.
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 clear context: 'Subsequent selection / read tools operate on this page' implies this should be called before those tools, but it doesn't explicitly exclude alternatives or name specific sibling 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 convey that the tool is mutating but not destructive; the description adds meaningful behavioral context: 'Detached nodes are skipped' and 'Returns { ok, affected }', which are not derivable from annotations or schema. This goes beyond the baseline and provides useful operating detail.
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 two concise sentences with no wasted words. It front-loads the core purpose and immediately follows with key behavioral notes and the return shape. Every sentence 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 simple 2-parameter tool with no output schema and existing annotations, the description covers the essential aspects: what it does, edge-case behavior (detached nodes), and the return format. This is complete for an AI agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes both parameters with 100% coverage ('index' as 'Target index within the parent' and 'nodeIds' as 'Node ids to reorder'). The description adds no additional parameter-level meaning beyond what the schema already provides, so it meets the baseline but does not exceed it.
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's function: 'Reorder nodes within their current parent by inserting each at `index`'. It specifies the resource (nodes) and the operation (reorder), and distinguishes itself from sibling tools like reparent_nodes (by emphasizing 'within their current parent') and move_nodes (by referencing z-order).
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 description provides clear context for usage: it is for reordering nodes within the same parent, not for changing parents. It also notes that detached nodes are skipped, which is an important exclusion. However, it does not explicitly mention alternative tools or provide a when-not-to-use list, so it stops short of a 5.
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?
The annotation indicates readOnlyHint=false, but the description adds behavioral details: non-resizable nodes are skipped and the return shape is { ok, affected }. This goes beyond the basic safety hints.
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 concise sentences, front-loaded with the action and outcome. No filler.
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 simple resize operation, the description covers the action, edge case (non-resizable skipped), and return value. Annotations provide safety context. Enough for the agent to select and invoke correctly.
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 only 33% (nodeIds has a description). The description reiterates 'width × height (positive)' which duplicates the schema's exclusiveMinimum constraint. It does not explain units, allowed node types, or the meaning of 'affected'. Minimal added value beyond 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 the specific verb 'resize' with a clear resource ('nodes') and specifies the dimensions ('width × height (positive)'). This distinguishes it from siblings like move_nodes or rotate_nodes.
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 description provides clear context: resize nodes with positive dimensions, non-resizable nodes are skipped. It does not explicitly mention when not to use this tool compared to alternatives, but the operation is self-evident.
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?
Beyond readOnlyHint annotation, the description discloses that traversal is by subtree, that it returns per-node text and font attributes, and that the default scope is the current page. This gives the agent useful behavioral expectations without needing to infer from 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?
Two short sentences; first states the core function, second explains scoping. No redundant words or filler.
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 read-only tool with one optional parameter, the description covers what it returns, how to scope, and the default behavior. The absence of an output schema is mitigated by listing the returned fields, making it complete for its simplicity.
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?
The single parameter root is fully described in the schema ('Node id to scope the scan; omit for the current page'), and the tool description repeats this information almost verbatim. No additional semantic meaning is added 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?
Clearly states the tool returns all TEXT nodes within a subtree, with specific properties (characters/fontSize/fontName). This distinguishes it from generic node scanners like scan_nodes_by_types and from get_node, making its purpose unambiguous.
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 description provides clear context: you use this to scan text nodes in a subtree, with root scoping and default to current page. Though it doesn't explicitly name alternative tools, the specialized function makes when-to-use evident. Lacks explicit exclusions, but context is solid.
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 establish that this is a write operation but not destructive. The description adds context that the duration is measured in seconds, must be positive, and that the response is {ok, nodeId}. It doesn't discuss error behavior or side effects, but for a simple setter this is adequate.
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 concise and structured with the primary action first. The second and third sentences respectively give the required prerequisite and return value. No filler or repeated schema text.
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?
Given that the schema and annotations cover the parameter details and safety profile, the description supplies the remaining operational knowledge: how to find timelineId and what response to expect. This is sufficient for an agent to successfully invoke the tool. No output schema exists, but the return format is explicitly stated in the description.
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?
All parameters are fully described in the schema (100% coverage), including units, constraints, and source. The description only restates the duration >0 rule and timelineId provenance, adding little beyond the schema. Thus the baseline of 3 applies.
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 names the target resource ('Figma Motion timeline') and the action ('Set the duration'), with an explicit constraint (must be >0). This directly distinguishes it from other set_* tools that target different properties. It also tells the agent how to obtain the timeline ID, eliminating ambiguity.
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 tells the agent exactly how to get the required timelineId: from get_node_motion via a node's timelines. It also implies the nodeId must reference a node on that timeline. However, it doesn't explicitly state alternatives or scenarios where a different tool would be better, so it's clear but not exhaustive.
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?
The description discloses several behavioral traits beyond the sparse annotations: the operation is atomic and undoable when batched, returns an `appliedStyleId` that can be used to remove exactly that instance later, and is a Figma-Design-only beta feature. No contradiction with `readOnlyHint: false` or `destructiveHint: false`.
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 front-loaded with the core purpose and every sentence earns its place: input source, config tuning, return/removal semantics, batch staggering, and platform limitation. There is no filler or repetition of schema content.
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 tool with nested configuration and no output schema, the description covers input provenance, key config behavior, return shape, removal strategy, and atomic batching. It does not enumerate every config prop, but the schema covers those details, making the description complete enough for practical use.
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 schema already documents all parameters (100% coverage), but the description adds valuable meaning: it tells the caller to obtain `styleId` from `get_motion_styles`, explains `timelineOffset` as the stagger lever with `node index * step`, and summarizes `config` as duration, offset, and preset-specific props.
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'), a specific resource ('a Figma Motion animation-style preset'), and a target ('a node'). It clearly distinguishes this from the sibling `apply_style_to_node` by emphasizing Motion presets and referencing `get_motion_styles` as the source of style IDs.
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 description gives clear guidance on sourcing `styleId` from `get_motion_styles` and explicitly instructs when to use `batch` for staggered entrances by increasing `timelineOffset`. It does not explicitly contrast with `apply_style_to_node` or `apply_manual_keyframe_track`, but the Motion-specific context is sufficient.
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?
Beyond the annotations (readOnly=false, destructive=false), the description adds that missing nodes are skipped and that it returns { ok, affected }. This provides useful behavioral context about partial handling and the return shape.
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 two sentences long, front-loads the core action, and every sentence adds value: the batch action, the input format, the skipping behavior, and the return value. No extraneous 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?
For a simple batch rename tool, the description covers the essential aspects: input format, behavior for missing nodes, and the return value. It doesn't discuss error handling, but given the tool's simplicity and the annotations, this is adequate.
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?
Although schema coverage is 100%, the description reinforces the parameter structure by stating 'from a [{ nodeId, name }] list', which adds clarity about the exact expected array elements beyond the schema's generic 'Per-node rename instructions'.
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 'Rename many nodes at once', specifying the verb and resource, and distinguishes itself from the sibling 'rename_node' by emphasizing the batch aspect. It also describes the input list format and the behavior of skipping missing nodes.
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 description provides clear context for use: 'many nodes at once' signals this is for batch operations. It doesn't explicitly mention alternatives or when not to use it, but the purpose is clear enough to guide selection in most cases.
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 only say readOnlyHint=false and destructiveHint=false, indicating a mutation but not a destructive one. The description adds valuable context: frames can be sized/positioned and appended to a parent (defaulting to current page), and it discloses the return shape. It doesn't mention edge cases like invalid parents or selection changes, but for a create operation this is reasonably transparent.
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 description front-loads the core purpose, adds a key capability (auto-layout host), gives a sibling alternative, and concludes with the return structure. Every clause 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 6 optional params and no output schema, the description covers the essentials: what the tool creates, default behavior, guidance for related tools, and return value. It doesn't explain all edge cases (e.g., invalid parentId, insertion order), but for a create-node tool this is sufficiently complete for an AI agent to understand usage.
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 covers 67% of parameters (x and y lack descriptions). The description compensates by noting that sizing/positioning is optional and that parentId defaults to the current page. This adds meaning beyond the schema and clarifies optionality, though it doesn't explain units or coordinate origin, which are likely obvious to the target user.
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 'Create' with the resource 'frame' and clearly distinguishes it from siblings: it positions the frame as the primary UI container and the only auto-layout host, explicitly contrasting with create_section for canvas-level grouping. This is more than a tautology and fully clarifies what the tool does.
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 description gives clear context: frames are for auto-layout UI, and it points to set_auto_layout for enabling auto-layout after creation. It also names create_section as the alternative for grouping. It doesn't explicitly say when not to use it (e.g., for simple shapes), but the primary use case and alternative are well communicated.
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 only indicate the tool is not read-only and not destructive, which is minimal. The description adds meaningful behavioral context: the grid pattern structure (GRID via sectionSize, ROWS/COLUMNS via count+gutterSize+alignment) and the return shape ({ ok, styleId, name }). It does not disclose edge cases like naming conflicts, but what is provided goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. Front-loaded with purpose, then pattern details, application hint, and return value. Every clause is informative.
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 there is no output schema, the description correctly includes the return shape. It explains the core patterns and application workflow. It doesn't cover every parameter (offset, visible) or error conditions, but the tool is moderately simple and the description is sufficient for a typical use case.
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 only 33% (only 'name' has a description). The description compensates by explaining the semantics of the pattern enum and how sectionSize, count, gutterSize, and alignment relate to each pattern. It does not cover offset, visible, or the top-level description param, but the main grid logic is clarified.
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 creates a reusable local layout-grid style, which is a specific verb+resource. It distinguishes this from siblings like set_layout_grids (which applies grids directly) and apply_style_to_node (which applies a style) by focusing on creation and reuse. The pattern details (GRID, ROWS, COLUMNS) further clarify the scope.
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 description signals when to use this tool: for creating a reusable style, not for one-off grid application. It explicitly points to apply_style_to_node as the follow-up for applying the created style. It does not explicitly mention alternatives like set_layout_grids for non-reusable cases, but the 'reusable' qualifier implies the distinction.
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 establish that this is a mutating (readOnlyHint: false) and non-destructive action. The description adds valuable behavioral details: the two acceptable source identifiers, optional position/name/parent parameters, and the return shape { ok, nodeId, name, type }. It does not disclose error behavior when both or neither identifier is provided, but overall complements the annotations 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?
Four tight sentences deliver all key information without redundancy. Every sentence earns its place: purpose, source identifiers, optional parameters, and return value.
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?
The description covers the main usage modes, optional placement, and the return contract, which is adequate for a tool with no output schema. However, it omits behavior when both or neither componentId/componentKey are supplied, leaving a potential ambiguity given no required parameters. Overall, it is nearly complete for typical usage.
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 descriptions cover componentId, componentKey, name, and parentId, while x and y have no schema descriptions. The description adds meaning by referring to 'name / position / parent', implicitly explaining x/y as position and reinforcing the semantics of the other parameters. This compensates for the 67% schema coverage, though x/y could have been more explicit.
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 'Instantiate' with the resource 'component', and clearly distinguishes between local and published component sources via componentId and componentKey. This sets it apart from sibling tools like create_component or swap_component, making the purpose unambiguous.
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 description clearly indicates when to use this tool (to create an instance from a local or published component) and provides context for optional placement. However, it does not explicitly state when not to use it or name alternative tools, so it stops short of full usage guidance.
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 readOnlyHint=false and destructiveHint=false, which are consistent with a mutation that is not destructive. The description goes beyond annotations by disclosing the 'local' scope (not in a library), the naming convention with slashes for folder grouping, and the return value shape '{ ok, styleId, name }'. This adds useful behavioral context not present in annotations or 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?
The description is concise and efficiently structured. It packs essential information into two sentences: the core creation capability, the input shape hint, naming convention, related workflows, and return value. Every sentence contributes value with no superfluous content.
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 tool with three parameters, no output schema, and moderate complexity, the description is fairly complete. It covers purpose, input specifics, workflow, and return value. It does not discuss potential failure cases like duplicate style names or permission requirements, but these are not critical for a create-style tool with non-destructive annotations. The availability of related sibling tools (apply_style_to_node, update_paint_style) further rounds out the 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?
The schema has 100% description coverage, though some descriptions are minimal (e.g., 'Paints'). The description adds meaning by referencing 'same shape as set_fills' for the paints parameter, which is valuable for agents familiar with that sibling tool, and by explaining the name parameter's folder grouping convention via slashes. This exceeds the baseline for schema-covered parameters.
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's function: 'Create a reusable local paint (color) style from SOLID or gradient paints'. It identifies the specific resource (paint style), the action (create), and the input types. It also distinguishes itself from sibling tools like create_text_style and update_paint_style by naming the exact workflows for applying and editing the style.
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 description provides clear usage context by explaining the lifecycle: 'Apply it to nodes with apply_style_to_node, or edit it later with update_paint_style.' It does not explicitly list when not to use the tool, but referring to alternative sibling tools for application and editing gives good contextual guidance. The distinction from other create_*_style tools is implied by the tool name and the paint-specific focus.
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 write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds valuable behavioral context: the default font is loaded automatically, the node is appended to a parent (defaulting to current page), and the return value includes { ok, nodeId, name, type }. This exceeds the structured annotations 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?
The description is two sentences: the first front-loads the core action and key options, the second gives targeted alternatives and return value. Every sentence earns its place, and there is no 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 tool's simplicity, the description covers the essential aspects: creation, optional placement, parent default, and return metadata. Since there is no output schema, the explicit mention of the return value is especially useful. It does not cover error conditions or permissions, but for a create operation with good annotations and schema, this is sufficient.
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 description coverage is 100%, so the baseline is 3. The description reinforces that parentId is optional and defaults to the current page, and that characters are required, but does not add new semantic meaning beyond what the schema already provides for x, y, fontSize, or characters. It does not significantly enhance parameter understanding.
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 ('Create a new TEXT node') with a clear resource and details about optional sizing, positioning, and parent assignment. It also distinguishes itself from sibling tools like set_text and set_text_properties, making its purpose unambiguous.
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?
The description explicitly provides when-to-use guidance by naming alternatives: 'To change the text of an existing node use set_text; for font, size, or color use set_text_properties.' It also clarifies the default parent behavior, giving clear context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite readOnlyHint: true, the description adds substantial behavioral context: it is a heavy render that should be called alone, failure modes are clearly described (path:null with a reason, and Figma's own error when reason is 'failed'), and prerequisites are stated. These details go beyond what annotations alone provide.
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 dense but every sentence serves a purpose: purpose, node selection, prerequisites/failure modes, concurrency warning, and return shape. It is slightly wordy in the middle section listing failure cases, but generally well-structured and front-loaded with the primary action.
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?
The description covers all critical operational aspects: input requirements, output formats, failure conditions, performance constraints, and the returned object shape. With no output schema, it fully communicates what the agent can expect, making it complete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% parameter coverage with detailed descriptions for all 7 parameters. The tool description reinforces the nodeId semantics ('Pass any node in the frame or the frame itself') but does not add additional meaning beyond the schema. Baseline of 3 is 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?
The description clearly states the verb 'Export' and the specific resource: 'an animated Figma top-level frame' to targeted output formats ('MP4 / WebM / GIF file on disk'). It also details the node-acceptance nuance (any node in the frame or the frame itself), which differentiates it from sibling export tools like export_pdf.
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 description provides explicit context on when to use the tool (requires Figma Design editor and animated content) and when not to use it (static frame, nested frame, FigJam, Dev Mode all yield path:null). It also warns against concurrent calls. However, it does not explicitly name alternative sibling tools like export_pdf for static exports, so it falls short of a 5.
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 only flag readOnlyHint=false and destructiveHint=false, so the description adds valuable behavioral context by disclosing that fonts are loaded before each edit and that the operation affects text nodes. It also explains the scope default and case sensitivity, which are beyond the structured fields. It does not contradict 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 concise and front-loaded, with the first sentence stating the core purpose. Each subsequent sentence adds a distinct piece of useful information (scope, case sensitivity, font loading, return value) with no redundancy or fluff.
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 tool with no output schema and four parameters, the description covers the essential usage semantics, return value, and a side effect (font loading). It could mention potential error conditions or confirm the batch nature, but it is largely complete for selecting and invoking the 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?
With 100% schema coverage, the description adds helpful context to parameters: it clarifies that 'root' defines the scope (defaulting to page), that 'caseSensitive' overrides the default case-insensitive matching, and that 'find'/'replace' are substring-based. This enrichment goes beyond the bare schema descriptions, meriting a 4 rather than baseline 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 verb ('replace'), resource ('substring across all TEXT nodes under a scope'), and distinguishes it from sibling text-editing tools by emphasizing the bulk scope operation. The alternative of searching the whole page when no root is given further clarifies its purpose.
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 description provides clear usage context, including the default scope (whole page) and case-sensitivity behavior, which implies when to use this tool. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of a 5.
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?
The description adds context beyond the readOnlyHint annotation by scoping to the active Figma file and specifying the return fields (id and name). It doesn't mention handling of empty files or edge cases, but the read-only nature is already 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, direct sentence that front-loads the verb and resource, with no filler. It is optimally concise and well-structured.
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 zero-parameter read-only listing tool, the description is nearly complete: it specifies the exact output fields (id and name). It lacks an explicit return format (e.g., array structure), but given the simplicity and annotation support, this is a minor gap.
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, so the input schema fully covers all inputs. The description reinforces that no arguments are needed, which is consistent with the empty 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 clearly states the action (Return), the resource (every page in the active Figma file), and the exact data shape (id+name). This distinguishes it from sibling page tools like add_page, delete_page, or rename_page.
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 description provides clear context: it returns all pages, so the use case is obvious. It does not explicitly name alternatives or exclusions, but the simplicity of the tool makes usage evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses extensive behavioral details beyond the readOnlyHint annotation: gitignore-aware scanning, name-based and near-exact matching, fallthrough on uncertainty, color contract extraction (currentColor/fixed/multi-color), recolor guidance, importHint variants, and the fact that it does not fabricate import lines. This far exceeds the annotation's minimal 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 concise relative to the tool's complexity, with every sentence adding value (matching behavior, import hints, return shape). It is front-loaded with the core purpose. However, a long single paragraph is slightly dense; bullet points could improve scannability, but it is still well within acceptable length.
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?
Despite no output schema, the description clearly states the return shape: 'Returns { mappings, unmapped, iconLibraries, profile }' and explains what each part contains (file path, color contract, recolor info, importHint forms). It also covers failure handling, defaults, and integration with project imports. This is a complete, self-contained description for a complex tool.
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 description coverage is 100% for all three parameters, so the schema already documents their meanings and defaults (e.g., rootDir defaults to cwd, threshold default 0.7). The description adds context about matching thresholds indirectly but does not provide additional parameter-specific syntax or edge-case details beyond the schema. Baseline 3 is 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?
The description clearly specifies the tool's function: 'Map the Figma icon nodes in a selection/subtree to the project's existing `.svg` files'. It also explains the goal 'so codegen reuses the designer-curated asset instead of re-exporting a duplicate', which distinguishes it from sibling mapping tools like token_map and component_map.
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 description gives clear context for when to use the tool (during codegen to reuse existing SVG assets) and describes fallback behavior ('unsure matches fall through to a fresh export'). It does not explicitly state when not to use it or name alternative tools, but the 'iconLibraries' mention and distinct purpose imply alternatives. The lack of explicit exclusions prevents a 5.
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 declare destructiveHint=true and readOnlyHint=false, so the description doesn't need to restate destructive behavior. It adds value by disclosing the return shape ({ ok, nodeId }) and clarifying that field targets the same field as apply_manual_keyframe_track, which helps the agent understand the effect.
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 two sentences, front-loaded with the main action, and every sentence conveys necessary information without redundancy. It's a model of conciseness.
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 mutation tool with no output schema, the description adequately covers what is removed, how the field selector works, and the return value. It doesn't detail error cases or idempotency, but combined with the annotations and schema it's sufficiently complete for straightforward 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?
Schema coverage is 100% with descriptions for both nodeId and field. The description adds a cross-reference to apply_manual_keyframe_track, reinforcing that the field parameter matches its sibling's semantics, which is useful 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?
The description uses the specific verb 'Remove' with a clear resource: 'manual Figma Motion keyframe track for a given field on a node.' It also distinguishes this from siblings like remove_animation_style by explicitly naming the target and cross-referencing apply_manual_keyframe_track.
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 description implies when to use this tool (removing a manual keyframe track) and clarifies that the field parameter uses the same target semantics as apply_manual_keyframe_track, guiding coordination. It doesn't explicitly exclude alternatives, but the context is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds substantial behavioral detail beyond that: AST-based identification (exported, PascalCase, function-ish), independence from folder layout, framework-specific parsing for React/Vue/Svelte, default behaviors for extensions and rootDir, and the exact return shape. This transparently sets expectations for the operation.
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 compact but information-dense, leading with the core purpose before explaining detection logic, framework handling, and defaults. Each sentence contributes novel information, though the framework-specific parsing details (React vs Vue/Svelte) make it slightly longer than necessary for a quick scan. Still, it is well-structured and free of filler.
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?
With no output schema, the description compensates by explicitly stating the return value ('Returns { components, profile }'). It covers the operation's location, detection method, framework support, parameter defaults, and return shape. Given the tool's moderate complexity and the absence of an output schema, the description is fully complete for an agent to select and invoke it correctly.
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 description coverage is 100% for both parameters, so the baseline is 3. The description adds minimal new semantic value; it only repeats the default behavior for 'extensions' and 'rootDir' that the schema already documents. It does not explain parameter syntax or edge cases beyond what the schema provides, so no score above baseline is warranted.
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 specific verb 'scan' and a clear resource ('local project for existing UI components') with an explicit purpose ('so they can be reused instead of regenerated'). It also distinguishes itself from Figma-based siblings by stating 'Runs on the server filesystem, not in Figma', making it clear this is a local filesystem operation rather than a Figma document scan.
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 description conveys when to use the tool: when you need to discover existing local UI components for reuse. It also clarifies the scope ('Runs on the server filesystem, not in Figma'), which helps an agent choose this over Figma scanning tools. However, it does not explicitly name alternatives or provide 'when not to use' guidance, so it falls short of a 5.
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?
The description discloses key behavioral details beyond the minimal annotations: per-corner values override the uniform radius for that corner, at least one radius is required, and the tool returns { ok, nodeId }. It also notes that individual corners are supported only on certain nodes, which sets expectations. 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 three sentences long and front-loaded with the primary action. Each sentence earns its place: the first states the purpose, the second explains the parameters and their context, and the third covers the override and requirement. There is no filler, repetition, or extraneous detail.
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 six parameters, minimal annotations, and no output schema, the description covers the essential context: parameter relationships, required input, and return value. It could optionally mention behavior on unsupported nodes (e.g., whether it ignores corner values or throws), but the overall picture is complete enough for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema already documents each parameter (100% coverage), the description adds crucial relational semantics: per-corner values override the uniform radius, and the requirement that at least one radius be provided. This explains how parameters interact, which the JSON schema alone cannot convey. The description elevates the parameter understanding beyond simple field descriptions.
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 'Set a node's corner radius' – a specific verb and resource that immediately clarifies the tool's core function. It distinguishes itself from sibling tools like set_arc or set_fills by focusing solely on corner radius, and further details uniform vs per-corner options. This leaves no ambiguity about what the tool does.
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 description provides clear context on when to use per-corner values versus a uniform radius, with examples like 'a card rounded only on top, a tab or a chat bubble'. It also states the requirement that at least one radius parameter must be supplied. While it doesn't explicitly name alternative tools, no sibling tool serves the same purpose, so the guidance is sufficient.
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 a mutating operation (readOnlyHint=false, destructiveHint=false). The description adds value by disclosing the return format ({ ok, nodeId }) and the expected input structures, including the note about compatibility with get_node output. 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 compact—three sentences that front-load the purpose, then provide examples and return info without unnecessary words. Each sentence adds meaningful detail and the structure is easy to scan.
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 setter tool with rich schema and annotations, the description covers the main purpose, input formats, and return value. It does not discuss error cases or side effects, but given the simplicity of the operation, this is acceptable and leaves the agent sufficient context to invoke 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?
Schema coverage is 100%, so the schema already documents both parameters and their types. The description enriches this by providing concrete syntax examples, clarifying color value ranges (0–1), and explaining the gradientTransform shape, which goes beyond the schema's descriptions.
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 'Set a node's fills', a specific verb+resource that clearly identifies the tool's function. It further distinguishes itself from sibling tools (e.g., set_strokes, set_effects) by explicitly describing SOLID and gradient paint structures, making the purpose unambiguous.
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 description clearly implies when to use this tool (to set fills on a node) and provides format details. It does not explicitly name alternatives or exclusions, but the 'round-trips get_node output' phrase suggests a typical edit workflow, offering contextual guidance without being exhaustive.
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?
The description adds meaningful behavioral detail beyond the annotations: it explains the masking behavior, notes that maskType is only applied when enabling, and states the return shape ({ ok, nodeId }). This goes beyond the minimal readOnlyHint/destructiveHint annotations 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?
The description is two concise sentences, front-loaded with the core purpose and followed by parameter usage and return information. Every clause earns its place, with no fluff or 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?
For a simple mutation tool with no output schema, the description adequately covers what the tool does, how to use it, and what it returns. It lacks details about potential errors or prerequisites, but these are not critical for a well-scoped setter operation. Sibling context does not demand more.
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%, so the parameters are already documented structurally. The description adds semantic value by explaining that maskType applies only when enabling, and by enumerating the enum values inline, reinforcing the schema's meaning.
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 ('Set whether a node is a mask') and clearly defines the resource and behavior ('a mask clips its later siblings to its own shape'). It also distinguishes the tool from the many sibling set_* tools by explaining the unique mask semantics.
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 description provides clear context for when to use this tool: when you need a node to act as a mask by clipping later siblings. It does not explicitly mention when not to use it or name alternative tools, but the usage scenario is evident and no direct alternative exists among siblings.
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?
Beyond the minimal annotations (readOnlyHint=false, destructiveHint=false), the description discloses that omitted fields are left unchanged, per-side weights override strokeWeight, and the return shape is { ok, nodeId }. It also hints at node-specific support for per-side weights. This provides meaningful behavioral context without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but efficient, with each sentence contributing essential information. It front-loads the main action, then lists optional parameters, gives an override rule, states omission semantics, and ends with the return value. The reference to set_fills avoids repeating paint structure details, keeping it concise.
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?
With 9 parameters, no output schema, and minimal annotations, the description covers the key aspects: available parameters, override behavior, omission semantics, and return value. It does not mention failure cases (e.g., node not supporting strokes) or how to specify gradients beyond referencing set_fills, but it is sufficiently complete for a complex 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?
The schema already covers all 9 parameters with descriptions, giving a baseline of 3. The description adds value by explaining relationships: per-side weight overrides strokeWeight, dashPattern is dashes, and the strokes array has the 'same shape as set_fills'. This goes beyond what the schema states, clarifying how parameters interact.
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 sets a node's strokes (SOLID or gradient paints) plus optional stroke properties, which is a specific verb+resource. It explicitly references set_fills as a sibling to distinguish strokes from fills, and lists the exact optional properties (strokeWeight, strokeAlign, dashPattern, per-side weights). This fully differentiates it from sibling tools like set_fills or set_effects.
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 description implies when to use this tool by referencing set_fills (use set_fills for fills, set_strokes for strokes) and provides clear context for optional parameters. It notes per-side weights are 'for nodes that support individual stroke weights' and gives an example (border-bottom-only divider), which is useful guidance. However, it does not explicitly state when not to use it or compare to other stroke-related tools beyond set_fills.
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 only indicate readOnlyHint=false and destructiveHint=false. The description adds valuable behavioral details: font loading side effect, partial update behavior (any field omitted leaves unchanged), dependency of maxLines on textTruncation, and a return value ('Returns { ok, nodeId }'). This goes well beyond the annotations, though it does not discuss error cases or permissions.
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 compact and well-organized. It uses a colon to separate the main verb from property categories, lists all fields in a readable flow, and includes only necessary caveats. Every sentence adds value (font loading, omit behavior, maxLines dependency, return format), with no redundant or filler content.
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 tool's complexity (12 params, nested objects, no output schema), the description covers a lot: it defines the target node type, groups all parameters, explains return format, and notes the dependency between maxLines and textTruncation. It lacks detail on error handling or invalid input behavior, but for a mutation tool with comprehensive schema annotations, the description is sufficiently complete.
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 description coverage is 83%, giving a baseline of 3. The description adds meaning beyond the schema by grouping parameters into categories, explaining paragraphSpacing/paragraphIndent semantics (paragraphs split at '\n'), clarifying textTruncation (ellipsis) and maxLines line clamp, and stating that all typography fields trigger font loading. It also explicitly states the omit-to-leave-unchanged behavior, which is not in 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 opens with a specific verb and resource: 'Set a TEXT node's typography and layout/overflow properties.' It clearly enumerates the categories (typography, layout/overflow) and lists fields, distinguishing it from siblings like set_text (content) or set_fills (fills). It explicitly states the target node type (TEXT), making the tool's scope unambiguous.
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 description provides clear usage context: it groups properties into typography and layout, notes that omitted fields leave values unchanged, and gives a conditional rule ('maxLines applies when textTruncation is ENDING'). It also mentions prerequisite behavior ('these load the required fonts first'). However, it does not explicitly name alternatives or state when not to use this tool, so it stops short of a 5.
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 mutation (readOnlyHint=false). The description adds the return shape { ok, nodeId } and clarifies the component source types, but does not discuss side effects, reversibility, or prerequisites like existing instance status. This is reasonable given annotation coverage.
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 concise sentences: the first states the core function, the second details parameter choice and return value. No filler or 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?
The description covers the essential operation, parameter semantics, and return format. It doesn't address whether both componentKey and componentId can be provided or error handling, but given the schema and annotations, it is sufficiently complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all parameters, and the description goes further by explaining that componentKey is a 'published component, imported via the API' and componentId is a 'local COMPONENT node,' adding semantic meaning beyond the schema descriptions.
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 operation: 'Swap an instance's main component.' It also specifies the two input modes (componentKey and componentId), making the tool's scope distinct from siblings like set_instance_properties or detach_instance.
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 on how to use the tool by explaining the two component specification methods (published key vs local node). However, it does not explicitly state when to prefer this tool over alternatives or list exclusion criteria.
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 readOnlyHint=true, and the description adds substantial context beyond that: it runs on the server filesystem, rootDir defaults to server cwd, detects Tailwind v3/v4, and reports svg loader mode. This gives the agent a clear behavioral picture of a safe, local read-only probe. It doesn't exhaustively list every behavior, but it's well above baseline for an annotated read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but not bloated. It front-loads purpose, then usage guidance, then specific detection details. Each sentence adds distinct value (purpose, relationship to siblings, server-side execution, default, detection specifics). It could be tightened slightly, but overall it is well-structured and economical.
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?
The tool has no output schema, but the description compensates by listing what is detected (framework, language, styling system, component file extensions, svg handling, tailwindVersion, svg.mode). It also clarifies the operational context (server filesystem, no Figma, no file scan). For a simple probe with one optional parameter, this is sufficiently complete.
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% (one parameter, rootDir, fully described). The description adds meaningful extra semantics: 'rootDir defaults to the server cwd' and notes it is an optional override. This goes beyond the schema by clarifying the default and the scope of the parameter.
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 specific action and object: 'Detect the local project profile (framework, language, styling system, component file extensions, svg handling) by reading manifests and config'. It clearly distinguishes itself from siblings scan_components / component_map by positioning itself as the foundation and noting it is for 'inspection in isolation (no Figma, no file scan)'.
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?
Explicit usage guidance is provided: 'those tools run detection internally and return the same profile, so call this only to inspect detection in isolation'. It names the alternatives (scan_components / component_map) and states when not to use this tool, which fully addresses the when-to-use vs alternatives requirement.
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?
Beyond the annotations (readOnlyHint: false, destructiveHint: false), the description reveals key behaviors: the null-to-unbind mechanism, the requirement for the property type to match the field, and the need for the property to exist on the containing component. It also discloses the return shape. This adds meaningful context beyond the annotations, though it could mention whether existing bindings are overwritten.
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 dense paragraph with no filler. It front-loads the core action ('Attach'), then systematically explains type mappings, repeatability, unbinding, constraints, and return value. Every sentence earns its place, making it efficient and well-structured.
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 tool with 3 parameters, no output schema, and no nested objects, this description is complete. It covers preconditions, field/type mappings, how to unbind, and return value. It also situates itself within the component-property workflow by referencing add_component_property. There are no significant gaps.
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 already covers all three parameters with 100% coverage, so the baseline is 3. The description enhances this by mapping each field enum value to specific property types and node types (e.g., 'characters' requires a TEXT node), which is not in the schema. This adds real semantic value, earning a 4.
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's function: attaching a declared component property to a sublayer field so it drives that layer. It specifies exactly which field maps to which property type (visible for BOOLEAN, characters for TEXT, mainComponent for INSTANCE_SWAP) and distinguishes itself from sibling tools like add_component_property and edit_component_property by focusing on the binding action.
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 description provides explicit usage context: it references add_component_property as the prerequisite, explains valid field/type combinations, notes that the same property can be bound to multiple layers, and gives special handling for null to remove bindings. It does not explicitly name alternative tools or state when not to use it, but the guidance is clear enough for an agent to select the correct tool.
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 a mutating (readOnlyHint=false) and non-destructive (destructiveHint=false) operation. The description adds valuable behavioral details: copy placement ('sibling right after the original'), deep copy ('full subtree'), instance preservation, and the return payload. This goes beyond the annotations 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 well-structured sentences: the first states the core action and placement, the second covers the instance nuance and alternative, and the third (short) gives the return shape. Every clause adds value, with zero redundancy.
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?
Despite having no output schema, the description fully discloses the return format. It explains the scope (subtree), placement, behavior for component instances, and the alternative tool. For a single-parameter mutation tool, this is complete and self-sufficient.
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?
The input schema already provides 100% coverage for the sole parameter with 'Node id to clone'. The description adds no extra parameter-specific meaning beyond what the schema states, so it meets the baseline for high schema coverage. The behavioral context (placement and subtree) indirectly clarifies the parameter's effect but doesn't add new syntax or format 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 uses a specific verb 'Duplicate' and identifies the resource ('a node') with the explicit scope of 'including its full subtree'. It clearly differentiates from sibling tool create_instance by noting that cloning a component instance keeps it an instance, making the purpose unmistakable.
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?
The description explicitly contrasts with create_instance: 'to make a fresh instance of a component use create_instance instead'. It also clarifies when to use this tool (when duplicating a node with its subtree) and the behavior for component instances, providing clear selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations being present (readOnlyHint: false, destructiveHint: false), the description adds valuable behavioral context far beyond that: it explains that converting preserves the node's position and parent unless overridden, defaults to the current page, and discloses the exact return shape. This tells the agent what side effects to expect and how results are returned, exceeding the baseline.
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 front-loaded with the core action and structured logically: purpose, two modes with an example, follow-up, options, and return. It is slightly longer than minimal (5 sentences) but each sentence contributes, and the em-dash aside is a natural clarification. It is not wasteful but could be tightened slightly.
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 tool with 7 optional parameters and no output schema, the description covers the main decision points, defaults, and return shape. It addresses both creation modes and implies the use case for importing SVG frames. It does not discuss edge cases like invalid node types or what happens to children, but for routine use it is sufficiently complete.
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 schema description coverage at only 29%, the description compensates well. It explains the crucial fromNodeId at length (what it does, with an example, and the preservation behavior) and notes parentId's default. It also groups the remaining numeric/name parameters as 'sized / named / positioned,' giving them meaning without enumerating. This is a strong compensation, though it could still clarify specific units or coordinate origins.
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 'Create a reusable main component,' a specific verb+resource statement, and immediately clarifies the two operational modes (fromNodeId vs. empty). It distinguishes itself from the sibling create_instance by explicitly stating the follow-up step, so the purpose is unambiguous and differentiated.
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 description provides clear when-to-use guidance: 'Pass fromNodeId to convert an existing node' and 'omit fromNodeId to create an empty component.' It also points to create_instance as the next step, offering alternative sequencing. However, it does not explicitly cover exclusions (e.g., unsupported node types) or compare against other sibling tools, leaving a small gap in full guidance.
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?
With annotations already indicating readOnlyHint=false and destructiveHint=false, the description adds the return shape ({ ok, nodeId, name, type }) and the default parent behavior (current page). This goes beyond the annotations and clarifies the mutation effect without contradiction.
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 the key information front-loaded: action, options, use cases, alternatives, and return value. No redundant or filler text; every sentence 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 simple creation tool with no output schema, the description adequately covers the return value, default behavior, and sibling alternatives. It is complete enough for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all 6 parameters with descriptions (100% coverage), so the baseline is 3. The description adds light context about 'optionally sized/positioned' and 'default: current page' but does not add deeper syntax or format details 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 clearly states 'Create a rectangle' with optional sizing/positioning and append behavior, and distinguishes it from sibling tools like create_frame and import_image by specifying use cases. This is a specific verb+resource+scope definition.
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 names alternatives: 'for a container that holds other layers use create_frame, and for placed bitmaps use import_image.' Also provides use cases (solid shapes, dividers, color blocks), giving clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the return shape ('Returns { ok, nodeId, name, type }') and placement constraints ('Sections sit on a page or nest inside another section, but not inside a frame'), adding value beyond the basic readOnly/destructive flags. It doesn't mention error conditions, but for a create operation this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, starting with the action and resource, then adding placement rules and return value. There is no redundancy or filler; every sentence 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 simple create tool, the description covers purpose, placement constraints, alternative tool, and return shape. Combined with full schema coverage and consistent annotations, the agent has enough information to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 6 parameters are already described in the schema with clear semantics (e.g., 'Parent page or section id (default: current page)'), so the description doesn't need to restate them. It doesn't add extra parameter detail, but the schema fully covers it, so baseline 3 applies.
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 begins with 'Create a section' and defines it as 'a canvas-level container for grouping and labelling regions of a page', clearly stating what the tool does. It distinguishes from create_frame by explicitly saying 'for a UI container or auto-layout use create_frame instead', making the purpose unambiguous.
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?
It explicitly states the use case ('grouping and labelling regions of a page') and the exclusion ('not inside a frame'), and points to an alternative tool ('use create_frame instead'). This gives clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive behavior, but the description adds valuable context: deletion is blocked for the current page and the last remaining page, and the return value is { ok, nodeId }. This goes beyond the annotations and helps the agent anticipate edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: the first states the primary action, the second notes constraints and return value. Every word earns its place; no redundancy.
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 simple tool with one parameter and no output schema, the description fully covers the action, constraints, and return shape. The schema handles the parameter definition, and the description provides all necessary behavioral context.
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% for the single parameter (pageId) with a clear description. The tool description does not add additional parameter semantics, but the schema already fully documents the parameter, so baseline 3 is 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?
The description uses a specific verb ('Delete'), a clear resource ('a page'), and the method ('by id'). It distinguishes from sibling tools like delete_nodes by focusing specifically on pages, and adds constraints that clarify scope.
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 description states explicit conditions for use: the current page and the last remaining page cannot be deleted. However, it does not explicitly mention alternatives (e.g., delete_nodes for non-page nodes), though the tool's name and scope make this reasonably clear.
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 flag destructiveHint=true, so the description adds value by detailing the side effect: 'any node or paint bound to it reverts to its raw value.' It also discloses the return shape, which is useful since no output schema exists.
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 short sentences, no filler, front-loaded with the core action and side effect. Every sentence serves a purpose.
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 single-parameter destructive tool with no output schema, the description covers purpose, side effect, alternative, and return value. It is complete for the tool's complexity.
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 already covers the only parameter (variableId) with a clear description, so the description adds little beyond 'by id'. Baseline 3 is appropriate given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Uses specific verb 'Delete' with resource 'variable' and clarifies it's a single variable. Explicitly contrasts with delete_variable_collection for whole collections, distinguishing it from siblings.
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 instructs when to use delete_variable_collection instead: 'To delete an entire collection and all its variables use delete_variable_collection.' This provides a clear alternative and when-not condition.
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?
The annotation readOnlyHint=true already indicates a safe read operation. The description adds meaningful behavioral details: sorting by frequency descending, the exact output shape, and how mixed-font text is counted (one count per styled segment). This goes beyond the minimal safety info and enriches the agent's understanding of the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the primary purpose, then provides essential output details and edge-case behavior. Every word earns its place: no filler, no repetition, and the structure is optimal for quick parsing by an agent.
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?
The tool is simple with no parameters and no output schema, but the description fully specifies the return shape, sorting order, and counting rule for mixed fonts. This covers all necessary contextual information for an agent to select and invoke the tool without ambiguity. The description is complete for the tool's complexity level.
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 zero parameters and 100% schema coverage (vacuously), the description carries no parameter burden. The baseline for no parameters is 4, and the description appropriately focuses on output semantics rather than parameter documentation. It fully satisfies the need for parameter clarity given there are none.
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's function: return every font on the current page with counts, sorted by frequency. It uses a specific verb ('Return') and resource ('every font used on the current page'), and the output format is explicitly defined. This distinguishes it from sibling tools like get_styles and get_variable_defs, which serve different resources.
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 description implies when to use it: when you need a list of fonts with usage counts on the current page. It provides clear context but does not explicitly mention alternatives or when not to use it. Since the purpose is self-evident and distinct from siblings, this is clear context without exclusions, matching a score of 4.
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?
The readOnlyHint annotation covers safety, but the description adds meaningful context: the return structure, the significance of styleId, and the beta/editor limitation. This goes beyond the annotation and helps the agent understand the tool's behavior and constraints.
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 focused sentences: the first defines the tool's purpose, the second covers return format and caveats. Every word earns its place; no fluff or repetition.
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?
No output schema exists, so the description fully compensates by describing the return object (styles array with styleId, name, description?, props?) and connects it to apply_animation_style. It also notes beta status and editor availability. For a simple no-parameter read-only tool, this is complete.
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 zero parameters, the schema provides full coverage. Per the rubric, baseline is 4 for 0 params. The description adds value by explaining the output structure, although parameter guidance is unnecessary here.
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 verb 'List' and the resource 'Figma Motion animation-style presets', and differentiates from sibling tools like apply_animation_style by noting it returns the styleId used by that tool. This is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies a clear workflow by stating these are 'the templates you apply with apply_animation_style' and adds a constraint ('only available in the Figma Design editor'). However, it does not explicitly list exclusions or alternative tools, so it's one step below fully explicit.
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?
The readOnlyHint annotation already declares this as safe, and the description adds meaningful behavioral detail by specifying the structure of the returned data (grouping and per-style properties). It covers the primary behavior without contradicting the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and includes just enough detail to be useful. Every clause adds value without repetition or filler.
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?
The tool is simple (no params, no output schema), and the description fully explains what is returned and how it is structured. There are no obvious gaps; the details provided are sufficient for an agent to understand the tool's output.
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?
This tool has zero parameters, so there is nothing to explain. The baseline for 0-parameter tools is 4, and the description appropriately focuses on the return structure rather than parameter usage.
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 ('Return') and a specific resource ('the document's local styles'), then enumerates the exact grouping ('paints, texts, effects, grids') and what each group carries. This clearly distinguishes it from sibling tools like get_motion_styles or style-mutation tools.
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 description makes the context clear: if you need the document's local styles, this is the tool. It doesn't explicitly name alternatives or exclusions, but the scope is so specific that a user wouldn't confuse it with other style-related tools. No when-not guidance is given.
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?
The readOnlyHint annotation covers safety; the description adds return format and the single-element behavior, plus the scope limitation to the host document. This provides useful behavioral context beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the operation and output type. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool, the description fully explains what it returns and its scope. The output shape is included even without an output schema, making the tool self-contained.
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 zero parameters, the schema fully describes the input. The description doesn't need to explain parameters; it instead clarifies the return shape, which is appropriate for a parameterless tool.
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 returns the files reachable from the plugin, with a specific response shape. It also distinguishes from siblings by noting it's a single-element list for the current file, making its purpose unambiguous.
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 context that a plugin only sees its host document, implying when to use this tool: to get current file information. However, it does not explicitly name alternatives or exclusions, so it falls short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond annotations: locking a parent locks descendants, locked nodes still render/export, and the operation is reversible. It also discloses the return value. This is especially valuable given readOnlyHint=false and destructiveHint=false, which confirm the description's claims.
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 two sentences, front-loaded with purpose, then key behaviors, then return value. Every sentence earns its place, with exact phrasing and no redundancy.
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 single-parameter tool without an output schema, the description covers purpose, side effects, reversibility, and return format. The annotations complement the safety profile, making this fully self-contained for an agent to decide and invoke.
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?
The schema already covers the only parameter (nodeIds) with a clear description. The tool description does not add new parameter-level semantics, though it does explain that providing a parent id will affect descendants, which is a behavioral consequence rather than parameter formatting.
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's function: locking nodes prevents selection and editing on the canvas. It differentiates from siblings by specifying scope (canvas interaction only), noting that locks are reversed by unlock_nodes, and explaining the parent-child descendant behavior.
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 description implies when to use the tool (e.g., for backgrounds) and clarifies that it only affects canvas interaction, so users can infer it is not for hiding or exporting. It references the companion unlock_nodes, providing a clear contrast, but does not explicitly state 'use this when/not when' conditions.
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 only declare readOnlyHint=true. The description adds meaningful behavioral detail: it reports server info, end-to-end sandbox info when a plugin is connected, and follower/leader version info with skew warnings. This goes well beyond the annotation and provides useful context about edge-case 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?
The description is two sentences, front-loaded with 'Health check', and every clause adds specific meaning without redundancy. It is concise and well-structured.
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 low-complexity, zero-parameter tool with no output schema, the description covers return behavior thoroughly, including plugin-connected, follower, and stale-server scenarios. It provides sufficient context for the agent to understand what the tool does and what to expect.
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 no parameters, so there are no parameter semantics to clarify. Schema coverage is 100% (empty schema), and the baseline for zero-parameter tools is 4, which applies here.
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 identifies the tool as a health check and specifies what it returns, distinguishing it from the sibling tools which are all mutations or other queries. The verb 'Health check' is specific and sets clear expectations.
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 context is clear (use when you need a health check), and there are no exclusions needed since no sibling tool provides similar functionality. It doesn't explicitly say 'use this when', but the purpose is self-evident enough to be considered 'clear context, no exclusions'.
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?
The annotation already marks destructiveHint=true, and the description adds the conditional behavior of removing one vs all, plus the return shape { ok, nodeId }. The description aligns with annotations and adds practical context about the id source.
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 three sentences: purpose, usage variation, return value. No filler, information is front-loaded.
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 two-parameter mutation tool with one optional parameter, the description covers the operation, the conditional behavior, and the return value. No output schema exists, but the description compensates by stating the return format. It also references related tools for obtaining the id.
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%, so baseline is 3, but the description enriches the meaning by specifying that animationStyleId is the appliedStyleId from apply_animation_style or get_node_motion, and clarifies that omitting it removes all. This adds meaningful context beyond the schema's one-line descriptions.
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 verb and resource: 'Remove an applied Figma Motion animation style from a node.' It distinguishes this from siblings like apply_animation_style and get_node_motion by naming the specific action and scope.
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 description explains when to pass animationStyleId (to remove a specific one) and when to omit (to remove all), and directs users to get the id from apply_animation_style or get_node_motion. It clearly frames the usage context, though it does not explicitly mention alternative tools for deleting style definitions.
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 declare readOnlyHint=false and destructiveHint=true, so the description adds value by specifying that it clears 'every' reaction and returns { ok, nodeId }. The equivalence to set_reactions with an empty array is a useful behavioral detail. However, it doesn't address reversibility or permission requirements, though the destructive annotation mitigates that gap.
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, front-loaded with the core action and alternative. No wasted words; every sentence contributes purpose, use case, or return value.
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 single-parameter tool with no output schema, the description provides the essential context: action, effect, alternative, and return shape. The annotations cover destructive safety. No gaps that would prevent correct invocation.
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 description coverage is 100% (nodeId is described as 'Node to clear reactions from'). The description itself does not add parameter-specific meaning beyond what the schema already provides, so the baseline 3 is 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?
The description states a specific verb-resource pair: 'Clear every prototype reaction from a node'. It distinguishes itself from set_reactions by explicitly noting equivalence to an empty array and pointing to set_reactions for replacement. This leaves no ambiguity about what the tool does.
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?
Explicit guidance is given: 'Use this to strip interactivity; to replace reactions with new ones use set_reactions.' This clearly states when to use this tool and names the alternative, making the decision process straightforward.
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?
The description goes beyond the annotations by stating that the variable id is unchanged and existing bindings keep working, which reinforces the non-destructive hint. It also mentions the return shape and the folder grouping behavior. However, it doesn't cover potential errors or permission requirements, so it is not fully comprehensive.
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 two sentences, immediately front-loaded with the action and example. It includes only necessary details (folder grouping, id stability, return value) with no redundant information.
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 simple two-parameter mutation tool, the description covers the purpose, behavior, and return value. The output schema is absent, but the return is explicitly stated. Given the low complexity and clear annotations, the description is complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes both parameters (variableId and name), and the description adds useful semantics: the example for the name format and the fact that the id remains unchanged. This adds value beyond the structured schema descriptions.
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 action 'Rename' with the specific resource 'variable' and provides a concrete example ("color/primary" → "color/brand"). This distinguishes it from sibling tools like rename_node or rename_page, making the purpose unambiguous.
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 description gives clear context on when to use this tool—for renaming variables—and explains the naming convention with slashes for folder grouping. It does not explicitly mention alternatives or when not to use it, but the context is sufficiently clear for this focused 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?
Annotations only signal readOnlyHint=false and destructiveHint=false, so the description carries the behavioral burden. It explains how angles carve the wedge, what innerRadius does (0=solid disc, >0=ring), and that updates are partial. It also states the return value { ok, nodeId }. This adds meaningful detail without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the purpose and includes value explanations, the second covers constraints and return value. Every clause adds necessary context, and the most important information is front-loaded. There is no redundancy or filler.
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?
The description fully covers the tool's input semantics (units, ranges, node type restriction), update behavior (partial updates), and output (return shape). The schema and annotations handle structured details, and the description fills in the behavioral and interpretive gaps. No significant missing context for an agent to invoke the 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 schema already has 100% parameter descriptions, but the description adds concrete numeric anchors (full circle is 0 → 2π ≈ 6.28319, half is π ≈ 3.14159) and clarifies innerRadius as '0–1 of the radius' with a donut example (0.6). It also explains that all fields are optional except nodeId, and that omitted fields retain current values. This goes beyond the schema's basic type/range info.
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 specific verb+resource combination: 'Turn an ellipse into a pie slice / gauge or a ring / donut by setting its arc data.' This clearly states the tool's function and differentiates it from sibling tools like set_fills or set_strokes, which target other visual properties.
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 description explicitly notes 'Only ellipses have arc data,' telling the agent when this tool applies. It also explains the subset-update semantics ('Pass any subset — omitted fields keep their current value. At least one is required.'), which guides usage. It doesn't mention explicit alternatives, but the context is clear enough for selecting this tool over other setter 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 already mark the operation as non-read-only and non-destructive. The description adds context about property semantics and constraints (e.g., bounds apply to auto-layout frames and direct children), but it does not explicitly address error behavior when constraints are violated, which would add further transparency.
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 long but necessary for a 10-parameter tool. It is logically structured and front-loaded with the main purpose. It could be slightly more compact, but every sentence carries relevant information.
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 complex mutation tool with no output schema, it covers property semantics, prerequisites, and the return shape ({ ok, nodeId }). It does not specify behavior for invalid combinations (e.g., FILL without an auto-layout parent), which leaves a minor gap, but overall it is quite complete.
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%, so baseline is 3. The description adds interpretive value by explaining HUG/FILL/FIXED in plain terms, linking layoutAlign/layoutGrow as older equivalents, and clarifying null semantics for bounds. However, much of this is already present in the schema, so the added value is moderate.
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 specific verb and resource: 'Set a node's auto-layout sizing and child properties.' It clearly enumerates the properties and explicitly differentiates from resize_nodes by recommending HUG/FILL over guessing pixel sizes, which distinguishes it from a key sibling.
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?
It provides explicit when-to-use guidance: 'reach for these instead of guessing pixel sizes with resize_nodes' and gives conditions for HUG (needs auto-layout frame/text) and FILL (needs auto-layout parent). It also clarifies that older per-axis equivalents exist and that omitted fields are left unchanged.
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?
Given annotations already convey readOnlyHint=false and destructiveHint=false, the description adds valuable context: the plugin loads current fonts first and preserves existing character styling where possible. It also discloses the return shape, which is not covered by annotations or an output schema. This goes beyond the structured fields 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?
The description is three sentences, with the primary action front-loaded, followed by sibling differentiation and return format. Every sentence earns its place, and there is no redundant or extraneous content.
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 simple two-parameter tool with no output schema, the description is complete: it explains what it does, what could be surprising (font loading and styling preservation), how to choose alternatives, and what it returns. No additional context is needed.
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 both nodeId and characters having clear descriptions. The tool description does not add additional meaning to the parameters beyond what the schema states (e.g., 'TEXT node id' and 'New text content'), so it meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Replace the entire text content of a TEXT node', which uses a specific verb ('Replace') and resource ('TEXT node'), precisely conveying the tool's scope. It also explicitly distinguishes from siblings by directing formatting tasks to set_text_properties and multi-node substitution to find_replace_text.
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?
The description provides clear usage guidance: 'For formatting (font, size, color, spacing) use set_text_properties, and to substitute text across many nodes use find_replace_text.' This explicitly states when to use alternatives, which is exemplary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description richly discloses behaviors: ambiguity handling with candidate.ambiguousWith, framework built-in detection, multi-mode collection handling with themedCollections, map-file overrides, staleOverrides, and the return structure. It also notes a limitation (Tailwind v3 JS configs not yet parsed), which is excellent transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a dense single paragraph with many nested clauses and parentheticals. While every sentence adds substantive information, the lack of structure (e.g., bullets, sections) and its length make it harder to parse quickly. It is thorough but not concise; a more structured format would improve it.
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?
Given the tool's complexity and the absence of an output schema, the description is highly complete. It explains edge cases (ambiguity, framework built-ins, multi-mode collections), override mechanisms, stale overrides, and the return object structure. This is more than sufficient for an agent to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that tokenSource can be pointed to a CSS file when Tailwind v3 JS configs are not parsed, and that rootDir defaults to the server cwd (also in schema). This extra practical guidance pushes it above baseline.
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's purpose: mapping Figma variables and shared paint styles to project design tokens so generated code references tokens instead of hard-coded values. It uses a specific verb ('Map') and a specific resource ('the document's Figma variables...and shared paint styles...to the project's design tokens'), and it distinguishes itself from sibling tools like component_map or icon_map by targeting token mapping specifically.
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 description provides clear context for when the tool is used (mapping tokens for code generation) and includes practical guidance like using tokenSource to override detection when Tailwind v3 JS configs are not parsed. However, it does not explicitly mention alternatives or when not to use the tool, so it falls short of a 5.
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 already mark this as destructive, the description adds valuable behavior: it explains that non-group nodes are ignored rather than causing errors, and it discloses the return shape { ok, affected } with affected being the promoted child ids. This goes beyond the annotation requirements.
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 concise sentences, front-loaded with the action and outcome. No filler, and every clause adds essential information.
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 single-parameter tool with no output schema, the description covers the operation, input expectations, edge-case behavior (non-group nodes skipped), and response structure. Nothing critical is missing.
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 schema already describes nodeIds as 'Group node ids to ungroup' (100% coverage). The description reinforces this and adds the behavioral nuance that non-group nodes are simply skipped, which clarifies what happens with invalid/inapplicable entries.
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 tool ungroups GROUP nodes by id and distinguishes itself by specifying that non-group nodes are skipped. This clearly differentiates it from sibling tools like group_nodes, reparent_nodes, and 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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on usage: pass group node ids, and non-group nodes are skipped. It does not explicitly name alternatives or exclusions, but the behavior is unambiguous and sufficient for this simple 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?
Annotations only indicate a non-read-only, non-destructive mutation. The description adds valuable behavioral details: Figma stores bindings on the paint rather than the node, unbinding via null, and the 0-index default for paint selection. This goes beyond the annotation hints, though it doesn't fully cover error handling or edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: three sentences, each packed with relevant information. It front-loads the primary action, then provides necessary elaboration without repetition or fluff.
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 tool with 4 parameters and no output schema, the description covers the main use case, the alternative tool, and the return shape. It lacks some edge-case details (e.g., behavior when index is out of range or paint is not solid), but it is otherwise complete for typical usage.
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%, so the baseline is 3, but the description adds meaning by explaining the purpose of target/index defaults and clarifying that variableId null means unbind. It also introduces the 'must be SOLID' constraint not present in the schema, which aids correct usage.
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 precise action: 'Bind a COLOR variable to a SOLID fill or stroke paint', immediately clarifying what the tool does. It explicitly contrasts with bind_variable_to_node, distinguishing this tool's scope (paint bindings) from scalar node bindings, which is a clear 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 Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool vs the alternative: 'this is separate from bind_variable_to_node (which covers scalar fields like width / padding / radius)'. It also explains the paint/node distinction and the requirement that the paint must be SOLID, giving clear situational guidance.
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 only provide readOnlyHint=false and destructiveHint=false, the description adds meaningful behavior: 'The font is loaded before assignment' and explains edge-case unit semantics (AUTO omits value). It stops short of describing potential failure modes or side effects, but the added context goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the primary purpose, followed by key behavioral details and an explicit alternative. Every sentence serves a purpose, with no redundant or filler content.
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?
The description is remarkably complete given the tool's complexity: it covers creation, reusability, application method, font loading, unit specifics, the alternative for one-off use, and the return shape. Minor gaps exist around error conditions or naming uniqueness, but the core usage context is well-covered.
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 description coverage is only 17%, so the description must compensate. It does explain lineHeight and letterSpacing unit semantics, and the font loading behavior relates to fontName. However, it doesn't elaborate on fontSize, description, or the exact structure of fontName beyond what the schema offers, leaving some parameters without additional semantic depth.
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 it creates a reusable local text style (a typography token) for TEXT nodes, using a specific verb and resource. It distinguishes itself from sibling tools like set_text_properties and other create_style tools by specifying text typography and reuse.
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 provides an alternative: 'For one-off formatting of a single node use set_text_properties instead.' It also implies when to use this tool by mentioning that the style can be applied later via apply_style_to_node, making the usage context clear.
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 show readOnlyHint=false and destructiveHint=false, and the description adds useful behavioral details: rectangle defaults to image size, scaleMode options with default, and the return object shape. However, it does not address mutual exclusivity of data/url or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences front-load the purpose, then provide defaults, scaleMode, sibling alternative, and return value. No wasted words.
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 tool's complexity (9 params, no output schema), the description covers the main purpose, accepted formats, defaults, return value, and a sibling alternative. It omits the implicit requirement of providing either data or url, which would be helpful.
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 descriptions cover 67% of params. The description clarifies the data/url alternatives and explains scaleMode options with default FILL, which the schema lacks. It doesn't cover x/y, but those are straightforward positional parameters.
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 ('Import') and resource ('raster image... place it as a rectangle with an IMAGE fill'), clearly distinguishing it from the sibling tool import_svg for vector graphics.
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 directs vector SVG users to import_svg, and implies raster image use cases. This provides clear when-to-use guidance and an explicit alternative.
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 only state readOnlyHint=false and destructiveHint=false. The description adds context: it mentions the implementation via createNodeFromSvg, the default sizing behavior, and the return shape { ok, nodeId, name, type }. It does not disclose error handling or edge cases, but for a non-destructive mutation it covers most relevant 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?
The description is information-dense with no fluff. It front-loads the core function, then gives usage context, alternative guidance, and return value in a tightly structured sequence. Every sentence contributes.
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?
The description is largely complete for a 7-param, no-output-schema tool. It covers purpose, usage, alternatives, return value, and sizing behavior. It omits potential edge cases (e.g., SVG sanitization, positioning semantics), but given the context it is well-rounded. A higher score would require mention of those edge cases.
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 71% schema description coverage, the description adds meaning to svg (raw markup string, read from asset or inline) and width/height (override intrinsic size). It does not address x/y placement, but those are standard and less critical. The added semantics go beyond the schema fields.
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 identifies the verb (import) and resource (SVG), specifying it creates editable vector nodes as a frame of vector paths. It distinguishes from siblings by mentioning vector logos/brand marks/icons and explicitly contrasting with import_image for raster photos and create_instance for existing icon components.
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?
Provides explicit guidance: 'use this for vector logos, brand marks, and icons', and explicitly says 'For raster photos (PNG / JPG) use import_image instead' and 'when a matching icon component already exists, create_instance it rather than re-pasting the SVG.' This gives clear when-to-use and when-not-to-use 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 readOnlyHint=true, and the description adds recursive search behavior, default scope (current page), and flat array return format. It does not contradict the annotation and provides useful operational context beyond it, though it could mention edge cases like empty results or invalid root IDs.
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 concise sentences front-load the main action, then provide usage guidance and alternatives without redundancy. Every clause 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 moderate complexity and absence of an output schema, the description states the return format and default behavior. It clearly covers core usage and outcome, though it could note edge cases like invalid root or hidden nodes, but these are not critical for a read-only list 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?
Schema coverage is 100%, with both parameters described in the schema. The description adds practical meaning: root is optional and defaults to current page, and types is exemplified with TEXT or COMPONENT, reinforcing schema info and helping the agent map values correctly.
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's function: recursively search for nodes by type and return a flat list. It also distinguishes itself from siblings by explicitly naming search_nodes and get_design_context as alternatives for different 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 Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use this tool for collecting nodes by kind (e.g., TEXT or COMPONENT) and names alternatives for name/character search and styled tree snapshots. This provides clear when-to-use guidance and prevents confusion with sibling 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 only indicate non-read-only and non-destructive. The description adds valuable context: the effect is only on compositing, not fills, the PASS_THROUGH nuance, and the return shape { ok, nodeId }. It doesn't cover error handling or preconditions, but for a simple setter this is reasonable. 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?
Three concise, front-loaded sentences: main purpose, special-case caveat, and return type. Every sentence adds relevant information with no 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?
For a simple 2-param setter with 100% schema coverage and no output schema, the description covers return value and a key constraint. Missing error behavior and full enum list, but the provided details are sufficient for typical invocation. This is well above the minimum viable.
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 already describes both parameters, so baseline is 3. The description enriches blendMode with concrete examples and a special case (PASS_THROUGH), adding meaning beyond the schema. nodeId is clear from schema, and return info is extra but not param-specific.
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 states a specific verb+resource: 'Set how a node composites with the layers beneath it.' It lists concrete blend mode values and explicitly differentiates from siblings like set_fills and set_opacity, making the tool's scope unambiguous.
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?
Provides clear when-to-use guidance: 'use set_fills or set_opacity for those' directly names alternatives for related actions, and it explains a constraint (PASS_THROUGH only on groups/frames), helping an agent choose this tool appropriately.
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 non-readonly, non-destructive operation. The description adds valuable behavioral context by explaining what each constraint mode does and the limitation that auto-layout frames ignore these constraints, without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the primary purpose, followed by enum explanations, a critical caveat, and the return value. Every sentence earns its place with no redundancy.
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?
Without an output schema, the description explicitly provides the return shape { ok, nodeId }. It covers all three parameters, explains the enum values, and discloses the auto-layout limitation. This is more than sufficient for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While the schema describes the parameters, the description enriches the enum values with concrete spatial semantics (MIN pins left/top, MAX right/bottom, CENTER centers, STRETCH grows, SCALE proportional). This is essential for correct parameter selection and goes well beyond the schema's minimal descriptions.
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 it sets constraints on a node's response to parent frame resizing, with a specific verb and resource. It distinguishes itself from sibling tools by focusing on constraints and enumerating the available modes with concrete meanings.
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 explicitly notes that constraints only apply inside plain frames and are ignored in auto-layout frames, which is a key when-not usage signal. However, it doesn't explicitly name alternative tools (e.g., set_auto_layout), so it stops short of full alternative guidance.
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 are minimal (readOnlyHint false, destructiveHint false). The description adds meaningful behavior: unspecified properties retain values, SLOT properties are excluded, and the response shape is { ok, nodeId }. This clarifies the update semantics beyond annotated hints.
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 dense but well-organized, using examples to encode the key syntax. No filler; each sentence adds a constraint or clarification.
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?
Given 2 params and no output schema, the description addresses the key syntax, value types, unsupported slots, and return shape. It's sufficient for an agent to invoke the tool correctly without external knowledge.
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?
Schema already covers both parameters with descriptions, but the description adds substantial semantic detail: the exact key format per property type (e.g., bare name for VARIANT, '#id' suffix for others), value types, and the INSTANCE_SWAP target node id. This compensates beyond 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 clearly states the tool's function with a specific verb ('Set') and resource ('an instance's component properties'), enumerating the supported property types. It distinguishes from sibling tools by focusing on component properties and referencing get_component_api for key names.
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 implicitly indicates when to use by pointing to get_component_api as the source for property names, and explicitly notes that SLOT properties are not settable. It doesn't name alternative tools but provides sufficient context given the large sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the minimal readOnly/destructive annotations, the description discloses a significant side effect: 'A new font is loaded before assignment.' It also specifies unit semantics (AUTO omits value) and states the return shape '{ ok, styleId, name }', giving a clear behavioral model.
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 front-loaded with the core action and each sentence covers a distinct aspect: purpose, optionality, side effect, units, usage, and return. There is no filler or 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?
For a 7-parameter tool with no output schema, the description covers purpose, usage, update semantics, units, and return value. It lacks error handling or permission requirements, but those are not essential for correct 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?
With only styleId documented in the schema (14% coverage), the description compensates by explaining optionality of every field ('Any of name / fontName / fontSize / lineHeight / letterSpacing / description may be omitted to leave unchanged') and detailing valid units for lineHeight and letterSpacing. It doesn't fully describe nested structures, but it adds meaningful semantics 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 opens with 'Update an existing text style (typography token) by id,' which names the specific verb, resource, and primary parameter. It also distinguishes from create_text_style by noting 'existing' and later 'instead of creating a duplicate.'
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 description explicitly states when to use the tool: 'Use this to keep a shared style in sync with code instead of creating a duplicate.' It clearly implies the alternative of creating a duplicate style, but it doesn't name sibling tools like create_text_style or apply_style_to_node.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the minimal annotations by revealing key behaviors: the property is inert until bound, defaultValue must match the type, preferredValues only applies to INSTANCE_SWAP, and the return shape is { ok, componentId, propertyId, name } with instructions to pass propertyId to subsequent operations. These details are not present in annotations and add meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but efficiently organized: it starts with the core action, then explains the inert/bind workflow, type constraints, an important exclusion, and the return value. Every sentence contributes necessary information without redundancy or filler.
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?
The description is fully self-contained for a moderately complex tool: it defines property types, explains the attach step, gives default value rules, notes the variant-property exception, and describes the return value. Since no output schema exists, including the return shape and pointing to related tools for subsequent actions makes this exceptionally 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?
Schema description coverage is 100%, so the input schema already thoroughly documents each parameter. The description reinforces type constraints (e.g., 'defaultValue must match the type') and the INSTANCE_SWAP-only nature of preferredValues, but does not substantially add new parameter-level semantics beyond what the schema already states.
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 specific verb and resource: 'Declare a component property on a component (or its variant set)'. It clearly distinguishes the action from related tools by contrasting with bind_component_property and explicitly excluding variant properties ('VARIANT properties come from combine_as_variants, not here').
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?
The description provides concrete usage guidance by explaining that the property 'starts inert' and must be attached via bind_component_property, with type-to-layer mappings. It also gives an explicit exclusion for variant properties and points to the correct tool (combine_as_variants), making when-to-use versus alternatives very clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations only indicate a non-read, non-destructive operation, the description adds crucial behavior: atomic all-or-nothing with rollback, ordered result shape ({ ok, results } with per-op results), and rejection of destructive ops. This goes well beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences, no filler. The main purpose is front-loaded, followed by structure, constraints, and return format. 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 tool with no output schema and one complex nested param, the description adequately covers the op structure, allowed/disallowed tools, atomicity semantics, and return format. Complete enough for an agent to select and invoke 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 schema already documents 'ops' as an array of { tool, params } with high coverage. The description enriches this by clarifying that 'tool' must be an invertible write, giving concrete examples (set_fills, rename_node, move_nodes, create_frame), and specifying destructive names are invalid. This adds meaning 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 opens with 'Apply multiple invertible write ops atomically,' providing a specific verb (apply) and resource (invertible write ops). It distinguishes itself from sibling tools by explicitly restricting to invertible writes and rejecting destructive ops, making it a clear batch operation rather than an individual tool.
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 clearly states when to use: when needing atomic application of multiple invertible write ops, with rollback. It also states when not: destructive ops are rejected. However, it doesn't explicitly contrast with calling individual write tools non-atomically, leaving that alternative implicit.
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?
Beyond the annotations, the description discloses that variable's resolvedType must match the field's type, explains unbinding via null, and mentions the cornerRadius special behavior (binding all four corners at once). It also returns { ok, nodeId }. It does not detail error behavior or overwrite semantics, but the provided context is substantial.
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 two sentences, front-loaded with the main action, and every sentence adds value. It efficiently includes examples, alternatives, constraints, and return format with no unnecessary verbiage.
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?
Given the tool's complexity (binding fields, type constraints, unbinding), the description is remarkably complete: it covers the action, examples, constraint, alternatives, source of IDs, and return value. No output schema exists, but the description provides the return shape, making it fully usable.
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 schema covers parameters at 100%, the description adds meaning by listing valid field examples, highlighting the special cornerRadius case, and clarifying that variableId can be null to unbind. This goes beyond the schema's simple descriptions and helps the agent understand valid values and behavior.
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 identifies the tool's action (bind/unbind a variable to/from a node field), provides concrete field examples, and explicitly distinguishes itself from the sibling tool bind_variable_to_paint. The verb 'bind' is specific and the resource is well-defined.
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?
It explicitly states when to use this tool (binding a node field) and explicitly directs users to bind_variable_to_paint for fill/stroke colors. It also gives a prerequisite by referencing get_variable_defs for obtaining bindable variable IDs, providing clear guidance on alternatives and prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate readOnlyHint=false and destructiveHint=false, but the description adds valuable context beyond that: the variable starts empty, EASING/TIMING are rejected, and the return value is { ok, variableId, name }. It also differentiates this tool from related ones by explaining what it does NOT do (set values or bind).
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 three sentences: the first states the core purpose, the second explains the workflow, and the third notes a limitation and return value. Every sentence adds value and the most important information is front-loaded. No filler or unnecessary repetition.
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 create operation with no output schema, the description covers the essential behavior: what it creates, the allowed types, the initial empty state, the required follow-up actions, the unsupported types, and the return format. Considering the sibling tool landscape, it fully equips the agent to use this tool correctly within the broader workflow.
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 covers 100% of parameters with descriptions, so baseline is 3. The description repeats the resolvedType enum values but does not add new meaning for each parameter beyond what the schema already provides. It does mention the types in the context of the tool's purpose, but that is not extra semantic detail.
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 specific verb and resource: 'Create a variable in a collection with resolvedType BOOLEAN / FLOAT / STRING / COLOR.' This clearly identifies the tool's function and scope. It also distinguishes itself from sibling tools like set_variable_value and bind_variable_to_node by explaining the variable starts empty and requires subsequent steps.
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?
The description provides explicit usage sequencing: 'set per-mode values with set_variable_value, then attach it with bind_variable_to_node or bind_variable_to_paint.' It also gives a clear exclusion: EASING and TIMING variables cannot be created by plugins and must be made in the Figma UI. This guidance is actionable and helps the agent decide when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given destructiveHint=true, the description adds meaningful context beyond annotations: it specifies exactly what gets destroyed (property and every sublayer reference) and that it refuses VARIANT properties. It also discloses the return value, making the tool's behavior predictable.
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 sentences, front-loaded with the main purpose, then exclusions and return info. Every sentence contributes essential information without redundancy or irrelevant details.
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?
Despite no output schema, the description explicitly states the return object { ok, componentId, propertyId, name }, covers side effects (sublayer references), and explains refusal behavior. This is complete for a destructive tool with two parameters.
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 descriptive parameter texts, so the baseline is 3. The description adds minimal extra value by reminding users to obtain property ids from get_component_api, but this is already implied in the schema description for propertyId.
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 removes BOOLEAN / TEXT / INSTANCE_SWAP properties from a component and all sublayer references, which is specific and distinguishes it from sibling tools like add_component_property or edit_component_property. It also explicitly excludes VARIANT properties, further clarifying its scope.
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?
It provides explicit when-not-to-use guidance: 'VARIANT properties are the variant-set structure — delete their variants instead; this refuses a VARIANT.' It also directs users to get current property ids from get_component_api, which is a clear prerequisite. This is beyond typical guidance and helps the agent choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, and the description reinforces it with 'Permanently delete.' It adds context beyond annotations: missing/non-removable nodes are skipped, and the return shape `{ ok, affected }` is disclosed. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each earning its place: the action, the exception behavior, the alternative, and the return value. Front-loaded with the primary purpose, no redundancy or filler.
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 destructive tool with one parameter and no output schema, the description is complete: it states permanence, skips semantics, provides a reversible alternative, and specifies the return object. No critical information is missing.
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% because nodeIds has a clear description ('Node ids to delete'). The tool description adds that invalid/missing ids are skipped, which slightly enriches parameter semantics, but the core meaning is already fully documented by 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 opens with a specific verb and resource: 'Permanently delete nodes by id.' It clearly distinguishes from siblings like set_visible by noting the deletion is permanent and by offering a reversible alternative. The scope is unambiguous.
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 states when to use this tool vs. an alternative: 'To hide nodes reversibly instead of deleting them, use set_visible(false).' Also clarifies behavior for missing/non-removable nodes, so an agent knows how edge cases are handled.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description discloses the full destructive scope (removes collection, all variables and modes) and the side effect that bindings revert to raw values. It also specifies the return shape, enriching the tool's behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no fluff. It front-loads the action and consequences, then gives the alternative, then the return value—every sentence 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?
The description is self-contained, covering purpose, destructive impact, side effects, alternative usage, and return value. Given its cascading deletion behavior and lack of an output schema, this level of detail makes it fully sufficient for an agent.
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?
The sole parameter collectionId is already fully described in the schema (100% coverage). The description only repeats 'by id' without adding extra format, source, or prerequisite details, so it meets the baseline but does not exceed it.
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' and identifies the resource (variable collection), while explicitly contrasting with delete_variable for single variables. This clearly distinguishes it from sibling tools and states the operation's scope.
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?
It explicitly states 'To delete a single variable instead, use delete_variable,' providing a clear alternative and when-not-to-use guidance. This helps the agent choose between delete_variable_collection and delete_variable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even with readOnlyHint=true, the description goes beyond by disclosing that the tool writes a baseline file under .figwright/snapshots/, never touches git, and never mutates Figma. It also transparently explains the update:true re-snapshot behavior and the default nodeId/rootDir behavior, providing a complete picture of side effects and state changes.
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 dense single paragraph, but every sentence contributes: purpose, lifecycle, statuses, diff contents, update flag, defaults, file location, git behavior, and mutation guarantee. It could be slightly more scannable with bullets, but it is not padded or redundant.
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 tool with no output schema, the description covers all necessary contextual information: status return strings, what changes are included, the update mechanism, path defaults, the baseline file's relationship to git, and that Figma is never mutated. This is complete enough for an agent to invoke the tool correctly without further probing.
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 meaning beyond raw parameter names: nodeId defaults to selection and accepts pasted URLs, update:true means 'accept the changes' and re-snapshot, rootDir defaults to server cwd. These semantic details are not present in the schema and help the agent use the parameters correctly.
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 precise action: 'Diff a Figma node against a saved baseline of itself.' This clearly distinguishes it from sibling tools like get_design_context by focusing on change detection rather than full context retrieval. The scope is explicit (per-node, per-property) and the lifecycle (baseline-created vs diff) is stated.
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 gives a strong use case ('edit only the affected code instead of regenerating') and explains the first-call vs later-call behavior. However, it never explicitly names alternatives or states when not to use this tool; the guidance is implied rather than direct, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the operation as destructive, but the description adds valuable context: it is 'permanently breaking' the link, the frame 'keeps its current appearance,' and layers become 'directly editable.' It also discloses the return shape { ok, nodeId, name, type }, exceeding what annotations or schema provide.
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 two sentences that are tightly packed with purpose, effects, alternative usage, and return value. No filler or repetition of schema details. Each sentence contributes meaning.
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 simple one-parameter destructive operation, the description covers what the tool does, the permanent consequence, the retention of appearance, the editability result, the alternate tool, and the return format. It is fully complete given the tool's simplicity and existing 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?
The schema covers 100% of the single parameter with a clear description ('Instance node id to detach'). The tool description does not add additional parameter-level semantics, but the baseline of 3 applies because the schema handles the parameter meaning sufficiently.
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 'Detach' with a clear resource ('a component instance into a plain frame') and explains the consequence ('permanently breaking its link'). It also distinguishes itself from the sibling tool swap_component by explicitly naming the alternative.
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?
The description states exactly when to use this tool (when you want to detach into a plain frame) and provides an explicit alternative for a different use case: 'To switch an instance to a different component instead of detaching, use swap_component.' This is clear guidance with an exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals critical behavioral details beyond the annotations: renaming returns a new propertyId (keeping the #id suffix but changing the name part), requires using the returned propertyId later, and existing bindings keep working. It also explicitly states the return shape. These are non-obvious side effects that the annotations (readOnlyHint=false, destructiveHint=false) do not convey.
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?
Four sentences pack all essential information with no filler. The description is front-loaded with the core action, then covers usage constraint, behavioral nuance, source of IDs, and return value—all in a compact, structured manner.
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?
Despite having no output schema, the description states the return object explicitly. It covers preconditions (property ids from get_component_api), special cases (INSTANCE_SWAP only), and post-conditions (renaming ID change, bindings preserved). Given the tool's moderate complexity and five parameters, this description is sufficiently complete for an agent to invoke it 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?
Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that at least one of name/defaultValue/preferredValues must be supplied, and that preferredValues is only applicable for INSTANCE_SWAP properties. It also explains the propertyId format implication ('#id suffix is kept'), which is not fully captured in 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 opens with 'Change an existing component property' and enumerates three specific operations: rename, change defaultValue, or change preferredValues (for INSTANCE_SWAP only). This clearly distinguishes it from sibling tools like add_component_property or delete_component_property by focusing on modifying existing properties.
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 description explicitly instructs 'Supply at least one' and tells the user to get current property ids from get_component_api, which serves as a prerequisite. It implies when to use this tool (when an existing property needs modification) but does not explicitly mention alternatives or exclusions, so it's clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, it discloses the tool's inability to paginate or merge nodes, warns about slow performance on large pages, and specifies return behavior including null path when missing/not exportable and empty:true for blank PDFs. This is rich context that goes well beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Each of the four sentences carries distinct information: core function, API limitation, usage/alternative, and return values/edge cases. It is front-loaded and every sentence earns its place without fluff.
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?
Given the tool has no output schema, the description fully explains the return object and failure modes, while also covering purpose, limitations, alternatives, and parameter usage. This is a complete picture for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions already cover both parameters (nodeId and outPath) with 100% coverage. The tool description repeats the nodeId semantics and adds a performance caution for large pages, but does not significantly enhance understanding beyond what the schema 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 clearly states it exports a node or the current page to a single-page vector PDF, specifies valid node types (frame/section/component), and distinguishes itself from save_screenshots by noting raster vs vector output. This is a specific verb+resource+output combination.
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?
It explicitly names save_screenshots as an alternative for raster output (PNG/JPG), explains the API's pagination limitation to prevent mis-use for multi-page exports, and gives concrete guidance on when to pass nodeId vs omit it for the current page.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite readOnlyHint being present, the description adds substantial behavioral detail: full recursive subtree, maximum fidelity, every serialized field listed, no depth limit, no deduplication, and the exact return shape ({ node }, null when not found). This goes well beyond the simple read-only annotation.
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 sentences, front-loaded with the primary action, followed by use cases, a distinctly named alternative, and return behavior. Every sentence earns its place with zero redundancy.
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?
The description covers the tool's high complexity (recursive subtree, fidelity, field types) and provides essential context for large trees, return format, and null behavior. No output schema exists, but the description sufficiently covers what the agent will receive.
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% (nodeId is fully described with type and URL fallback). The description adds no extra parameter-level semantics beyond stating 'by id', which is already implicit in the parameter name and schema. Baseline 3 applies.
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 ('Return') with a clear resource ('one node by id') and explicitly distinguishes itself from get_design_context and other siblings by emphasizing 'full recursive subtree' with 'no depth limit' and 'no deduplication.'
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?
It explicitly states when to use this tool ('Best for inspecting a single component or a node you are about to modify') and provides a clear alternative for large trees ('prefer get_design_context'), including why (depth-limited, deduped, tokens resolved to names).
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?
The readOnlyHint annotation already signals safety, but the description adds valuable behavioral context: the return structure, that nodes are full flat serializations without children, and the meaning of an empty array. This goes beyond what the annotation alone provides, though it does not describe potential error conditions or pagination, which are less relevant for a selection getter.
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 well-structured and concise: it opens with the core action, then explains the return format and node content, and closes with usage guidance and edge-case semantics. Every sentence contributes meaningful information without redundancy.
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 simple, parameterless, read-only tool with no output schema, the description is complete: it explains the output shape, the level of detail in nodes, the workflow relationship to other tools, and the empty-selection case. There is no missing information that would prevent an agent from using it 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 tool has zero parameters, so the baseline is 4. The description reinforces this by calling it 'zero-argument' and provides no parameter details, which is appropriate since there are no parameters to document. The schema already fully covers the empty parameter set.
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's function: 'Return the current selection on the active Figma page' and specifies the exact output shape ({ pageId, pageName, nodes }). It distinguishes itself from siblings by noting it is the zero-argument 'what is the user looking at' call and explicitly points to get_design_context/get_node for deeper traversal.
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?
It provides explicit usage guidance: 'use it to identify the selected node ids (and page), then walk deeper with get_design_context or get_node.' This explains when to use this tool versus alternatives, and also clarifies the empty nodes array case, giving clear context for invocation.
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 it is a non-read-only, non-destructive mutation. The description adds valuable context by stating it does not affect a component's name elsewhere or its instances, and discloses the return value { ok, nodeId }.
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, front-loaded with purpose, followed by alternatives and return value. No wasted words, every sentence 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 simple rename tool with rich annotations and complete schema coverage, the description fully covers scope, side effects, and return format. No significant gaps.
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%, with descriptions for both parameters. The description adds nuance by clarifying the nodeId refers to a single canvas node and that the rename doesn't propagate to instances, which goes 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 clearly identifies the action ('Rename a single canvas node's layer name'), specifies the resource and scope, and distinguishes it from sibling tools like rename_page and batch_rename_nodes.
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 states when to use this tool versus alternatives: 'To rename a document page use rename_page; to rename many nodes by pattern use batch_rename_nodes.' This provides clear usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it's not read-only and not destructive, but the description adds valuable behavioral context: it affects only the page name, leaves node id and contents unchanged, and returns { ok, nodeId }. This goes beyond the bare mutation flag and helps the agent understand 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?
Three concise sentences that front-load the main action and scope, followed by a sibling pointer and return value. No wasted words, well-structured.
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 simple two-parameter mutation with no output schema, the description provides the return shape and explicitly scopes the effect. This is complete for the tool's complexity and structured context.
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 description coverage is 100% for both parameters (pageId and name), so the schema already handles parameter meaning. The description adds minimal semantic nuance ('by id') but doesn't compensate or contradict; baseline 3 is 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?
The description uses a specific verb ('rename') and resource ('Figma page'), clarifies it's a top-level page/tab, and explicitly distinguishes from the sibling tool rename_node for canvas layers. This makes the tool's purpose unambiguous.
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?
The description clearly states when to use this tool (top-level pages) and provides an explicit alternative ('To rename a layer/node on the canvas use rename_node instead'). It also notes the scope of the operation, which helps the agent decide between similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond the readOnlyHint annotation: it explains that images are deduplicated by imageHash, files are written to disk, path can be null, mixed indicates per-text-range fills, and format is sniffed. These details are not available in annotations, making the description highly transparent.
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 long but every sentence earns its place: it front-loads the primary purpose and differentiator, then systematically explains the return shape, field meanings, deduplication, edge cases, and alternatives. It is well-organized and free of fluff, making it appropriately concise for its complexity.
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?
Given the rich return type and no output schema, the description fully compensates by detailing the output structure, field semantics, deduplication behavior, and edge cases. It also covers when to use alternatives, providing complete context for an agent to invoke the tool correctly.
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?
The input schema already provides full descriptions for both parameters (outDir and nodeIds) with 100% coverage. The tool description does not add new meaning to the parameters themselves; it only restates 'write to disk under outDir' which mirrors the schema. No baseline adjustment is warranted, so a neutral 3 applies.
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's purpose with a specific verb and resource: 'Extract the ORIGINAL image bytes behind each node's IMAGE fills and write them to disk.' It also distinguishes itself from sibling tools by contrasting with save_screenshots/get_screenshot and export_pdf, making its scope unambiguous.
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?
Explicit guidance is provided on when to use this tool versus alternatives: 'unlike save_screenshots / get_screenshot which re-render the composited node' and 'For a rendered/composited raster use save_screenshots; for a vector node use export_pdf.' This makes the decision process clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses edge cases beyond the readOnlyHint annotation: clipped nodes are auto-recovered and flagged, empty nodes render blank, missing nodes produce null paths, and file names are sanitized. It also explains format and scale behavior, giving the agent a strong mental model of what happens.
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 dense but every sentence earns its place: it covers the operation, output shape, defaults, edge cases, and file naming without filler. The structure moves from general behavior to specific flags, making it easy to scan.
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?
With no output schema, the description carries the full burden of explaining return values and does so precisely with the saved array, path nullability, recovered/empty flags, and naming convention. For a 4-parameter tool, this is complete enough to invoke 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?
Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that scale only applies to raster formats, path is null for missing nodes, and outDir is created if missing—details beyond the raw schema field descriptions.
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 specific verb ('Export nodes') and clearly identifies the resource (nodes) and destination (disk under outDir). It distinguishes itself from sibling tools by specifying per-node export with a saved-array output, and the detailed format list reinforces the purpose.
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 description provides clear context for when to use the tool: when you need to export specific nodes to a directory on disk. It does not explicitly name alternatives or exclusions, but the behavior and output are fully specified, making the use case evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description reveals crucial behavioral details: case-insensitive substring matching, exact type matching, the requirement of at least one filter, default to current page, and a flat array return format. This goes well beyond what annotations provide.
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, front-loaded with the primary action and constraints. Every word earns its place with no fluff or repetition of schema data.
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 simple search tool with rich schema and readOnly annotation, the description fully covers the return type (flat array), defaults, filtering behavior, and required constraints. It is complete without needing 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?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful constraint by noting 'at least one of name or type is required' and clarifies the relationship between parameters (and/or), which the schema lacks. This elevates it to a 4.
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 it searches the node tree by case-insensitive name substring and/or exact node type. This specific verb+resource combination distinguishes it from siblings like scan_nodes_by_types which focuses only on types, and get_node which fetches a specific node.
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 description gives clear usage context by stating the required at least one of name or type, and the optional root parameter for subtree scoping. It does not explicitly mention alternatives or exclusions, but the context is unmistakable for when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate not read-only and not destructive, so the description carries the burden of behavioral context. It adds important details: coordinate interpretation (parent-relative vs canvas), layout caveat for auto-layout nodes, optional coordinate omission, and the return shape. 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?
Three sentences, front-loaded with purpose, then usage guidance, then return value. Every sentence earns its place with no redundancy or fluff.
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 simple mutation tool with no output schema, the description is complete: it explains purpose, usage context, the key caveat about auto-layout, and the return value. No missing critical 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 coverage is 100% with basic param descriptions, but the description adds meaning beyond them: explains what 'relative to parent' means for top-level vs child nodes, and that either coordinate may be omitted. This enriches the schema's minimal descriptions.
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 it sets a node's exact position (x/y) and distinguishes from move_nodes (delta) and set_layout_props (absolute positioning). The verb+resource is specific and the scope is well-defined.
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 states when to use (place overlay/badge/pinned element, position top-level frame), when not to (in-flow auto-layout nodes need absolute positioning first), and names alternatives (move_nodes for delta). This is clear when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits beyond annotations: hidden nodes remain in the layer tree, descendants are hidden, and the operation is fully reversible. This complements the annotations (readOnlyHint=false, destructiveHint=false) without contradicting them, providing the agent with a clear 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 concise and well-structured: it opens with the primary action, explains the behavioral implications in one sentence, and then provides alternatives and the return value. Every sentence earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description is complete. It covers what the tool does, its side effects (hidden from rendering/exports, descendants hidden), reversibility, alternatives, and the return shape. No critical information is missing.
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?
The schema already provides 100% coverage with clear descriptions for both parameters (nodeId and visible). The description adds no new parameter-specific details beyond what the schema states, but it does clarify the overall effect of the visible flag, which is marginal added value.
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's function: 'Show or hide a node by toggling its visible flag.' It distinguishes itself from siblings by explicitly mentioning delete_nodes and set_opacity as alternatives, making the tool's specific purpose unambiguous.
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?
Explicit guidance is provided: it explains the tool's effect on rendering and exports, notes reversibility, and gives clear alternatives ('To remove a node use delete_nodes; to dim one... use set_opacity'). This tells the agent exactly when to use this tool versus related ones.
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?
Beyond the minimal readOnlyHint/destructiveHint annotations, the description adds valuable behavioral details: ids that no longer exist are skipped, and the return value is { ok, affected } with the ids actually unlocked. This gives the agent insight into edge-case behavior and the response format. It could mention error handling but covers the important traits 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?
The description is exactly two sentences: the first front-loads the primary purpose and relationship to lock_nodes, the second adds behavioral detail and return shape. Every word contributes value, with no redundant or filler content.
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 single-parameter tool with no output schema, the description is complete: it states the action, explains the purpose, reveals behavior for invalid ids, and specifies the return structure. No additional context is needed for an agent to invoke it 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 already provides the parameter name and a descriptive sentence ('Node ids to unlock'). The description enhances this by noting that non-existent ids are skipped and that the response reports the ids actually unlocked, giving the agent a better understanding of how the nodeIds parameter behaves.
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 the specific action 'Unlock nodes' and states the purpose 'so they can be selected and edited on the canvas again'. It explicitly names itself as 'the inverse of lock_nodes', clearly differentiating it from the sibling tool and leaving no ambiguity about its function.
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?
The description tells the agent exactly when to use this tool: when nodes are locked and need to be selected/edited. It identifies the direct alternative (lock_nodes) as its inverse, and the purpose statement makes the use case explicit. No exclusions are necessary for such a straightforward reversal operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses important behavioral details: partial updates (omitted fields leave unchanged), replacement semantics for 'effects', and requirements like 'Shadows need color + offset; blurs need radius'. It also specifies the return shape '{ ok, styleId, name }'. This goes well beyond the basic read/write flags.
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 three sentences, front-loaded with the core purpose. Each sentence adds value: target and update behavior, effect-specific requirements, and usage guidance plus return value. No wasted words.
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?
Given the tool's complexity (nested effect definitions, partial updates) and the absence of an output schema, the description covers all critical aspects: purpose, update semantics, parameter constraints, usage context, and return value. It is sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning not fully present in the schema. It explains that name/effects/description can be omitted to remain unchanged, that the effects parameter replaces the whole list, and gives per-effect requirements (color+offset for shadows, radius for blurs). This compensates for the 50% schema description coverage.
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 'Update an existing effect style by id', a specific verb and resource with a clear identifier. It distinguishes from sibling tools like update_paint_style and create_effect_style by emphasizing the update semantic and the advice to 'keep a shared style in sync with code instead of creating a duplicate'.
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 description provides clear guidance: 'Use this to keep a shared style in sync with code instead of creating a duplicate.' This explicitly indicates when to use the tool and contrasts with creating a new style, though it does not name the exact alternative tool or explicitly state when not to use it beyond the duplicate scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses meaningful behavior: instances resolve to their main component/set, the exact return shape, and the property naming convention for set_instance_properties. It also notes safety on large files, adding practical context.
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 dense sentences, each earning its place. The first sentence states the core purpose, the second details the return structure, and the third covers naming semantics and differentiates from get_local_components. No wasted words.
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?
With no output schema, the description fully compensates by explaining the return object shape, property map types, and naming conventions. It also addresses performance context and input variations, making it complete for practical use.
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%, so the baseline is 3. The description adds a genuinely useful nuance beyond the schema: 'an instance resolves to its main component / set'. This extra semantic detail merits a 4.
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 specific verb and resource: 'Return a component's full property API — the prop contract behind its instances.' It clearly scopes the tool to a single component and explicitly contrasts it with get_local_components, making it easy to distinguish from siblings.
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?
The description explicitly says 'Unlike get_local_components (a subtree inventory), this targets one component and is safe on large files.' This names the alternative and gives a clear when-to-use signal. It also lists accepted id types, further guiding invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true, so the description carries the transparency burden. It discloses error behavior when neither nodeId nor selection is available, graceful degradation from full to compact to sectionPlan, dedupe semantics with flags and preserved overrides, and the hypothesis-based nature of projectTokens. This is far beyond what annotations provide.
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 dense single paragraph, front-loaded with the main purpose and containing no filler. However, the length and density could benefit from bullet points for scannability, especially the degradation and token-matching caveats. Every sentence earns its place, so no waste, but structure is a minor miss.
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?
With no output schema, the description fully explains return shapes (sectionPlan, projectTokens, dedupe flags), error cases, and the over-budget degradation path. It also covers edge cases like multiple tokens sharing a value and how to verify matchedBy. This is comprehensive for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds operational depth: detail levels map to output shapes, depth=0 means unlimited with truncation flags, and dedupeComponents collapses subtrees while preserving textOverrides and propertyOverrides. For example, it explains that deduped instances still carry visible text, which is not inferable from 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?
Description states 'Get a depth-limited, token-efficient node tree' and positions it as 'the main design-grounding read', clearly distinguishing it from sibling tools like get_document and get_node. The verb 'get' plus the resource 'node tree' with scope qualifiers makes purpose unmistakable.
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 directs 'prefer it over get_document / get_node for anything large', and gives specific tactical guidance: 'pass detail: compact explicitly for a cheap structure scan' and warns 'do not retry unscoped — call again per section nodeId'. This is strong when/when-not guidance with named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context: coordinates become relative to the new parent, missing nodes are skipped, and index defaults to appended last. These are useful side-effects not obvious from annotations or 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?
Three concise sentences, front-loaded with the primary action, followed by edge-case behavior, alternatives, and return value. No wasted words.
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?
The tool has 3 parameters, all documented, and no output schema. The description provides the return shape ({ ok, affected }), covers exceptions (skipped nodes), and clarifies side effects (position shift). This is complete for the tool's complexity.
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%, so baseline is 3. The description adds meaning by explaining the index parameter's default behavior ('default: appended last') and that nonexistent nodes are skipped. This goes beyond raw schema descriptions.
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 moves nodes into a different parent, using a specific verb and resource. It explicitly distinguishes itself from sibling tools by mentioning reorder_nodes and group_nodes as alternatives for different 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 Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use this tool vs alternatives: 'To reorder within the current parent use reorder_nodes; to wrap nodes in a new frame/group use group_nodes.' This gives clear context and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint false and destructiveHint false, so the description carries the burden. It discloses that grids are replaced wholesale, empty array clears them, only certain node types are valid, and the return shape is { ok, nodeId }. This is valuable context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences: purpose, pattern details, and behavior/return. It is front-loaded with the core action and contains no redundant or filler content.
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 two-parameter tool with an array parameter and no output schema, the description covers valid node types, replacement/clear behavior, return shape, and grid pattern semantics. An agent has enough information to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds pattern semantics (e.g., '12-col grid', '8pt baseline') and explains how gutterSize/alignment/sectionSize relate to pattern types, going beyond the schema's field descriptions. This extra meaning justifies a 4.
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 'Set a frame's own layout grids' with a specific verb and resource, and explicitly distinguishes from set_auto_layout. It also explains the grid patterns (COLUMNS/ROWS/GRID) with examples, making the tool's purpose unmistakable.
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?
It explicitly contrasts with set_auto_layout ('arranges children') and notes that 'Only frames (and components/instances) carry layout grids', giving clear scoping. The description also explains how to clear grids with [] and that the operation replaces existing grids, providing actionable usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses critical behavior beyond annotations: multiplicative blend with fill/stroke alpha, and opacity 0 still renders/exports/hit-tests. Return value is also stated. 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?
Two sentences packed with essential info, front-loaded with purpose, no filler.
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 simple 2-param tool with no output schema, description covers purpose, semantics, alternatives, and return value—fully sufficient.
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 covers both parameters at 100%, but description adds semantic clarity (transparent to opaque, multiplicative effect) that enriches understanding beyond plain schema descriptions.
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 verb and resource: 'Set a node's layer opacity' with range. Explicitly distinguishes from siblings by mentioning set_visible and delete_nodes.
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?
Provides clear when-to-use vs alternatives: opacity 0 still renders, so use set_visible to exclude and delete_nodes to remove. Offers explicit alternatives and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the critical behavioral trait that it overwrites existing reactions rather than appending — a nuance not captured by the readOnlyHint/destructiveHint annotations. It also states the return value '{ ok, nodeId }', adding transparency beyond what annotations offer.
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 only. The first sentence states the core behavior; the second packs the data structure, usage context, alternative, and return value. Every phrase earns its place with no filler or redundancy.
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?
Despite the lack of an output schema, the description documents the return value, the primary use case, the overwrite behavior, and the alternative tool. For a simple 2-parameter tool, this is fully self-contained and leaves no major gaps.
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 schema already documents both parameters, but the description adds concrete JSON examples for trigger ({ type: 'ON_CLICK' }) and actions ({ type: 'NODE', destinationId, navigation, transition }), making the data shape more tangible. This reinforces the schema without repeating it verbatim.
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 'Replace all of a node's prototype reactions' — a specific verb, resource, and scope. It explicitly contrasts with appending ('overwrites existing reactions rather than appending') and distinguishes from remove_reactions, making it clear what this tool does and how it differs from siblings.
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?
Provides explicit guidance: 'Best used to round-trip get_reactions output' tells the agent exactly when to use this tool. It also names an alternative, 'to clear all reactions instead use remove_reactions', giving a clear when-not-to-use and an exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that ranges apply in order with later overrides, and that fonts load automatically — beyond the annotations' simple readOnly/destructive flags. It also warns to set the whole node first, a key prerequisite.
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 front-loaded with the purpose and then packs every sentence with useful detail — examples, properties, ordering, font loading, prerequisites, and return value. No filler.
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 write tool with a complex nested parameter, the description covers the key preconditions and alternatives, and states the return shape since there is no output schema. It is sufficiently complete for correct selection and 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?
Schema coverage is 100%, so the baseline is 3. The description adds that each range applies 'any subset of run properties' and clarifies the sequential override behavior, which enriches the ranges parameter semantics without fully duplicating 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 opens with 'Style character ranges of an existing TEXT node' — a specific verb and resource. It explicitly distinguishes from siblings by naming set_text and set_text_properties as alternatives, and gives concrete examples of inline rich text.
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?
It states 'Set the whole node first with create_text / set_text; use set_text_properties for node-level typography & overflow' — explicit when-to-use and alternatives. The phrase 'write-side mirror of a read segment' also frames when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the minimal annotations (readOnlyHint=false, destructiveHint=false) by disclosing that EASING/TIMING variables are rejected by Figma, that the value must match the resolvedType, and the exact return shape { ok, variableId, name }. 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?
Three sentences, each earning its place. Front-loads the purpose, then covers type constraints, read-only exceptions, prerequisite, and return value. No redundancy or filler.
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 mutation tool with only three parameters and no output schema, the description is complete: it covers required value types, the read-only edge case, a prerequisite, the origin of modeId, and the response shape. This is sufficient for an agent to invoke the tool correctly in most scenarios.
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%, so the baseline is 3. The description adds context beyond the schema by explaining that the value must align with the variable's resolvedType and by detailing the allowed value forms (color, alias, etc.). It also clarifies the source of modeId. The schema includes an easing type, but the description warns against using it, adding practical guidance.
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 action ('Set a variable's value') and the scope ('for one mode'), with the modeId explicitly tied to the variable's collection. It distinguishes this from sibling tools like rename_variable and create_variable, and even differentiates from get_variable_defs for reading.
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?
The description provides explicit when-not-to-use guidance for EASING and TIMING variables, directing the agent to get_variable_defs and the Figma UI instead. It also states the prerequisite of creating the variable first with create_variable, and clarifies that modeId comes from the collection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true, but the description discloses extensive behavioral traits: auto-fit scaling behavior, scale caps at 2576px, batch size limits (20 nodes), total size caps (~2.4MB per frame), and handling of missing/recovered/empty nodes. This far exceeds what annotations provide and does not contradict 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?
Although lengthy, every sentence carries unique information about scaling, batching, edge cases, or alternatives. The description is front-loaded with the core purpose and output structure, then logically progresses through scale behavior, capacity limits, and recovery semantics without redundancy.
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?
The description is remarkably complete: it specifies return format, scaling constraints, batch limitations, fallback behavior, and explicitly names alternatives. No output schema exists, so the description fully compensates by detailing the output shape and special flags, making the tool's behavior predictable in all mentioned scenarios.
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 description coverage, the description adds significant nuance: 'scale applies to raster formats; when omitted, each node is auto-fitted', 'explicit scale is capped so the long edge stays within 2576px', and format defaults. It also explains the meaning of output fields like base64, recovered, and empty, enriching understanding 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 clearly states the tool's function: 'Export nodes as images the model can see' with a specific verb and resource. It also distinguishes itself from siblings by explicitly recommending 'save_screenshots' for full-res or batch needs, making the purpose unambiguous.
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?
The description provides explicit usage guidance: 'use save_screenshots when you need a full-res file on disk' and 'or use save_screenshots for many nodes at once.' It also gives conditions like 'ask for fewer nodes when you need the detail' and explains when batch limits apply, offering clear when-to-use vs. alternatives.
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:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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/awdr74100/figwright'
If you have feedback or need assistance with the MCP directory API, please join our Discord server