Figxel

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the description's added value is what matters, and it delivers a lot: what binding actually does ('instances then edit the label without detaching'), the reuse contract with the `reused: true` flag, the return value shape, and environment limits (Design verified; FigJam and Slides unverified).

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

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

Front-loaded with the core action, and every clause carries information (four type behaviors, the return key, the reuse rule, sibling routing, editor coverage). It is dense and packed into one long paragraph, which slightly hurts scanability, but there is little dead weight.

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

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

With no output schema, the description correctly fills the gap by stating what is returned (the property `key` as name + #id that figma_set_instance_properties accepts) and that a plain name works too. Combined with type semantics, reuse behavior and editor support, an agent has everything needed to call it correctly.

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

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

Schema coverage is 88%, so the baseline is 3. The description still adds genuine meaning on top: it explains that bindNodeIds wires text layers for TEXT, that BOOLEAN drives show/hide, that INSTANCE_SWAP's default is a component id, and that VARIANT only applies to sets — semantics the bare enum does not convey.

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

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

States a specific verb+resource ('give a component ... a property that instances can change') and immediately enumerates the four property kinds with their distinct semantics. It clearly differentiates itself from figma_edit_component_property, figma_delete_component_property and figma_create_slot by naming when each is the right call.

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

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

Explicitly routes the agent: use figma_edit_component_property to rename, re-default or unwire, and figma_create_slot for slots. It also documents the re-call/reuse case ('called again with a name and type that exist, it reuses that property') and notes VARIANT is 'on a set only', so both when-to-use and when-not-to-use are covered.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=true), but the description adds real behavioral context beyond them: the paid-plan gating rule, the fact that Figma's own refusal message is surfaced, the returned modeId, and the editor support matrix (Design; unverified FigJam/Slides). This is well above the lower bar set by the annotations.

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

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

Front-loads the core action and return value, then adds plan gate, follow-up tool, and editor support in tight clauses. No sentence is filler and none repeats structured data verbatim.

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

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

For a 4-param mutation with no output schema, the description covers the return value, plan prerequisite, error behavior, and next step, so an agent can call it correctly. The only remaining gap is the undocumented collectionId/name semantics.

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

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

Schema description coverage is only 50% (session and idempotencyKey are documented; name and collectionId are not). The description mentions the target collection and the mode name example "Dark" but adds no format, uniqueness, or identifier semantics for the undocumented required parameters. With half the parameters bare in the schema, the description does not fully compensate.

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

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

States a specific verb (Add) and resource (a mode to a variable collection), names the counterpart operation in the title, and discloses the return value (modeId). It is clearly distinguishable from sibling tools like figma_set_variable_mode, figma_update_variable_collection, and figma_create_variable_collection.

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

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

Gives concrete context: modes beyond the first require a paid plan, Starter files are refused with the message returned, and the follow-up step is routed explicitly to figma_set_variable_value. It also documents supported editors. It stops short of naming a when-not alternative beyond the plan gate, so it is a strong 4 rather than a 5.

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

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

Annotations cover the safety profile (readOnly=false, idempotent=true, destructive=false), and the description adds genuine behavior: per-item partial-success semantics ('one node failing does not fail the call'), the exact return shape, and editor support ('Design; unverified: FigJam, Slides'). It stops short of stating that applying a style replaces existing fills/strokes.

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

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

A single dense paragraph where every clause carries routing or behavioral information; the core action is front-loaded before the alternatives and edge cases. No filler sentences.

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

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

With no output schema, the description supplies the return contract (`{ updated, items: [{ id, ok, error? }] }`), the partial-failure rule, the style-source alternatives, and platform coverage — everything needed to call it correctly and interpret results.

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

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

With 83% schema coverage the baseline is 3, but the description adds real meaning beyond the enum: `type` defaults to fill and can be stroke when applying a paint style, and it explains the id-vs-name distinction for styleId/styleName. It does not touch `session` or `idempotencyKey`, which the schema already documents.

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

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

States a specific verb and resource (apply a local style to a node), enumerates the style kinds (paint, text, effect, grid), and clarifies the effect ('the node then follows the style'). It is readily distinguishable from siblings like figma_create_paint_style and figma_set_fills.

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

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

Explicitly routes the agent: use figma_set_fills for a raw colour, figma_get_styles for local styles, and figma_get_design_context's `stylesUsed` id for library styles. It also states when `type` is needed (shared name across kinds, or paint-as-stroke with fill as default).

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

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

Annotations only declare readOnly=false, destructive=false, idempotent=true, openWorld=false. The description goes far beyond: stop-at-first-failure with no rollback, partial.steps/partial.failedAt semantics, whole-batch Ctrl+Z undo, the 1–50 step limit, pre-flight validation of each step against its own tool parameters, and the BRIDGE_PROCESS motion gate. This is exactly the extra behavioral context the annotations cannot carry.

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

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

Front-loads the core value (ONE call, ONE undo) and the create/delete exclusions before the mechanics. Everything present earns its place, though the single dense paragraph packs success/error shapes, validation, and the motion gate together, which costs some scannability.

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

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

This is a complex aggregator tool with no output schema, so the description carries the full burden of describing returns — and it does: the success object shape, the itemsFailed array, and partial failure reporting. Combined with the step format and exclusions, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: op names must omit the figma_ prefix, the 1–50 step range, and that each step is validated against its own tool's parameters before execution. Session and idempotencyKey are left to the schema, which documents them adequately.

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

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

States a specific verb+resource ('several edits in ONE call and ONE undo step') and scopes the resource precisely: fills, strokes, radius, effects, auto-layout, sizes, text, constraints, names. It also distinguishes itself from siblings by explicitly excluding creates (naming figma_create_from_spec), deletes, and node-replacing ops (group, boolean, flatten, clone), so an agent can differentiate it from hundreds of siblings without reading a schema.

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

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

Gives explicit when-to-use ('a polish pass over what you built'), when-not (no creates, no deletes, nothing that replaces nodes with new ids), and names the alternative for the excluded case (figma_create_from_spec builds). It also flags the motion-gate prerequisite for keyframe steps, so the agent knows exactly what conditions apply.

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

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

Annotations only declare the safety/idempotency profile; the description adds genuinely new behavior — per-item results `items: [{ id, ok, error? }]` and the key guarantee that one failing node does not fail the whole call, plus partial platform support. It does not mention reversibility (e.g. that an undo step can roll back renames), which is the main remaining behavioral gap.

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

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

Four tight sentences, front-loaded with the core operation and then the result semantics and platform caveat — each sentence carries information and none is padding. Slightly compressed in places ('Scope, optional type filter, optional regex' is telegraphic), but that density is efficient rather than confusing.

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

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

With no output schema, the description correctly compensates by describing the per-item result envelope and partial-failure behavior, and it covers the three operating modes. For an 8-parameter mutation tool the description plus the high-coverage schema is nearly complete; only reversibility/cleanup guidance is absent.

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

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

Schema description coverage is 88%, so the schema already documents scope, types, regex, nodeId, session, and the idempotencyKey retry contract in detail. The description only restates 'scope, optional type filter, optional regex' and adds no format or interaction detail (e.g. how nodeId pairs with scope='subtree') beyond what the schema provides, so the baseline 3 applies.

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

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

'Bulk rename by find/replace over names' states a specific verb, resource, and mechanism, which cleanly separates it from the single-node figma_rename_node and the text-content figma_find_replace_text. It stops short of naming those siblings, so an agent must infer the distinction from 'names' vs 'text'.

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

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

The example ('turning `Frame 12` into `Card / 12`') and the mention of scope/type filter/regex imply intended usage, and the editor note ('Design; unverified: FigJam, Slides') is useful environment guidance. However, there is no explicit when-to-use-vs-figma_rename_node or vs figma_find_replace_text routing, which matters given how many rename-adjacent siblings exist.

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

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

Annotations cover the safety profile (readOnly=false, idempotent=true, destructive=false), and the description adds substantial behavior beyond them: per-item result shape, that one failing node does not fail the whole call, per-item refusals for unsupported text fields, and editor support (Design verified; FigJam/Slides unverified).

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

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

Front-loaded with the core purpose, then the field taxonomy, alternative routes, and return shape. It is dense and the long field enumeration is heavy, but nearly every clause carries actionable information an agent needs to pick valid field values.

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

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

No output schema exists, but the description supplies the return contract ({ updated, items: [{ id, ok, error? }] }), failure semantics, refusal cases, and editor coverage. Combined with the fully documented schema and idempotencyKey retry guidance, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% so baseline is 3, but the description adds real meaning: it explains which `field` values exist and their semantics, that `index` selects the specific paint/effect/grid and must be SOLID, and how variableId vs variableName relate. This goes beyond the schema's terse examples.

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

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

States a specific verb+resource+scope: binding a variable (design token) to a node property so the node follows the variable. It enumerates exactly which properties are bindable, letting an agent distinguish it from siblings like figma_set_variable_value (changes a value) or figma_create_variable (creates a token).

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

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

Gives clear routing context: library variables bind by the id reported by figma_get_variable_defs { nodeId }, and a token inside a style is handled by figma_update_style instead. It also states exclusions (gradient/image paints are refused, not replaced). It stops short of an explicit when-not-to-use-this vs figma_set_variable_value comparison.

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

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

Annotations already declare the mutation-safe profile (readOnly=false, idempotent=true, destructive=false), so the bar is lower. The description adds real behavior: the result takes the lowest shape's place, the resulting id is returned, and the parent-sharing constraint. It does not explain what happens to the source shapes' child structure, leaving a minor gap.

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

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

Front-loaded with the core action, then the four modes, then placement/return behavior, then use cases and editor scope. Dense but every clause carries information; no filler sentences.

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

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

For a mutation tool with no output schema, it covers modes, placement, returned id, parent requirement, and editor support. The one omission is what happens to the original nodes' internal hierarchy after the boolean, a detail an agent might need.

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

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

Schema coverage is 60%, and the description enriches the operation enum with per-value meaning (union, subtract, intersect, exclude) that the schema lists only as bare names. It also implicitly reinforces the multi-node input, though it adds nothing for the undocumented `name` parameter.

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

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

States a specific verb and resource (combine shapes into one boolean shape) and enumerates all four operation modes with plain-language definitions of each. An agent can distinguish this from nearby siblings like figma_flatten_nodes, figma_group_nodes, and figma_ungroup_nodes without opening the schema.

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

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

Gives clear usage context ("Builds icons, badges, cut-out shapes and logos") and a hard prerequisite (shapes must share a parent), plus editor support notes. It stops short of explicitly contrasting when to pick this over the sibling flatten/group/ungroup tools, so it is clear context rather than full when/when-not routing.

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

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

With readOnlyHint/openWorldHint/destructiveHint already covering the safety profile, the description adds meaningful context: result semantics ('ok: true = no errors or warnings'), each audit pass behavior, that 'tells' is informational only, and that tokens pass returns the variable to bind. It also implies cost bounds via maxNodes defaults. It does not discuss pagination or performance limits beyond that.

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

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

Front-loads the timing and purpose, then compresses defect classes and audit-pass semantics into a dense but scannable telegraphic style. Every sentence carries information, though the heavy semicolon/backtick packing makes it harder to parse than a cleanly structured list would be.

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

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

With no output schema, the description carries the return burden and does so partially: it explains 'ok: true' and 'number and fix' per finding, default scope, and audit-pass additions. It covers enough for a correct invocation, though result shape details (severity fields, counts) are only implied.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds cross-parameter semantics the schema lacks: safeArea and minTextSize 'imply craft', expectFonts 'implies the fonts audit', and each audit enum value is explained with its output meaning (e.g. tells = info only). This goes beyond restating the schema.

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

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

States a specific verb and resource (checks a Figma design/selection for layout defects) and enumerates the concrete defect classes it reports (overflow, overlap, clipping, placeholder copy, low contrast, zero-size nodes). It explicitly contrasts itself with the visual sibling figma_export_node and distinguishes itself from the surrounding mutation tools in the suite.

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

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

Gives clear timing guidance ('after each section and before calling anything done') and names the alternative for the visual view (figma_export_node). It also states the default scope (selection, then page, or focused slide). It stops short of explicit when-not-to-use or exclusion conditions, but the context is unambiguous.

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

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

Annotations only declare readOnly/non-destructive/closed-world; the description adds genuinely new behavior — keyframe-based analysis with no render, the meaning of ok:true, the export-unlock gate that expires when the file changes, and the plan-default-fill behavior. It does not cover permission requirements or error/limit behavior, so it stops short of the top of the range.

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

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

Purpose is front-loaded in the first clause and the removal signal ('no render') lands immediately. It is a dense wall of clauses for a 20-parameter tool, but nearly every sentence maps to a distinct capability or workflow step rather than padding.

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

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

Despite no output schema, the description sketches the return shape ('each issue names layer, field, frame and numbers at fps, with a fix') and the ok:true contract, and it covers the surrounding workflow and the unsupported case. For a complex 20-param checker 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.

Does 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 goes beyond the schema by explaining cross-parameter semantics: which params the plan supplies by default, that `holds` are exempt from dead_span, that `rules`/`from`/`to` must stay as loose as the plan to preserve the ok verdict, and that bpm/beatTimes/brandId/ctaId each toggle a specific rule.

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

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

States a specific verb and resource ('frame-by-frame check of an animated top-level frame from its keyframes'), plus a crisp scope qualifier ('no render'). It explicitly positions itself against the sibling figma_check_layout, so an agent can distinguish the two without opening either schema.

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

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

Gives when-to-use via the workflow chain: figma_set_motion_plan fills bpm/holds/brandId/ctaId, this check runs, a clean pass unlocks figma_export_video { final: true }, then figma_review_video. It names the alternative (figma_check_layout) and states the failure-mode scope (UNSUPPORTED: no Figma Motion here), leaving little to inference.

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

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

Annotations already cover the safety profile (write, non-destructive, idempotent), so the description earns credit for adding behavior: the clone carries the entire subtree, and for slides it lands adjacent in the row and returns row/col. It doesn't say whether the source is untouched or what the default placement is for a non-slide node (the schema's parentId default handles that), leaving a modest gap.

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

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

Three sentences, front-loaded with the core action before the slide special case. The slide sentence is dash-heavy and dense, but no sentence is wasted.

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

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

For a write tool with full annotation coverage and no output schema, the definition covers what it does, where it is supported, and part of the return shape (row/col). It never mentions whether the original node remains unchanged or whether the duplicate inherits names, which an agent might wonder about.

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

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

Schema coverage is 57%, so the description should compensate but mostly restates the schema's own parentId slide-row note ("a SLIDE_ROW") and position semantics. Its only genuinely additive parameter information is the row/col return values, which matters because there is no output schema.

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

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

"Duplicate a node with its whole subtree" is a precise verb+resource, and the parent/position clause clarifies scope beyond a simple copy. It does not name a specific sibling (e.g., figma_reparent_nodes or figma_create_instance) that an agent might confuse it with, so it stops short of the top band.

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

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

It states the context in which the optional parentId/repositioning applies and scopes editor support ("Editors: Design; unverified: FigJam, Slides"), which is real selection guidance. It never names an alternative tool or a when-not condition, so it is clear context without exclusions.

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

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

Annotations already declare readOnly=false, destructive=false and idempotent=true. The description adds real context beyond them: the naming convention Figma uses to derive properties, the shared-parent constraint, default wrapping-row layout, and that the grid mode returns page coordinates for external header labels.

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

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

Front-loaded with purpose, then prerequisites, layout behavior, follow-on workflow, and editor support in a tight sequence. Dense but every sentence carries operational weight; the editor-support tail is the only marginal line.

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

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

For an 8-parameter mutation tool with no output schema, the description covers prerequisites, layout modes, and the notable return value (grid coordinates). It stops short of describing error/rollback behavior, but the essentials for correct invocation are present.

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

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

Schema coverage is already 88%. The description still adds meaning for the non-obvious parameters, clarifying what `arrange: false` does and how `columns: "State"` produces columns per value and rows per combination, plus the returned grid coordinates — details the schema comments only summarize.

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

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

States a specific verb and resource — 'Combine components into one component set (variants)' — and anchors it to the Figma feature of the same name. It is clearly distinguishable from siblings like figma_convert_to_component and figma_group_nodes.

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

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

Spells out prerequisites (name each component 'Property=Value' via figma_rename_node first, components must share a parent) and the follow-on workflow (figma_create_instance to place, figma_set_instance_properties to switch), naming the sibling tools explicitly. It also flags editor support (Design; unverified Slides).

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

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

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the description only needs additive context. It supplies the failure conditions and the fact that the original node is preserved with its children and a new id is returned, plus editor/platform availability. It stops short of describing what happens to existing instances or references to the original node.

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

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

Three tight sentences, front-loaded with the core action, followed by constraints and the sibling routing. No filler, and the parenthetical asides earn their place.

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

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

With no output schema, the description helpfully notes the returned id, and it covers preconditions and platform scope. It could say more about the return payload or how the new component relates to the original node, but it is sufficient 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.

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

Schema description coverage is 100%, so all five parameters (including name defaulting and idempotencyKey retry semantics) are fully documented in the schema. The description adds essentially no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Turn an existing node ... into a reusable COMPONENT') and clarifies the colloquial equivalent ('the toolbar's Create component'). It is clearly distinguishable from siblings like figma_get_component or figma_create_instance.

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

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

Explicitly states preconditions where conversion is impossible (already a component, or inside a component/instance) and names the follow-up alternative for placing copies (figma_create_instance). This is exactly the when/when-not/alternative structure the dimension rewards.

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

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

Going beyond the annotations (which only declare non-readonly, idempotent, non-destructive, closed-world), the description discloses the creation mechanics (one plate per panel, frame-exact opacity cuts), that outputs are read back as `verified` or `notApplied`, that plates 2–n rest at opacity 0, and that it costs one undo step and is Design-editor-only + unverified. This is rich behavioral context; only minor gaps (e.g. failure modes, scale limits) remain.

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

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

Purpose is front-loaded in the first clause, and the dense detail that follows is generally relevant. It is long and several clauses are run-on, but for a complex 10-parameter generative tool most sentences earn their place.

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

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

With no output schema, the description compensates by describing return semantics (`render` is the export_video call, `blank` lists empty panels, per-track `verified`/`notApplied`), the visual result, the frame-timing mechanics, editor restrictions, and undo cost. Nothing essential for invoking it correctly appears to be missing.

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

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

Schema description coverage is already 90%, so the schema documents x/y/drift/width/burnIn/dissolveFrames/idempotencyKey thoroughly. The description restates and contextualizes a few behaviors (dissolveFrames cross-fades, drift pushes 3%, burnIn labels, blank lists empty panels) but adds little syntax or format detail beyond the schema. Baseline 3 applies.

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

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

Names a specific verb and resource ('turn a figma_create_storyboard board into an animatic') and describes the concrete artifact produced (a top-level frame `Animatic · <title>` with one plate per panel). It explicitly references the sibling figma_create_storyboard it consumes, so an agent can distinguish it from other create tools at a glance.

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

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

Lays out a clear pipeline: read timing from the board as-is, then export via figma_export_video and judge pace with figma_review_video, with the storyboard skill guide referenced. It gives context for when this applies, but does not state explicit exclusions or when-not-to-use conditions.

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

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

Annotations cover the safety profile (destructiveHint=false, idempotentHint=true), and the description adds behavior beyond that: unrecognized language values are refused rather than silently falling back to plaintext, styling is fixed by FigJam, and environment support is 'unverified'. The idempotency-key retry semantics live in the schema, so the description is right not to repeat them.

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

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

It is compact and front-loaded with the resource and the most important parameter (language), and the refusal rule and styling constraints follow. The telegraphic fragments and the trailing 'Editors: FigJam only, unverified' are slightly cryptic, but nothing is wasted.

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

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

For an 8-parameter creation tool with only one required param, full schema coverage and matching annotations, the description supplies the environment scope, the language semantics and the styling limits an agent needs. No output schema exists, but the return value is a created node and the annotations plus idempotency key cover the risky parts.

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

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

Schema coverage is 100%, so a 3 is the baseline. The description adds genuine meaning on top of the schema: language matching is case-insensitive, plaintext is the default, and 'dart is in the Plugin API but not yet confirmed on the canvas' gives a caveat the schema does not. That pushes it above baseline.

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

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

The name and title establish the verb+resource ('create a code block'), and the description pins it to FigJam with syntax highlighting, which distinguishes it from generic siblings like figma_create_text, figma_create_table and figma_create_stickies. The description itself opens with a noun phrase rather than a verb, so it leans on the name/title for the action.

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

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

It gives concrete usage constraints: FigJam-only environment ('Editors: FigJam only, unverified') and 'no theme, font or size to set', which steers the agent away from trying to set styling. It also states the language default and refusal behavior. It does not name an alternative tool, but for a creation tool the environment constraint is the key guidance.

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

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

Annotations only cover readOnly/idempotent/destructive/openWorld; the description adds non-obvious behavior the annotations cannot convey: connectors are created in their final parent (lowest shared section, else page), are never moved, and reparenting leaves stale elbows — hence build last. It also documents default cap behavior and default lineType, which materially affects the result.

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

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

Front-loaded with the action and batch limit, then endpoints, then defaults. Dense but each clause carries information; the main inefficiency is restating the endpoint syntax and lineType/cap defaults already present in the schema. Hedges like 'to be confirmed' and 'unverified' are appropriately honest rather than filler.

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

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

No output schema, but the description covers the parent-placement semantics, the endpoint grammar, cap/lineType defaults, and points to the edit sibling for later changes; idempotencyKey retry semantics live in the schema. Return-value behavior is not described, but for a create tool that is a minor gap.

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

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

Schema coverage is 75%, and the description supplies the critical endpoint mini-language ("12:34", "12:34@right", "12:34@0.5,1", free point "120,340") plus the constraint that an end may not be another connector. Defaults for lineType and caps are repeated from the schema, so it adds real value but some redundancy.

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

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

States a specific verb+resource ('FigJam connector lines between nodes'), quantifies batch capacity (1–200 per call), and names the sibling figma_edit_connectors for the modify path. An agent can distinguish this from figma_create_line, figma_create_vector, and figma_edit_connectors without opening schemas.

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

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

Gives clear routing guidance: build connectors last (because reparented connectors keep stale elbows), and use figma_edit_connectors to change one later. It also flags the environment constraint (FigJam only, unverified). No explicit when-not-to-use statement, so it stops short of 5.

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

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

Annotations already cover readOnly/destructive/idempotent, so the bar is lower. The description adds real behavioral context beyond them: the style is 'local' (not a library style), it is mutable in place via figma_update_style, and the permission gate 'Editors: Design only' is a genuine prerequisite disclosure. It still says nothing about what is returned or duplicate-name behavior.

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

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

Four short, telegraphic sentences with no filler, and the resource identity leads. The fragmentary first sentence ('A local effect style ...') reads like a note rather than a definition, slightly weakening front-loading but not enough to waste space.

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

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

For a creation tool with a large nested effects schema, no output schema, and existing annotations, the description covers the key relationships and permission gate. It omits what the call returns (e.g. the style handle needed for figma_apply_style_to_node) and name-collision/error behavior, leaving a visible gap in an otherwise adequate definition.

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

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

Schema coverage is 60%, so the schema documents several params (session, description, idempotencyKey, and most effect fields). The description's 'Same effect entries as figma_set_effects' is a valuable cross-reference for the complex 16-item effects array, but it adds nothing for name/description/session and doesn't fully compensate for the uncovered remainder.

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

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

It names the concrete resource (a local effect style, for shadows and blurs) and distinguishes itself implicitly from the paint/text/grid style creators. It stops short of a clean verb-first statement, opening with a noun phrase rather than 'Creates...', but an agent can still identify the artifact unambiguously.

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

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

The description routes the agent downstream ('nodes can then follow via figma_apply_style_to_node') and to the mutator ('change it later in place with figma_update_style'), which is useful related-tool framing. It never states when to choose this over figma_create_paint_style / figma_create_text_style / figma_create_grid_style, so the usage guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds only the editor-support caveat ('unverified: FigJam, Slides'), which is genuinely useful context, but says nothing about where the node is placed by default, how x/y behave, or what happens when parentId is omitted. For a mutation tool, that leaves meaningful behavioral gaps.

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

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

The description is short and front-loaded with the ellipse/fill fact, so there is no wasted prose. However, its brevity stems from under-specification rather than disciplined editing — it is too small for a 10-parameter creation tool, so the concision is not fully earned.

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

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

Given 10 parameters, 30% schema coverage, nested objects, a mutation hint in the annotations, and no output schema, the description should do far more work than two fragments. It omits the required-parameter contract, positional defaults, parent placement, and any relationship to sibling shape creators, leaving the agent to reconstruct the call from the schema alone.

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

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

Schema description coverage is only 30% across 10 parameters, so the description carries a real burden — yet it mentions only 'optional fill'. It never notes that width and height are required, nor explains x/y coordinates, parentId, name, or how sizing interacts with the created node. The nested sizing object and idempotencyKey are documented in the schema, but the remaining parameters are left to the agent's inference.

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

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

The description is a bare noun phrase, 'An ellipse with an optional fill,' which essentially restates the tool name figma_create_ellipse and title 'Create ellipse'. It never supplies a verb or says the tool creates a node in a Figma file, and it does nothing to distinguish itself from the many sibling create_* tools (create_rectangle, create_polygon, create_star). The editor availability note is the only non-redundant content.

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

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

The 'Editors: Design; unverified: FigJam, Slides' clause gives a weak environment hint about where the tool is supported, but there is no guidance on when to use this tool versus figma_create_polygon, figma_create_star, or the composite figma_create_shapes_with_text. No prerequisites (e.g., a target page or parent frame) are stated.

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

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

Annotations already declare the mutation profile (readOnly=false, idempotent=true, destructive=false). The description adds real behavioral context beyond them: auto-layout hugging on unsized axes, sizing:fill inheriting parent column width, wrapping rowGap defaulting to gap, and content not clipped unless clipsContent is true. It is solid, though it does not cover return behavior 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.

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

Front-loaded with the core concept, then progressively details layout, sizing, wrapping, clipping, and naming. Dense but every sentence carries usable information; the editor-support clause is the least essential but still useful for scope-setting.

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

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

For a 20-parameter mutation tool with nested objects and no output schema, the description covers the dominant workflows and defaults (sizing, wrap, clipping, background). Gaps remain around validation/error behavior and how it interacts with downstream styling tools, but the essential calling context is present.

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

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

Schema coverage is high (85%), so the baseline is 3; the description earns above that by tying parameters together (layout/gap/padding/alignX/alignY for auto-layout, rowGap needing wrap and defaulting to gap, sizing:fill semantics). It adds cross-parameter meaning rather than merely restating individual field docs.

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

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

States a specific verb+resource (create a frame) and explains its role as the structural building block, with concrete composition guidance ('one frame per section, row or card'). It does not explicitly distinguish itself from close siblings like figma_create_rectangle, figma_create_section, or figma_create_from_spec, so an agent still has to infer the boundary.

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

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

Gives clear context for use: build designs step by step, add content via parentId, and a note that editors are Design with FigJam/Slides unverified. It stops short of explicit when-not-to-use guidance or naming the alternative creation tools for plain shapes or sections.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), but the description adds substantial non-structural behavior: unknown fields are 'refused, never dropped'; a mid-way failure does NOT roll back and reports created[]/failedAt; idempotencyKey is needed for safe retry on large specs; and editor support is scoped (Design verified; FigJam/Slides unverified). This is far beyond what annotations convey.

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

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

Dense but front-loaded: the capability statement comes first, then workflow, then grammar pointer, then the minimal shape, then failure/idempotency semantics, then editor scope. Every sentence carries operational value, though the grammar pointer plus inline example is slightly redundant.

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

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

For a complex single-call section builder with no output schema, this is complete: it gives the grammar source, a worked minimal example, the multi-call workflow, failure semantics, retry guidance, parent/page placement rules, and editor support. An agent could invoke it correctly without opening other docs.

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

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

Schema coverage is 100% and each of the 5 params has a schema description, so the baseline is 3. The description does add value by giving a minimal shape example, stating that an array of roots needs parentId or pageId, and explaining why idempotencyKey matters — but the core grammar is delegated to figma_get_guide rather than fully specified here.

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

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

States a specific verb+resource (build a whole section in one call) and enumerates exactly what it can produce — header, hero, card, grid, footer — plus the node types it supports. This clearly distinguishes it from the granular siblings like figma_create_frame, figma_create_text, figma_create_rectangle that build single nodes.

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

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

Explicit when-to-use workflow: 'a wrapper frame, then one call per section into it by parentId; after each, figma_check_layout and one figma_export_node, then targeted fixes.' It also states the alternative boundary — 'Not a whole page in one payload: a section at a time' — and points to figma_get_guide for the grammar, routing the agent precisely.

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

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

Annotations already cover the safety profile (readOnly=false, idempotent=true, destructive=false), so the bar is lower. The description adds a real constraint not present in annotations: 'Editors: Design only', plus the 'local' scope of the style. It does not cover naming collisions or what the call returns, keeping it short of a 5.

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

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

Three dense sentences, each earning its place: definition, consumption path, alternative, then the editor restriction. Information is front-loaded. The jargon-heavy, clause-packed style costs it a point on readability but not on economy.

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

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

For a creation tool with no output schema, the description covers what is made, how it is consumed, what differentiates it from the raw-grid sibling, and the permission requirement. Combined with annotations that carry the idempotent/non-destructive profile, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is only 60%, but the description compensates by giving a worked example for the complex 'grids' entries ('12 columns, 24 gutter, 64 margin') and cross-referencing figma_set_layout_grids for the entry format. The top-level name/grids carry no schema description, so this added context is genuinely valuable, though session/description/idempotencyKey rely on the schema alone.

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

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

States a specific verb and resource: creating a 'local GRID style — a named layout grid'. It reinforces this with a concrete example ('12 columns, 24 gutter, 64 margin') and explicitly distinguishes itself from the sibling figma_set_layout_grids, which 'sets raw grids on frames instead'. An agent can tell it apart from the other style-creation siblings without opening a schema.

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

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

Explains the downstream consumption path ('frames follow via figma_apply_style_to_node { type: "grid" }') and names the alternative tool (figma_set_layout_grids) with the condition that separates them (reusable style vs raw grids). It lacks an explicit 'use this when / not when' framing, but the context is clearly stated.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety and retry semantics are covered. The description adds real behavioral context beyond them: a library component is imported first and then placed, and editor support varies. It stops short of describing what the call returns or where the instance lands by default, but the added side-effect disclosure is meaningful.

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

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

Front-loaded with the core action and then layered with routing, the id-source rule, the exclusivity constraint, and platform support. Dense but every clause carries information; the only mild cost is that the exclusivity rule is buried mid-paragraph rather than stated up front.

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

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

For a 10-parameter mutation tool with no output schema and 80% schema coverage, the description covers the id-source workflow, the exclusivity constraint, the import side effect, and the sibling alternative. It does not say what the call returns (e.g. the new node id) or the default parent behavior, which are the remaining minor gaps given annotations already carry idempotency and safety.

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

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

Schema coverage is 80%, so the baseline is 3, but the description adds a constraint the schema does not encode: 'Give exactly one of componentId, componentKey, componentSetKey' (no oneOf in the schema). It also clarifies variant defaulting, which exceeds the schema's own description. That mutual-exclusivity rule is exactly the kind of semantics an agent cannot infer from structured fields.

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

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

States a specific verb (place) and resource (instance of a component/component set variant), enumerating the three modes of placement. It explicitly distinguishes itself from siblings figma_swap_component and figma_import_library_assets, so an agent can route correctly without opening a schema.

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

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

Explicit routing: local ids come from figma_get_local_components, library components are imported then placed, and the alternative for changing an existing instance is figma_swap_component. It also names the required version support (Design; unverified FigJam/Slides), which is genuine when-to-use guidance.

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

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

Annotations already declare this is a non-readOnly, non-destructive, idempotent creation tool. The description adds useful behavioral context beyond annotations: cap decorates both ends, a line keeps its length while a filled rectangle stretches, and editor compatibility is given.

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

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

The description is dense but front-loaded, with use cases first and geometry details following in a logical order. Every sentence earns its place, including the auto-layout alternative and editor support note.

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

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

For a create tool with no output schema and annotations covering safety and idempotency, the description gives enough to invoke the core line creation correctly. It is missing some placement and styling details, such as default parent behavior, but remains largely complete for the primary use case.

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

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

The description explains key geometry and appearance parameters such as length, angle, cap, and the x/y origin, which adds meaning beyond the schema. However, with 12 parameters and only 50% schema description coverage, several parameters such as parentId, name, color, weight, dashPattern, and idempotencyKey are not covered or only partially covered by the description.

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

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

States a specific verb and resource ('Create line') and immediately lists concrete use cases: dividers, connectors, arrows, underlines, decorative strokes. It also distinguishes the tool from figma_create_rectangle for auto-layout dividers, so an agent can tell it apart from siblings.

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

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

The description explains when to use a line versus a rectangle in auto-layout contexts, and notes editor support for Design, FigJam, and Slides. It provides clear usage context but does not explicitly exclude or compare against other nearby tools such as figma_create_connectors or figma_create_vector.

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

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

Annotations only cover mutability (readOnly=false, destructive=false, idempotent=true) and open/closed world; the description goes well beyond them by explaining the two preview outcomes (EMBED vs LINK_UNFURL and how each is determined), the pre-fetch parent validation, the refusal behavior, and the exact response shape. It also discloses the editor-mode restriction, which annotations cannot express.

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

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

Front-loaded with the core action, and every subsequent sentence carries distinct information (preview types, refusal behavior, return shape, editor scope). Slightly dense with parenthetical clauses, but there is no filler and nothing is repeated from the schema.

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

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

With no output schema, the description correctly supplies the return shape { id, type, title?, provider? }, and note that the tool mutates the document while saying nothing about the async/sync timing of the fetched preview — a minor gap for a tool that performs a network fetch. Overall it covers enough for correct invocation.

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

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

Schema description coverage is 100%, so every one of the six parameters (including the nuanced x/y defaults and the idempotencyKey retry contract) is already documented in the schema. The description only alludes to parentId indirectly ('the parent is checked'), adding no parameter-level detail beyond the schema — the baseline 3 for fully-covered schemas.

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

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

States a specific verb and resource — paste a web link onto a FigJam board as a card — and no sibling tool overlaps with that function, so an agent can pick it out of a list of ~100 node/style/variable tools instantly. It also distinguishes itself from generic node-creation by naming the artifact it produces (a preview card).

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

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

The closing sentence 'Editors: FigJam only, unverified' tells the agent the context in which the tool is valid, which is real routing information. It does not, however, name alternatives or contrast against a near-neighbour (e.g. importing an image or creating a code block), because none exists — so this is clear context without explicit exclusions.

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

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

Annotations already declare it as a non-readOnly, idempotent, non-destructive write, so the bar is lower; the description nonetheless adds real context: the 3-page cap on free Starter files, the fact that Figma's own error is surfaced verbatim, and the plan-vs-bridge error provenance. That failure-mode and environment disclosure goes beyond the structured data.

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

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

Very short, with no filler: the plan-cap warning, the error-provenance clarification, and the editor matrix each earn their place. The leading sentence fragment 'A new page.' is an awkward front-load but costs only a few words.

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

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

No output schema exists, but for a mutation tool whose annotations already carry the safety profile, the description covers the important ambient constraints (plan cap, error behavior, editor support). It omits whether/how the new page affects the current selection or file layout, which is a modest gap.

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

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

Schema coverage is 75%, with session, activate, and idempotencyKey all described in-schema, so the schema carries the parameter burden. The description adds no meaning about name (undocumented) or about how 'activate' interacts with the new page, so the baseline 3 fits.

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

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

The description opens with the fragment 'A new page.', which essentially restates the title 'Create page' rather than stating a verb + resource, and it never differentiates this from adjacent creation siblings like figma_create_slides or figma_create_section. The intent (create a page) is unambiguous once combined with the name/title, but the description itself contributes little.

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

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

The 'Editors: Design; unverified: FigJam, Slides' note gives implicit applicability guidance about where this call is safe, and the cap note tells you when it will fail. However, there is no when-to-use-vs-alternative guidance (e.g., use figma_get_pages to list, figma_navigate_page to switch) and no prerequisites stated beyond the plan cap.

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

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

Annotations already carry the safety profile (non-readOnly, idempotent, non-destructive, closed-world). The description adds constraints the annotations do not: 'Editors: Design only' and the behavioral consequence that a style has no size, so gradient `angle` is exact only on a square node. It stops short of describing return shape or duplicate-name behavior.

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

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

Front-loaded with the resource type, then dense but waste-free sentences covering binding, later editing, the gradient caveat and the editor restriction. Every sentence carries distinct information and nothing is padded.

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

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

For a 9-parameter tool with nested gradient objects and no output schema, the description covers the essential calling decisions plus key caveats and alternatives. Minor gaps remain (where the style lands, name-collision behavior), but nothing an agent strictly needs in order to call it correctly is missing.

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

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

Schema coverage is 78%, so the schema does much of the work, but the description adds real meaning beyond it: it explains that `variableId`/`variableName` binds the FIRST paint's colour to a COLOR variable (a behavioral link not visible in the schema), and it flags the `fills`/gradient-angle caveat. It does not add meaning for name, session, opacity or idempotencyKey.

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

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

The description nails the resource and type: 'A local PAINT style', which cleanly separates it from figma_create_text_style, figma_create_effect_style and figma_create_grid_style. The creation verb is implied rather than stated (it opens with a noun phrase, not 'Creates...'), so it falls just short of a 5.

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

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

It routes the agent explicitly to alternatives with conditions: use figma_update_style to change the style later in place, and use figma_set_fills (or pass `transform`) when an exact CSS angle on a known node is needed, because a style has no size. That is precise when-to-use / when-to-use-something-else guidance.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=false), so the description need not restate them. It adds useful editor-compatibility context that structured fields do not carry. However it says nothing about where the node lands (parentId/current page), what is returned, or what happens with an invalid parent, leaving gaps for a mutation tool.

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

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

Three dense fragments, no filler, and the core meaning (what shape, how the count maps, when to use it) comes first. The editor-compatibility note is placed last where it belongs. Nothing here could be cut without losing information.

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

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

For a 14-parameter mutation tool with no output schema and sub-half schema coverage, the description covers shape semantics and environment support but omits the return value, placement behavior (parentId vs current selection/page), and the practical role of idempotencyKey for retries. Annotations cover safety; the remaining operational gaps keep this at adequate rather than complete.

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

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

With only 43% schema description coverage across 14 parameters, the description is expected to compensate, and it partly does by mapping pointCount values to real shapes and pointing to figma_rotate_nodes for diamonds. But 13 of 14 parameters (fill, stroke, name, x/y, parentId, session, sizing, cornerRadius, strokeWeight) get no semantic help from the description; the schema carries the rest. Partial compensation only.

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

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

The description names the exact resource (a regular polygon) and enumerates concrete cases — triangle with pointCount 3, diamond with pointCount 4 plus figma_rotate_nodes — which is far more specific than the title 'Create polygon'. It implicitly separates the tool from sibling shape creators like figma_create_star, figma_create_ellipse and figma_create_rectangle, though it never names them. No explicit verb, but the intent (create a polygon node) is unmistakable.

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

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

Gives clear use-case context ('Badges, play buttons, decorative geometry') plus an environment note that it is supported in Design and unverified in FigJam/Slides, which is real selection guidance for editor choice. It also cross-references figma_rotate_nodes for the diamond case. What is missing is any when-not-to-use statement versus figma_create_vector or figma_create_star.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=false), so the bar is lower. The editor-compatibility note is genuine extra context not derivable from annotations, but the description says nothing about where the new node lands, permissions needed, or whether it fails outside Design — gaps for a creation tool.

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

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

Two short sentences with no filler, and the property summary is front-loaded ahead of the platform note. The first sentence is a noun fragment rather than a statement of action, which costs a little clarity but not length.

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

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

For a 13-parameter creation tool with no output schema and sparse schema descriptions, the description is far too thin: it does not say what is returned (e.g. the created node id), where the rectangle is placed by default, or how required width/height interact with x/y. The context an agent needs to call this correctly is largely missing.

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

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

Schema description coverage is only 31% across 13 parameters. The description names three (fill, corner radius, stroke), which roughly repeats schema names rather than explaining them, and is silent on x/y coordinate semantics, parentId, sizing, name defaults, and units — the areas where the schema provides no description at all.

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

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

The name supplies the verb (create) and the description supplies the resource's properties (fill, corner radius, stroke), so the intent is recoverable. But the description itself is a noun fragment with no verb or scope statement, and it does nothing to separate this from its many shape siblings (figma_create_ellipse, figma_create_frame, figma_create_shapes_with_text).

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

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

The only usage-adjacent content is 'Editors: Design; unverified: FigJam, Slides', which is platform availability, not when-to-use guidance. There is no statement of when to pick this over figma_create_frame, figma_create_from_spec, or figma_import_svg, and no prerequisites (e.g. must a parent/page be selected first).

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

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

Annotations already establish the safety profile (not read-only, idempotent, non-destructive), so the bar is lower. The description adds real behavioral context beyond them: platform verification status across Design/FigJam/Slides and the untitled-section behavior when `name` is empty.

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

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

The conceptual definition is front-loaded before the alternative and the editor caveat, and every sentence carries information. The 'white wrapper, zones inside it, cards inside those' clause is slightly verbose but earns its place by conveying FigJam structural nesting.

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

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

With 10 optional params at 90% schema coverage and no output schema, the description fills the important gaps: what a section is, how it nests, when to prefer create_from_spec, and platform support. An agent can call it correctly without more prose.

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

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

Schema coverage is 90%, so the baseline is 3. The description goes beyond it by explaining that `name: ""` deliberately leaves the section untitled when an inner title text carries the label, and by interpreting `parentId` as allowing another section (nesting), adding semantics the schema only hints at.

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

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

The description defines the resource concretely (a section as the container designers use to organise a page by flow, and on FigJam the structural wrapper) and clarifies the nesting model via `parentId` = another section. It clearly distinguishes itself from figma_create_from_spec, though it never explicitly contrasts with sibling creators like figma_create_frame.

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

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

It gives an explicit routing rule: to fill a section and fit it to content in one call, use figma_create_from_spec with `arrange` and `hug`. It also flags editor compatibility (Design confirmed; FigJam/Slides unverified), which helps an agent decide whether to attempt the call. No explicit 'when not to use' for the plain-section case, but the alternative is named.

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

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

Annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) already declare the mutation/idempotency profile, and the description does not contradict them. It adds useful behavior beyond them: the 1–200 batch limit, text auto-fitting unless width/height are supplied, and that a preset sets fill, stroke and text together. It stops short of describing the returned node ids an agent would need for downstream chaining.

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

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

Dense but front-loaded: the core action and batch limit lead, followed by shape/color semantics, then layout and alternatives. No filler sentences, though the single-paragraph block is heavy and would scan better with structure.

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

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

For an 8-parameter creation tool with no output schema and 88% schema coverage, the description plus schema covers shape, color, sizing, layout and alternatives thoroughly. The main omission is any mention of what the call returns (node ids) for chaining into figma_create_connectors.

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

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

Schema coverage is 88%, so baseline is 3, but the description adds real meaning the schema lacks: it enumerates the `color` presets and their light- variants (the schema only calls them 'a coordinated preset'), lists concrete `shape` types, and clarifies that `label` produces a fixed-size 1–2 character circle marker. This substantially improves interpretation over the raw schema descriptions.

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

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

States a specific verb+resource with scope: FigJam shapes with text, flowchart/decision/database/callout use cases, 1–200 per call. It actively distinguishes itself from siblings by naming figma_create_stickies (layout), figma_create_connectors (joining), and figma_create_table (tabular data, 'never a grid of shapes').

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

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

Explicit alternatives and exclusions: join shapes with figma_create_connectors, use figma_create_table for rows/columns rather than a grid of shapes, and note that editors are unverified in FigJam and Slides. This routes the agent to the correct sibling for adjacent tasks.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, closed-world, but the description adds what annotations cannot: slides are created empty, the background fill must live on the slide because rows/grid carry no fill, all positions are validated atomically before the first slide is created, and it notes the editor restriction ('Slides only, unverified').

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

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

Front-loaded with purpose and workflow, then item semantics, return shape, and alternatives — a logical order with no filler. It is dense and slightly run-on in the 'Per item:' passage, and one clause is restated from the schema, but every sentence carries information.

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

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

Despite no output schema, the description states what is returned (each slide's id, row, col and index as read back), and it covers permissions, atomic validation, workflow chaining and sibling alternatives. Nothing an agent needs to invoke this correctly is missing.

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

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

With 67% schema coverage, the description meaningfully compensates: it explains that `row`/`col` are counted against the grid left by earlier items in the same call, that omitting both appends to the end of the deck, and that on an empty deck the first slide creates row 0 — semantics the schema only hints at. It also disambiguates `skipped` and the hex `background` placement. Minor overlap with the schema's own wording on row-count behavior.

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

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

States a specific verb, resource, cardinality and dimension: 'Add 1–20 empty 1920×1080 slides to a Figma Slides deck, in list order.' It explicitly distinguishes itself from figma_create_frame, figma_move_slides and figma_set_slide_grid, so an agent can route correctly without opening any schema.

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

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

Gives the full intended workflow (create slides, then feed each via figma_create_from_spec with parentId = slide id, then verify with figma_check_layout at 3–5 slides per call) plus explicit exclusions and the sibling to use for each alternative case. It even states the anti-pattern to avoid ('Do not delete and rebuild slides to restyle a deck').

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the description does not need to restate safety. It adds genuine behavioral context beyond annotations: editor availability scoping (Design; unverified FigJam, Slides) and the validation rule that Figma refuses a grid layout on a slot. It stops short of describing return shape or failure behavior, so a 3 is appropriate given annotations carry the safety burden.

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

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

Front-loads purpose, then preconditions, cross-tool routing, and environment scope in a dense sequence where every sentence carries new information. No filler or restatement of the name.

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

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

For an 8-parameter mutation with a nested sizing object and no output schema, the description covers purpose, valid input shape, layout constraint, follow-up tools, and editor scope. It omits anything about default sizing/layout behavior or what the call returns, minor gaps rather than blocking ones.

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

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

Schema coverage is moderately high (75%), so the baseline is 3, but the description adds meaning beyond the schema: the layout constraint ('Figma refuses a grid on a slot') sharpens an enum the schema only labels 'Auto-layout direction', and the componentId constraint ('not a set') adds an input rule the schema does not state. Width, height, and sizing are left entirely to the schema.

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

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

States a specific verb and resource ('Add a slot to a component') and immediately defines what a slot actually is (a frame each instance fills with its own layers, plus the SLOT property). This is enough for an agent to tell it apart from sibling node-creation tools like figma_create_frame or figma_convert_to_component without opening a schema.

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

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

Gives explicit preconditions and exclusions: 'Pass a component or one variant, not a set', slot filling happens via parentId in an instance, figma_reset_slot empties it, and figma_set_instance_properties cannot set a slot. This is concrete 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.

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so safety/idempotency is covered structurally. The description adds a genuine behavioral trait not in the annotations: platform support (verified in Design, unverified in FigJam/Slides). It says nothing about what node is returned or how conflicts are handled beyond what idempotencyKey already documents in 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.

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

Three dense sentences, front-loaded with the shape semantics before use cases and platform notes. Every clause carries information; no filler or repetition of the tool name.

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

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

For a 15-parameter mutation tool with no output schema and an openEnded nested sizing object, the description covers purpose, key geometry params, and editor constraints but leaves most parameters and the return shape undocumented. Adequate minimum viable context, with visible gaps.

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

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

Schema coverage is only 47% across 15 parameters, so the description would need to compensate more. It does add real interpretation for innerRadius (low = spiky, near 1 = polygon) and pointCount (spikes), which goes beyond the terse schema defaults, but x, y, fill, stroke, name, parentId, cornerRadius, strokeWeight, and sizing get no descriptive support.

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

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

The description states the resource precisely ('a star or burst') and defines its two defining parameters (pointCount spikes, innerRadius 0–1), which implicitly separates it from the sibling figma_create_polygon ('near 1 = almost a polygon'). The verb is carried only by the name/title, so it is clear but not fully self-contained.

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

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

It supplies concrete use cases (rating stars, sale bursts, sparkles, decorative shapes) and an editor-compatibility caveat ('Editors: Design; unverified: FigJam, Slides'), which tells the agent when this tool is applicable. It does not name an explicit alternative for regular polygons, so it stops short of full routing guidance.

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

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

Annotations already cover safety (idempotent, non-destructive), but the description adds substantial extra behavior: Rows are laid out after text is measured so they never overlap, the parent is never resized and `parentOverflow` reports the overrun (routing to figma_fit_sections), and the editor/verification limitation is disclosed. These are non-obvious consequences an agent would otherwise discover only by testing.

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

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

Dense but front-loaded: count range and grid layout come first, then sizing, color, layout knobs, overflow, and return shape. Most sentences carry unique facts, though the run-on construction around sizing and `wide` could be tightened without losing information.

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

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

No output schema exists, yet the description documents the return payload (created [{ index, id, x, y, width, height }] and bounds), which is exactly the gap that would otherwise be missing. Combined with editor constraints, overflow signaling, and layout rules, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 88%, so the schema already documents most parameters and the baseline would be 3. The description still adds value: it clarifies that stickies are fixed-size (no width/height), that color names resolve to FigJam's exact swatches, and that `columns`/`gap` interact with the auto-measured layout rather than raw coordinates.

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

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

States a specific verb and resource (create FigJam sticky notes) plus the batch scope (1–200 per call). It actively distinguishes itself from siblings like figma_create_text by asserting 'Prompts, labels and instructions are text, not stickies,' so an agent can route without opening schemas.

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

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

Gives real selection guidance: use `wide` for about 100 words or more, and the note that prose belongs in text tools implicitly routes to figma_create_text. Also flags the 'Editors: FigJam only, unverified' constraint. It stops short of naming an explicit alternative tool or stating when not to use it at all.

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

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

Annotations declare idempotentHint=true and destructiveHint=false, but the description adds context annotations cannot: 'One undo step' (reversibility), editor support ('Design; unverified: FigJam, Slides'), and the shape of the returned diagnostics (panels starting off the beat, copy too brief to read). This is rich behavioral disclosure beyond the structured hints.

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

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

Dense but front-loaded, leading with the artifact and workflow before edge notes. It is a single long paragraph that packs a lot of distinct facts (cards, captions, timing, diagnostics, alternatives, skill, undo), which earns its length but is slightly heavy to parse in one block.

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

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

With no output schema, the description still tells the agent what comes back (offBeat and readTime lists, styleframeId, snapped changes) and how to retry via idempotencyKey. For a 16-parameter write tool with 88% schema coverage, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 88%, so the schema already carries most parameter meaning and the baseline is 3. The description still adds value by explaining timing derivation: durations are snapped to frames, bar.beat derived from bpm/fps, and the duration caption doubles as the retime control. It stops short of covering every parameter but clearly exceeds the schema-only baseline.

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

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

States a specific verb and resource ('Lay out a motion piece's storyboard') and immediately describes the concrete artifact: a board of cards in rows, one per panel, with thumbnails and caption rows. It distinguishes itself from close siblings by naming figma_set_keyframes and figma_create_animatic's domain (animation vs. planning), so an agent can tell it apart without opening a schema.

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

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

Explicit when-to-use and when-not: 'A plan, not an animation: figma_set_keyframes animates.' It also routes to figma_create_from_spec for sketching thumbnails and figma_get_guide for the storyboard skill, and warns to fix offBeat/readTime before building.

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

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

Annotations already cover readOnly=false, idempotent=true, destructive=false, so the bar is lower, yet the description adds real behavior: fills are never removed ("" is refused), columns cannot shrink below their minimum so actual widths come back, and editors are unverified in FigJam/Slides. These are non-obvious constraints the agent needs, though permission/auth and return-shape behavior are not covered.

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

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

Front-loaded with the identification claim and the input-form rule, and every clause carries substance. It is dense and reads as one long run-on stream rather than a structured list, which slightly impairs scanning but wastes little.

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

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

For a 17-parameter tool with no output schema, the description supplies validation rules, defaults, form exclusivity, and the edit handoff, which is substantial. It leaves positioning, naming, parenting, and session parameters to the schema, which is acceptable given 82% coverage.

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

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

With 82% schema coverage the baseline is 3, but the description goes further than the schema by enumerating the header-color preset family (black, dark-gray, …, light-green) and explaining defaults and the rows-vs-numRows exclusivity. It adds genuine meaning for rows, header, fill, and sizing beyond the structured field text.

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

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

The description names the resource precisely ("A FigJam table") and pins its scope with "the tool for any row-and-column data, never a grid of shapes," which distinguishes it from shape-based siblings like figma_create_shapes_with_text. Combined with the create verb in the name/title, an agent can identify exactly what this produces.

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

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

It supplies an explicit when-not ("never a grid of shapes"), defines the two mutually exclusive input forms ("exactly one form"), and routes cell edits to figma_edit_table after creation. It stops short of naming all competing creation siblings, but the selection logic is clear.

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

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

Annotations already declare readOnly=false, idempotent=true and destructive=false, so the safety profile is covered. On top of that the description discloses non-obvious behavior: the font fallback chain, a `fellBack: true` flag in the result, overflow behavior for unwrapped text, and editor support ('Design; unverified: FigJam, Slides'). That is meaningful added 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.

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

Three dense sentences that are front-loaded with the placement rule and each carry distinct information. It is on the longer side but virtually every clause earns its place (layout, wrapping, font fallback, editor coverage).

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

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

For a 16-parameter mutation tool with no output schema and nested objects, the description covers the interlocking layout/sizing behaviors and even describes the returned font/`fellBack` signal. Remaining gaps (defaults for many parameters) are handled by the schema's own descriptions, so it is close to complete.

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

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

Schema coverage is 75%, so the schema carries most of the burden, but the description adds semantics for the trickiest parameters: how `parentId` places the node, how `align` is inherited from the parent column, how `width` triggers wrapping, and how the font is resolved. This goes beyond restating the schema.

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

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

The description makes clear it produces a text node and how it is placed ('placed into a frame by `parentId`'), which is a specific resource plus behavior. It stops short of differentiating itself from near siblings such as figma_create_shapes_with_text or figma_set_text, so the agent must infer which to pick.

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

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

It gives real usage context for the layout parameters — 'Inside a vertical auto-layout it fills the column', 'elsewhere give `width` for text that should wrap' — which tells an agent how to obtain the desired result. However, there is no when-to-use-this-tool-vs-alternatives guidance relative to the many text-related siblings, so routing is only implied.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, so the safety profile is covered. Beyond that, the description discloses real behavioral traits: the style is 'local' (not a shared/published library style), only Design editors can run it, and lineHeight/letterSpacing now reject bare JSON numbers — a concrete failure mode an agent would otherwise hit. It stays silent on collision behavior when a style of the same name already exists.

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

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

The opening fragment 'A local TEXT style.' is not front-loaded with the action the tool performs, and the middle sentences are a dense em-dash run-on mixing formatting rules with option names. Content is relevant but not prioritized: the string-vs-number trap deserves the lead position rather than following an incomplete noun phrase. Mid-weight and functional but not tight.

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

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

For a 13-parameter create tool with no output schema and 77% schema coverage, the description covers the formatting param traps, the update path and the editor restriction reasonably well. The notable gap is the return value: since no output schema exists and the style must subsequently be applied via figma_apply_style_to_node, the agent is never told that an id/handle comes back to chain with. The idempotency key's retry semantics are left entirely to the schema.

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

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

Schema coverage is 77%, near the high band, so the schema already carries most parameter meaning — including the 'A string, not a number' warnings for lineHeight and letterSpacing that the description largely restates. The description adds a cross-reference to figma_set_text_properties and a use-case example ('upper for labels') but no new syntax or constraint information. Baseline 3 is appropriate for near-high coverage.

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

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

The text establishes a specific resource (a local TEXT style) and the title supplies the create verb; the phrase 'A local TEXT style.' alone is elliptical but unambiguous in combination. It distinguishes itself from siblings by pointing at figma_update_style for later in-place changes, separating create from update. It does not contrast with figma_create_paint_style, figma_create_effect_style or figma_create_grid_style, which are the nearest siblings.

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

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

'Change it later in place with figma_update_style' names one alternative and the condition selecting it, and 'Editors: Design only' states an environment restriction. However, there is no guidance on when to define a reusable style versus applying formatting directly via figma_set_text_properties, nor on when to publish to a library versus staying local. Usage is implied rather than explicit for the main create-vs-set decision.

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

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

Annotations declare the mutation/idempotency profile, and the description goes beyond them: duplicate names are refused, scopes are validated against the type with ALL_SCOPES standing alone, empty scopes hides a primitive, and mode manipulation requires a paid plan. These are runtime behaviors an agent cannot infer from readOnlyHint/idempotentHint.

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

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

Front-loaded with the core action and value encoding, then alternatives and constraints. Dense but every clause carries load. The single-block packing of value formats, scopes, aliasing, and editor support makes it slightly heavy to scan compared to cleanly separated lines.

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

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

For an 11-param mutation with nested objects and no output schema, the description covers the high-risk semantics (duplicate refusal, type/scope validation, alias format, plan gating). It stops short of describing what is returned on success, but with no output schema that gap is minor and largely covered by the idempotencyKey retry contract.

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

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

Schema coverage is 64% and the description fills key gaps: per-type string encoding for `value`, the 'alias:<name or id>' reference syntax, and intended usage of `scopes` with concrete examples (["FRAME_FILL","SHAPE_FILL"], ["GAP"]). It adds meaning beyond the schema, though it does not touch modeId, idempotencyKey, or session, which the schema already documents.

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

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

Opens with a precise verb+resource framing ('One design token') and immediately delimits the scope: creates exactly one variable. It names the batch sibling figma_create_variables and the binding sibling figma_bind_variable_to_node, so an agent can separate it from near-neighbors without reading either schema.

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

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

Explicit routing rules: 'For a whole token set in one call use figma_create_variables', 'Bind one to nodes with figma_bind_variable_to_node', and the paid-plan constraint for 'extra modes (figma_add_variable_mode)'. It also states editor coverage (Design verified; FigJam/Slides unverified), which is actionable context for when this call is valid.

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

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

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=true), yet the description adds genuinely non-derivable behavior: the first mode is named after modes[0] or "Default" and never Figma's "Mode 1," extra modes are paid-plan gated, and a refused mode surfaces as a `warnings` entry rather than a silent drop. With no output schema, disclosing that warnings channel is especially valuable for an agent interpreting results.

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

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

Roughly four dense sentences, all carrying usable facts, with the resource named up front. The em-dash asides and the "Mode 1" trivia are slightly conversational but earn their place by preventing a real naming mistake; the missing leading verb is the only structural blemish.

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

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

For a create tool with no output schema, the description covers naming behavior, plan limits, failure signaling, follow-up editing, and environment support. It only partially addresses what a successful result looks like (it references "the result" and `warnings` but never says a collection is returned/identified), which is a minor gap.

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

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

Schema coverage is 75%, so the schema already carries most parameter meaning (notably the idempotencyKey retry semantics). The description adds real interpretation of `modes` beyond its schema text — the default naming rule and the "Mode 1" pitfall — though it says nothing extra about `session` or `idempotencyKey`.

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

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

The opening identifies the artifact created — "A new variable collection" — and glosses it helpfully as "a token group," so an agent knows this is a creation tool for a Figma variable collection rather than a variable itself. It does not open with an explicit verb ("Creates"), and it only loosely distinguishes itself from siblings by pointing to figma_update_variable_collection.

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

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

It routes the agent for follow-up work ("Rename or remove modes later with figma_update_variable_collection") and states environment scope ("Editors: Design; unverified: FigJam, Slides"). There is no explicit when-not or prerequisite statement, but the alternative and the plan constraint are named.

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

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

Annotations cover readOnly=false, idempotent=true and destructive=false, but the description adds substantially more: atomic validation ('Everything is checked before the first variable exists, so a refusal creates nothing'), the 200-per-call cap with pacing, alias ordering/type constraints, and editor availability (Design verified; FigJam/Slides unverified). No contradiction with the idempotency annotation.

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

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

Front-loaded with the core operation and then proceeds through values, atomicity, ifExists, limits, sibling routing and editor support in one dense but waste-free passage. Every sentence carries information an agent needs; nothing is padding.

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

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

Covers atomicity, failure semantics, ordering constraints, rate/limit behavior and idempotency-key retry semantics, which is thorough for a 5-param mutation with no output schema. The only real gap is that it never says what a successful call returns (e.g. created variable ids) that follow-up alias or bind calls would need.

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

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

Schema coverage is already 80%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot: alias targets must exist already or appear EARLIER in the same call with the same type, and ifExists governs what an existing name does. Value string formats largely restate the schema, hence not a 5.

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

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

States a specific verb and resource with scope: 'A token set in ONE call (one undo step)' that creates primitives then aliasing semantic tokens. It explicitly distinguishes itself from the sibling figma_create_variable ('For one variable figma_create_variable is enough'), so an agent can route correctly without opening either schema.

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

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

Names the alternatives and the conditions selecting them: use figma_create_variable for a single variable, figma_set_variable_properties to change properties later. It also spells out the ifExists decision (error/skip/update) and the ordering rule for aliases, which is exactly the guidance needed before calling.

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

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

Annotations already declare the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false). The description adds editor-compatibility context (Design verified; FigJam/Slides unverified), which is genuinely behavioral and not in the annotations. It does not, however, describe placement/parenting behavior or what happens with the created node beyond creation.

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

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

It is front-loaded with the core purpose, then progressively adds parameter guidance, the alternative tool, and editor support. Every sentence carries distinct, non-redundant information with no filler.

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

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

There is no output schema, and the description never claims to explain return values, which is appropriate. For a 13-parameter mutation tool with only 31% schema coverage it still leaves positioning/parenting and sizing semantics unexplained, but it covers purpose, key parameters, alternative routing, and editor scope well enough to call the tool correctly in the common case.

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

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

Schema coverage is only 31%, so the description is expected to compensate. It does add real meaning for `path` (SVG `d` syntax and the allowed command letters), `width`/`height` scaling with aspect-ratio preservation, and stroke/fill interaction. But with 13 parameters, several (x, y, name, sizing, session, parentId, strokeWeight) get no semantic help, leaving the coverage gap only partially filled.

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

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

The description states a precise verb+resource - drawing an arbitrary shape from SVG path data - and illustrates it with concrete use cases (blob, wave divider, arrow, logo mark, chart line). It explicitly differentiates from the sibling figma_import_svg, so an agent can pick between the two without opening either schema.

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

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

It gives an explicit alternative with the condition that selects it: 'For a whole SVG file (an icon) use figma_import_svg.' It also states a usage rule for stroke-vs-fill ('Give `stroke` without `fill` for an open line') and notes which editors are verified vs unverified, so both the routing and the applicability are covered.

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

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

Annotations declare destructiveHint and idempotentHint, but the description adds the crucial blast radius that annotations cannot: every instance loses the property, overrides included. That is exactly the kind of context an agent needs before a destructive call, plus per-type eligibility and editor-support caveats.

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

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

Three compact sentences, zero filler: the effect, the exception, and the alternative tool, followed by the editor-support note. The destructive consequence is front-loaded rather than buried.

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

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

For a destructive, no-output-schema tool with four params fully documented in the schema, the description covers what remains: destructiveness scope, which property types are legal, the VARIANT exception, the alternate tool, and platform support. Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantic value beyond the schema: it names the four valid property types and clarifies that VARIANT is rejected, and it explains the relationship between a component and its component set that the schema only hints at. It does not add format details for the property key, but the schema already does.

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

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

States a specific verb (Delete) and resource (component property), enumerates the exact deletable property types (TEXT, BOOLEAN, INSTANCE_SWAP, SLOT), and explicitly carves out the exception (VARIANT) that an agent would reasonably assume was deletable. It also names the sibling figma_edit_component_property for the adjacent operation.

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

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

Gives a clear when-to-use (delete a property), a when-not with a named alternative (VARIANT cannot be deleted, rename variants instead), and routes to figma_edit_component_property for rename/rewire. Also states editor support (Design verified; FigJam and Slides unverified), which is a usage constraint.

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

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

Goes well beyond the destructive/idempotent annotations: partial-failure semantics ('one node failing does not fail the call'), the Ctrl+Z revert behavior, the slide-row refusal rule, and the emptiedRows side effect. This is exactly the operational context annotations cannot convey.

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

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

Front-loads the core action and usage before edge cases and return format. Every sentence carries distinct operational value with no filler.

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

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

With no output schema, the description supplies the return shape (items: [{ id, ok, error? }]) and per-item failure behavior. Combined with the destructive annotation and slide edge cases, an agent has everything needed to call it correctly.

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

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

Coverage is 67% with session and idempotencyKey already documented in schema. The description compensates for the undocumented nodeIds by explaining its expected source ('the ids the create call returned'), adding real meaning beyond the bare array type.

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

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

States a specific verb and resource ('Delete nodes by id') and distinguishes itself functionally from the similarly-named figma_undo_step by framing itself as 'the correct way to undo agent work.' An agent can tell what it does and why it would choose it over a generic undo.

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

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

Gives explicit when-to-use context ('pass the ids the create call returned') and a concrete precondition (delete slides before deleting a slide row that still holds slides). It stops short of naming the alternative figma_undo_step or stating when NOT to use deletion, so it is clear but not a full comparison.

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

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

Adds real behavior beyond annotations: dependent nodes 'keep the values it gave them' (the actual consequence of destruction), per-item partial-failure semantics ('one node failing does not fail the call'), and editor scope. This is substantive context that annotations alone (destructive/idempotent hints) cannot convey.

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

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

Punchy and front-loaded with verb+resource first, then dependency effect, id source, return shape, and editor scope. Every sentence carries distinct information with no filler.

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

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

Despite no output schema, the description documents the return shape (items array with id/ok/error), partial-failure behavior, the side effect on dependent nodes, and editor availability. Nothing essential for a correct call is missing.

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

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

Schema coverage is 67% and the schema already documents idempotencyKey richly; the description reinforces styleIds ('by id') and its source. It does not mention the session parameter, so it only partially compensates for the coverage gap — baseline 3 is appropriate.

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

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

Names a specific verb (delete) and resource (local styles: paint, text, effect, grid) with the keying method (by id). It clearly distinguishes itself from siblings like figma_update_style and figma_create_*_style.

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

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

Provides a prerequisite pointer ('figma_get_styles lists ids') and editor availability ('Editors: Design; unverified: FigJam, Slides'), which tells the agent where the tool works. It lacks an explicit when-not-to-use or a named destructive alternative, 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.

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

Adds real behavior beyond the annotations: bound nodes retain their last resolved value, results are per-item with a partial-failure contract ('one node failing does not fail the call'), and editor support is qualified. Annotations only flag destructive/idempotent; the description explains the actual blast radius and failure semantics.

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

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

Five short sentences, front-loaded with purpose, then side effects, id sourcing, return contract, and environment scope. Each sentence carries distinct information with no repetition of the name or annotations.

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

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

With no output schema, the description supplies the return shape (`items: [{ id, ok, error? }]`) and partial-failure behavior, plus the critical side effect on bound nodes. Nothing an agent needs to call this destructive tool safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description still adds value: it establishes that deletion is keyed by id and names the tool that produces those ids, tying variableIds to a concrete source. The idempotencyKey's retry semantics are left to the schema, which already documents them thoroughly.

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

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

States a specific verb and resource ('Delete variables (design tokens) by id'), and the parenthetical disambiguates variables from other deletable Figma objects such as styles or variable collections. An agent can tell it apart from siblings like figma_delete_variable_collection without opening a schema.

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

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

Gives clear operational context by pointing at figma_get_variable_defs as the way to obtain valid ids, and states the editor scope where the call is supported. It stops short of explicit when-not guidance (e.g., collections belong to figma_delete_variable_collection), so it is not a full 5.

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