Figxel

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

Annotations already mark it non-read-only, idempotent, non-destructive, and closed-world. The description adds valuable behavior beyond that: it returns a property key (name + #id) usable by figma_set_instance_properties, re-calling with an existing name/type reuses the property and reports reused: true, and it lists editor support. This is rich context not derivable from annotations.

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

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

The description is dense but front-loaded: it defines the core action, then explains each type and key behaviors in compact clauses. Every sentence carries actionable information, including reuse behavior and sibling routing, 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, but the description explains the return value (the property key and that plain names also work). It covers all nine parameters implicitly through type-specific guidance and explicitly mentions editors and sibling alternatives, leaving no material gaps 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 coverage is high (89%), so the baseline would be 3. The description adds type-specific semantics beyond the schema: TEXT uses bindNodeIds to wire text layers, BOOLEAN shows/hides bound layers, INSTANCE_SWAP default is a component id, and VARIANT is only on sets. This clarifies parameter behavior across types, though some schema descriptions already cover the per-parameter mechanics.

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

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

The description opens with a specific verb and resource ('Give a component (or component set) a property that instances can change') and then enumerates the four property types. It explicitly distinguishes itself from sibling tools like figma_edit_component_property, figma_set_instance_properties, and figma_create_slot.

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 clear conditions: VARIANT is 'on a set only', bindNodeIds wires text layers, and reuse happens when the name/type already exist. It also routes rename/re-default/unwire actions to figma_edit_component_property and slot creation to figma_create_slot, with editor availability noted.

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 annotations: discloses that the call returns a modeId, that Figma refuses extra modes on a Starter file and returns its own message, and that Design is verified while FigJam and Slides are unverified. The fail-mode and output-value context is exactly what a mutation tool needs on top of destructiveHint=false and idempotentHint=true.

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 with the core action and return value front-loaded, then the plan gating, then the follow-up tool and editor support. The telegraphic final clause ("Editors: Design; unverified: FigJam, Slides.") trades readability for brevity but still earns its place.

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

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

With no output schema, the description correctly states the return value, and it covers the paid-plan failure path for a 5-parameter mutation. Only the optional parameters' behavior (retry key, session disambiguation, overwrite semantics) is left entirely to the schema, which is acceptable given partial 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?

The description maps collectionId ("to a variable collection") and name (the mode name, e.g. "Dark"), adding modest meaning, but says nothing about force, session, or idempotencyKey even though only 60% of parameters carry schema descriptions. The typed hints in the schema still cover those, so the description neither fully compensates nor needs to.

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 mode ... to a variable collection") and names the return value (modeId), so the agent knows exactly what effect to expect. It is clearly distinguishable from adjacent tools like figma_create_variable_collection and figma_set_variable_value.

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

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

Gives a clear when: adding a mode to a collection, plus the sequencing hint to follow up with figma_set_variable_value per mode, and warns that non-first modes require a paid plan. It does not explicitly name alternatives for renaming/updating an existing mode (e.g. figma_set_variable_mode or figma_update_variable_collection), so routing is implied rather than 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 non-read-only, idempotent, non-destructive, but the description adds what the annotations cannot: per-item partial-failure semantics (`{ updated, items: [{ id, ok, error? }] }`, one node failing does not fail the call) and platform support scope (Design verified; FigJam/Slides unverified). This is exactly the extra context the bar asks for.

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 routing, then return shape, then platform scope — no filler sentences. It is dense and semicolon-packed for a 7-parameter tool, which slightly slows parsing but every clause 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?

No output schema exists, yet the description spells out the return shape and partial-failure behaviour, and it covers platform reach and the id-vs-name sourcing. An agent has everything needed to call this mutation correctly without opening other tools.

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 86%, so the baseline is 3, but the description adds real meaning: the `type`-vs-name interaction, the default-to-fill behaviour of paint styles, and where a valid `styleId` originates for library styles. The STALE/`force` semantics live in the schema, so the description doesn't repeat them.

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 (apply) and resource (local style: paint, text, effect, grid) plus the resulting behavior ('the node then follows the style'). It is also clearly distinguishable from sibling figma_set_fills, which it explicitly reserves for raw colour.

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 routing rules: use styleName when convenient, supply `type` when a name is shared across kinds or to apply a paint style as a stroke (default fill), get local styles from figma_get_styles, and use the `id` from figma_get_design_context's `stylesUsed` for library styles. It names the alternative (figma_set_fills) and the condition that selects it.

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

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

Adds substantial behavior beyond annotations: steps run in order, stop at first failure without rollback, partial.steps and partial.failedAt report what was applied, one Ctrl+Z undoes the batch, success returns { steps, completed, itemsFailed? }, and per-node failures are listed in itemsFailed. It also discloses validation against each target tool's parameters and the keyframe motion gate.

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 definition is front-loaded with the core value proposition and then supplies dense operational detail. It is longer than typical, but most sentences add distinct, useful information about batching, failure behavior, undo, and validation.

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 batch mutation tool with no output schema, the description covers purpose, exclusions, failure semantics, success shape, undo behavior, and validation. It does not elaborate on `force`, `session`, or `idempotencyKey`, but those are fully documented in 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 100%, so the schema already documents all four parameters. The description nevertheless adds meaningful semantics for `steps`: it is a JSON array of op/params objects, tool names omit the figma_ prefix, batch size is 1–50, each step is validated against its target tool, and keyframe steps obey the motion gate. Other parameters are left 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, resource, and scope: several edits in one call and one undo step, covering fills, strokes, radius, effects, auto-layout, sizes, text, constraints, and names. It clearly distinguishes itself from create, delete, group/boolean/flatten/clone operations, so an agent can tell exactly what it is for.

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 describes when to use it (polish pass / batch modifications) and what it excludes: no creates, no deletes, no node-replacing operations. It names figma_create_from_spec as the alternative for builds, but does not explicitly compare batch usage against calling individual setter tools.

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

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

Beyond the annotations, the description discloses the partial-failure contract ('one node failing does not fail the call') and the exact return shape, plus editor support (Design verified; FigJam/Slides unverified). These are behavioral facts the schema and 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?

Three compact sentences: operation, scope controls, return contract, then platform caveat. The core verb leads and every sentence carries distinct information with no 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?

For a 9-parameter mutation with no output schema, the description still supplies the result envelope and partial-failure semantics, and the schema covers the remaining parameter detail. Nothing an agent needs to invoke 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 description coverage is 89%, so the schema already documents scope, regex, types, force and idempotencyKey in detail. The description only restates scope/filter/regex at a high level and adds no syntax or format detail beyond the schema, so 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?

The description states a specific verb and resource ('Bulk rename by find/replace over names') plus its scope controls, and the word 'Bulk' implicitly separates it from the single-node sibling figma_rename_node. An agent can identify the operation 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?

It gives a concrete motivating use case ('turning `Frame 12` into `Card / 12`') and makes clear this is for many nodes rather than one. It does not explicitly name figma_rename_node or figma_find_replace_text as the alternatives for single-node or text-content renaming, so the routing guidance is implied rather than 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 cover idempotency and non-destructiveness, and the description adds meaningful behavior beyond them: gradients/images are refused (not replaced), text fields may be refused per item, and the call returns per-item results so one failure doesn't fail the batch. It does not restate the safety profile, adding real context.

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

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

Front-loaded with the core action and otherwise dense with useful detail, but the single semicolon-chained sentence is run-on and harder to parse than a structured list of field categories would be. Information earns its place, but the structure is not optimal.

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 documenting the return shape `{ updated, items: [{ id, ok, error? }] }` and per-item failure behavior. Editor support (Design vs unverified FigJam/Slides) is also noted, leaving little an agent needs 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 significantly enriches `field` with a full enumeration of bindable properties and explains how `index` selects the paint/effect/grid and that paints must be SOLID. This adds value beyond the schema's example-only field 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 (bind) and resource (variable/design token to a node property), plus the consequence ('so it follows the variable'). This clearly positions it against siblings like figma_set_fills or figma_set_opacity, which set a value rather than bind 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?

Routes the agent to figma_get_variable_defs for library variable ids and to figma_update_style for tokens inside a style, which is explicit alternative guidance. It lacks a crisp 'when not to use this vs setting a raw value' exclusion, but the routing cues are strong.

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 safe-ish mutation profile (destructiveHint=false, idempotentHint=true), and the description adds real value beyond them: the result inherits the lowest node's position, its id is returned, and editor support is qualified (Design verified; FigJam and Slides unverified). It stops short of saying that the source shapes are consumed by the merge, which is the main behavioral detail an agent still has to infer.

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 dense sentences, front-loaded with the action and operation semantics before preconditions, use cases, and compatibility. No filler and no restatement of the title.

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 6-parameter mutating tool with no output schema, the description covers operation meaning, precondition, resulting node position, returned id, and editor support — enough to invoke correctly. What is missing is the fate of the original nodes and any failure modes beyond the parent requirement, which the schema's force parameter only partially covers.

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 description adds semantics the schema itself does not carry — that stacking order, not list order, determines union/subtract outcomes. The remaining undocumented parameters (name, session) are not explained in the description, which is a modest gap rather than a blocker.

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 then defines all four operations inline, including the non-obvious subtract semantics ('cut the upper shapes out of the BOTTOM one'). An agent can distinguish this from figma_flatten_nodes, figma_group_nodes, and figma_set_mask 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 concrete use cases ('icons, badges, cut-out shapes and logos') and a hard precondition ('shapes must share a parent'), plus editor availability. It does not explicitly name alternatives such as flatten or group, which keeps it from a 5, but the usage context is clear enough to select the tool confidently.

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/non-destructive, so the bar is lower, yet the description still adds value: default scope (selection, then page, focused slide in Slides), the `ok: true` success signal, that every finding carries a number and a fix, and the effect of `audit` passes. It does not describe how truncated results are signalled when `limit`/`maxNodes` are hit, which is the main remaining 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?

It is compact and the when-to-run clause is front-loaded, but the body is a single telegraphed run-on of semicolon-delimited jargon ("a fill child in a hug parent", "board (FigJam)", "tells") that is hard to parse on first read. Important scope defaults are buried at the tail end rather than placed where an agent will scan for them.

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-parameter QA tool with no output schema and no required parameters, the description covers the essentials: what is checked, what the audit passes add, how the target and brief are resolved, and what `ok` means. Only the shape of the findings payload and truncation behaviour are left implicit.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters, and the description largely restates the audit pass list and brief defaults. The one genuinely additive point is the brief-precedence rule (a node that is another brief's work wins over the default brief); otherwise it adds little beyond the 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?

The description establishes a specific verb (check) and resource (per-node layout findings) and explicitly distinguishes itself from figma_export_node ("shows the picture"), naming concrete defect classes such as overflow, clipping, contrast and zero-size nodes. The framing "a designer's last look, in numbers" is metaphorical rather than literal, but the enumerated defect list leaves no doubt about what the tool 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?

"After each section and before calling anything done" gives an explicit trigger point, and the parenthetical routing to figma_export_node separates it from the visual-inspection sibling. It stops short of stating when this tool should not be used or that it never repairs findings, although "Reads only" implies the latter.

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 declare non-readonly, idempotent, non-destructive behavior, but the description adds real context beyond them: subtree duplication, slide row placement, the returned row/col, and editor support boundaries. It does not cover permissions or failure modes beyond what force already handles.

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 dense sentences with the core action front-loaded and the slide-specific caveat following. Every clause carries information, though the slide sentence is syntactically dense enough to require rereading.

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 no output schema, the description covers the non-obvious pieces: subtree scope, parent/position behavior, slide row semantics, return of row/col, and editor availability. The unexplained name and y parameters are the only notable gaps.

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

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

Schema description coverage is 63%, and the description clarifies the tricky cases: x is ignored for slides because the deck grid places them, and parentId takes a SLIDE_ROW for slides. However, name, y, and nodeId remain unexplained in both schema and description, so it only partially compensates for the gap.

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

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

The description opens with a specific verb and scope: duplicate a node with its whole subtree, optionally into another parent or position. That clearly separates it from creation tools like figma_create_instance or manipulation tools like figma_reparent_nodes, though no sibling is named explicitly.

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 hints at when this applies (slide duplication into a slide row, editor availability in Design vs unverified FigJam/Slides) but never states when to prefer it over figma_reparent_nodes or figma_create_instance. Usage is implied rather than prescribed.

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, non-destructive, idempotent, closed-world, so the description's added value is the editor support note ('Design; unverified: Slides'), the shared-parent constraint, the default layout behavior, and the fact that grid mode returns page coordinates for external header labels. It stops short of describing failure modes (e.g. what happens if parents differ) or the return shape outside grid mode.

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 purpose and the naming prerequisite are front-loaded, and each subsequent clause carries a distinct operational fact (parent constraint, default layout, grid alternative, follow-up tools, editor support). It is dense but not padded; the em-dash chaining makes it slightly harder to scan than a short bulleted breakdown 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?

For a 9-parameter mutation tool with no output schema, the description covers preconditions, layout modes, the one documented return value (grid coordinates), and the downstream calls. What is missing is any statement of the normal return value (presumably the resulting component set node) and error behavior, which matters given there is no output schema.

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

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

Schema coverage is 89%, so most parameters are already documented. The description adds genuine meaning beyond the schema for two of them: `arrange: false` suppresses the wrapping row, and `columns: "State"` produces a column per value and a row per combination of the remaining properties, with page coordinates returned. `gap`, `name`, and `force` semantics are left 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 ('Combine components into one component set (variants)') and anchors it to the Figma UI action of the same name. It is clearly distinguishable from siblings like figma_convert_to_component, figma_group_nodes, or figma_add_component_property.

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 an ordered workflow: rename components to 'Property=Value' first via figma_rename_node, ensure a shared parent, then place variants with figma_create_instance and switch with figma_set_instance_properties. Alternatives for layout (arrange vs columns) are spelled out with the conditions that select each.

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 and destructiveHint=false. The description adds useful behavioral detail: the conversion keeps the node's properties and children, returns a new component id, and cannot run on nodes already inside components or instances. It does not cover permission or stale-edit failure handling, but the force parameter's schema description does.

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

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

The description is front-loaded with the core operation and then efficiently layers in constraints, the relevant sibling tool, and editor availability. Every sentence carries useful 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 tool without an output schema, the description compensates by noting that the result id is returned. It also covers conversion constraints, the next-step sibling, and editor scope, leaving little an agent needs to know before calling it.

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

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

Schema description coverage is 100%, so both required and optional parameters are already documented. The description does not add parameter-specific semantics beyond the schema; its mention of the returned id is output context rather than parameter guidance.

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

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

The description states a specific verb and resource: 'Turn an existing node (usually a frame) into a reusable COMPONENT.' It distinguishes the operation from sibling tools like figma_create_instance by naming that tool for placing copies afterward.

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 explicit when-to-use context ('existing node, usually a frame'), when-not conditions ('already a component, or sits inside a component or instance, cannot be converted'), and points to figma_create_instance for the follow-up copy step.

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 safety profile (not read-only, idempotent, non-destructive), but the description adds substantial behavioral context beyond them: one undo step, Design-only editors, plates 2–n resting at opacity 0 (so figma_export_node shows panel 1), STALE refusal via `force`, and every track read back as `verified`/`notApplied`.

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 transformation and every sentence carries real information, but the paragraph is dense and heavy, packing many behaviors (dissolve, drift, burnIn, verified tracks, render routing) into long clauses. Helpful, but not maximally scannable.

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, complex creation tool with no output schema, the description is complete: it explains what gets built, how timing is sourced, what `blank` lists, the verification readback, and the render/review follow-up. Nothing an agent needs to call it correctly appears 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 high (91%) and already documents most params, but the description adds operational meaning: `dissolveFrames` applies only to panels whose transition caption starts with 'dissolve', `drift` pushes 3%, and `burnIn` semantics. It complements the schema rather than merely repeating it.

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 a figma_create_storyboard board into an animatic') and describes exactly what the output is: a top-level `Animatic · <title>` frame with one plate per panel. It explicitly names the sibling it builds on (figma_create_storyboard) and downstream tools, so an agent can distinguish it without reading 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?

Explicit routing: the result's `render` is the figma_export_video call, then pace is judged with figma_review_video, and the skill is storyboard (figma_get_guide). It also states the editor restriction ('Design only, unverified') and the one-undo-step caveat, covering when and how to invoke.

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 context beyond the annotations: unknown language values are refused rather than falling back to plain text, FigJam controls styling so there is no theme/font/size to set, and the editor support is flagged unverified. It does not restate the mutation/staleness behavior that the schema's `force` parameter already documents.

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 one-line purpose and keeps the constraints tight, but the full 17-item language enumeration largely duplicates the schema's description and clutters an otherwise efficient paragraph.

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 creation tool with no output schema, the description covers what the agent most needs (editor scope, language handling, styling limits); placement, retry and staleness parameters are fully explained in the schema, so nothing critical 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; the description earns a bump by explaining the refusal semantics behind `language` (invalid values rejected, not rendered as plaintext) which the schema's flat value list 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?

Opens with a specific verb+resource+scope: 'A FigJam code block with syntax highlighting.' The 'Editors: FigJam only' line distinguishes it from the general text/shape creation siblings, though it never names figma_create_text as the alternative for design files.

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 guidance on the language argument (default plaintext, unknown values refused, 'ask for plaintext yourself'), but says nothing about when to choose this over figma_create_text or figma_create_stickies, nor any prerequisite about needing a FigJam file open.

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 annotations (which only mark it as a non-destructive, idempotent write): it discloses that connectors are created in their final parent and never moved, that reparenting leaves stale elbows, and that an endpoint cannot be another connector. It also flags environment risk ('FigJam only, unverified') and uncertainty in the point syntax, all of which the agent could not infer from structured fields.

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 verb, resource, and batch limit, and every sentence carries real information (ordering, endpoints, styling, sibling). It is dense and heavily parenthetical, with some endpoint syntax duplicated from the schema, which costs a bit of tightness.

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 5-parameter batch-write with no output schema, it covers placement, ordering constraints, endpoint forms, styling defaults, and the edit path. The remaining gap is what a call returns (created connector identifiers/status), which it never mentions.

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 schema already documents endpoint syntax, lineType defaults, and cap defaults — and the description largely repeats those same strings. It adds marginal gloss (caps default none at start / arrow-lines at end, ERD caps) but no syntax or format details absent from the schema, 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?

Specific verb and resource with scope: 'FigJam connector lines between nodes, 1–200 in one call.' It distinguishes itself from figma_create_line (plain lines) and figma_edit_connectors (modifying an existing one), so an agent can pick it 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 ordering advice ('build connectors last') and routes later changes to figma_edit_connectors, plus a hard scope exclusion ('FigJam only'). It does not explicitly contrast with figma_create_line for the same visual output, so usage context is clear but not fully disambiguated.

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 write/idempotent/non-destructive/non-open-world profile, so the description's job is to add context — and it does: the style is *local* (not a published library asset) and "Editors: Design only," a real permission constraint an agent cannot infer from annotations. It does not mention duplicate-name behavior or what the call returns, so it stops short of full disclosure.

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 clauses, zero filler, with the resource and the apply path front-loaded. It reads as telegraphic fragments rather than sentences, which is efficient but slightly cryptic on first read.

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 6-parameter creation tool with no output schema, the description covers purpose, related tools, and permission scope, but never says what comes back (a style id/key to pass to figma_apply_style_to_node) or how name collisions are handled. Those gaps matter because there is no output schema to fill them.

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 effect sub-object is documented field by field with defaults and per-type applicability. The description adds only that entries mirror figma_set_effects and cover shadows/blurs; it says nothing about name, description, session, idempotencyKey, or the stale/force contract. Baseline 3 is appropriate when the schema carries most of the load.

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 local effect style (shadows, blurs)") and implicitly separates it from the paint/text/grid style siblings by qualifying it as an effect style. It lacks an explicit verb, relying on the title "Create effect style" to supply the action, so it falls just short of a full verb+resource statement.

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?

Three sibling relationships are spelled out: apply it with figma_apply_style_to_node, edit it with figma_update_style, and its entries match figma_set_effects. That effectively routes the agent between the create-style path and the direct-effects path, though it never states the selection rule outright ("use this instead of figma_set_effects when you want a reusable style").

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, so the safety profile is covered. The description contributes the editor-availability note (works in Design, unverified in FigJam/Slides), which is real context not present in annotations. However, it says nothing about the STALE/force overwrite semantics, parent requirements, or what gets created and returned, leaving 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?

Two short sentences with no filler, so it is compact. But it is compact to the point of under-specification: the lead sentence is a fragment with no verb, so the size is achieved by omitting necessary information rather than by trimming waste.

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-parameter mutation tool with a nested `sizing` object, low schema coverage, and no output schema, the description should carry substantial weight. Instead it supplies one line of editor scoping and nothing about geometry, parenting, or the result of the call — clearly inadequate for the tool's complexity.

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

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

With 11 parameters and only 36% schema description coverage, the description is expected to compensate and does not — it only alludes to the optional `fill` value. Critical parameters like `parentId`, `x`/`y` positioning, `sizing`, and `name` are never explained in the description, and the `force` STALE-retry semantics are documented only inside 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 is a noun phrase ("An ellipse with an optional fill") that restates the tool title rather than stating an action; the verb "create" only appears in the tool name/title. It offers no differentiation from the many sibling creation tools (figma_create_rectangle, figma_create_polygon, figma_create_star, figma_create_vector), so an agent gains nothing beyond what the name already says.

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?

"Editors: Design; unverified: FigJam, Slides" is a useful environment constraint that hints at when the tool is applicable, but it is terse and unexplained. There is no guidance on when to choose an ellipse over a polygon/vector, and no mention of prerequisites such as needing a parentId or an active Figma session.

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 write, idempotent, non-destructive, so the bar is lower; the description nonetheless adds real behavior: no clipping unless clipsContent (so shadows stay visible), auto-layout hugging on any unsized axis, sizing fill inheriting parent width, and rowGap defaulting to gap. It doesn't cover the STALE/force write-refusal semantics, which live only 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?

Front-loaded with the concept ('A frame — the building block for structure') then compressed to practical advice. Dense and mostly earns its space, though the mixed backtick-heavy phrasing and trailing editor caveat read slightly telegraphic.

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 21-parameter creation tool with no output schema, the description supplies the layout model and composition workflow an agent needs to call it correctly. Gaps remain around returned identifiers/return shape and the force/idempotency interplay, but the core decision inputs 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 86%, so 3 is the floor; the description earns an extra point by explaining cross-parameter logic the schema can't: layout+gap+padding+align as a unit, rowGap defaulting to gap under wrap, and sizing.horizontal='fill' taking the parent column's width. It doesn't touch a few parameters such as cornerRadius or background defaults.

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 a specific verb+resource ('Create frame') and defines the frame's role as the structural building block. It's clearly distinguishable from siblings like create_rectangle or create_section by the auto-layout emphasis, but it never names those alternatives explicitly.

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?

Clear contextual guidance: 'one frame per section, row or card, each with auto-layout ... then add content into it by parentId' supplies a usage pattern, and the editor scope (Design; unverified FigJam, Slides) tells the agent where it applies. It stops short of explicitly stating when to use a plain shape or group instead.

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 annotations: one undo step, no rollback on mid-way failure, created[]/failedAt reporting, STALE-overwrite semantics reinforced via force, idempotencyKey retry behavior, and editor coverage (Design verified; FigJam/Slides unverified). Only the return payload shape is gestured at rather than described, 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?

Front-loaded with purpose and workflow, and the grammar pointer and minimal example earn their space. It is dense and the mid-sentence enumeration is long, but nothing is clearly 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?

No output schema exists, yet the description still tells the agent what a partial result looks like (created[], failedAt) and how to recover. Combined with workflow, grammar link, and editor caveats, 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 coverage is 100%, so the baseline is 3; the description adds real value by pointing to the spec grammar doc and giving a minimal valid spec example with layout/gap/padding/children semantics. It reinforces parentId usage and idempotencyKey sizing advice beyond the schema 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?

Opens with a specific verb+resource+scope: 'Build a whole SECTION in one call', then enumerates exactly what it composes (frames with auto-layout, text, shapes, SVG, images, components). It also distinguishes itself from the granular siblings (figma_create_frame, figma_create_text, etc.) by emphasizing 'whole section', and from a whole-page build by 'Not a whole page in one payload'.

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 an explicit workflow: create a wrapper frame, then one call per section by parentId, then figma_check_layout plus one figma_export_node, then targeted fixes. It also names the grammar source (figma_get_guide topic: spec) and states the array-of-roots constraint (needs parentId or pageId), 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 (non-read-only, non-destructive, idempotent), and the description adds genuinely new context: the style is 'local' (not a library asset) and creation is restricted to 'Design only' editors, a real permission constraint. It doesn't discuss what happens on name collisions or what the call returns, but the force/STALE behavior is documented 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?

Two dense sentences with the definition first and the disambiguation second — nothing wasted. The opening is a nominal fragment rather than a sentence, which is slightly less parseable but costs no 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 6-parameter tool with a nested grids array, no output schema, and annotations already covering safety, the description supplies the concept, an example, the sibling boundary, and the permission constraint. Remaining gaps (return value, retry/idempotency expectations) are handled by schema parameter descriptions.

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?

At 67% schema coverage the schema does most of the work, and the description adds a concrete worked example ('12 columns, 24 gutter, 64 margin') that maps directly onto the count/gutter/margin fields of the nested grids array, plus a cross-reference to figma_set_layout_grids for entry semantics. It doesn't add anything for name or pattern, which are the leftover uncovered 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?

The description defines the resource precisely — a local GRID style, a named layout grid with concrete example values (12 columns, 24 gutter, 64 margin) — and distinguishes it from figma_set_layout_grids, which sets raw grids on frames. The only weakness is that the creating verb lives in the title rather than the description, but the referent is unambiguous and an agent can separate it from siblings.

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

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

It explicitly names the alternative ('Entries as in figma_set_layout_grids, which sets raw grids on frames instead') and the downstream consumer (frames follow it via figma_apply_style_to_node). That gives a clear create-a-reusable-style vs. set-a-raw-grid routing rule. It stops short of stating the positive trigger condition ('use when the grid should be reusable across frames') outright.

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 (readOnly=false, destructive=false, idempotent=true), so the description needn't restate them. It adds genuinely non-obvious behavior: library components are imported first and then placed, which is a side effect on the file's asset list, plus a FigJam/Slides reliability caveat. It stops short of describing placement results or failure modes, but the stale/force behavior is carried by 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?

Four dense sentences with no filler, front-loaded on the action, then prerequisites, then the alternative tool. The first sentence is slightly tangled with its three parallel cases, 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 11-parameter creation tool with no output schema, the description supplies everything an agent needs before calling: how to source identifiers, the mutual-exclusion constraint, default placement context (deferred to schema), library import side effects, and platform support. Remaining param details are covered by 82% schema 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?

Schema coverage is 82%, so the baseline is 3; the description earns above that by explaining the semantics of the three identifier parameters and their exclusion rule, and by clarifying that `variant` takes a Figma-style string like "Size=Large, State=Hover" with a defined default. Coordinates, sizing, and idempotencyKey are left entirely to their schema descriptions.

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

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

The opening sentence uses a specific verb ("Place an instance") and enumerates the three distinct resource cases: a component, a set's default variant, and a named variant. It is immediately distinguishable from siblings like figma_swap_component and figma_convert_to_component.

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

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

It explicitly routes the agent: local ids come from figma_get_local_components, bulk imports use figma_import_library_assets, and changing an existing instance's component requires figma_swap_component instead. It even states the mutual-exclusion rule ("Give exactly one of componentId, componentKey, componentSetKey") and the editor support matrix.

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, destructive=false and closed-world, so the safety profile is covered. The description adds real value beyond them — geometry semantics for `length`/`angle` and the auto-layout resize behavior — but says nothing about the returned node identity, default placement when `parentId` is omitted, or whether the new line is selected.

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 and dense — the use cases, then geometry, then the rectangle alternative, then environment caveats. Every sentence carries information, though the telegraphic fragment style ('A straight line: ...') costs a little readability and the auto-layout sentence is long.

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 mutation tool with no output schema, the description covers the geometry that actually determines the result and the environment constraints. It could have closed the loop on what is returned and on default parenting, but the schema's descriptions plus annotations fill most of the remaining space.

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 54% schema coverage the description does meaningful work: `length` is quantified as px from (x, y), `angle` as degrees with 0=right and 90=up, and `cap` is enumerated with the fact that it decorates both ends. However `name` and `parentId` are documented in neither place, and gaps remain on whether x/y are absolute or parent-relative.

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 concrete resource plus a list of canonical use cases (dividers, connectors, arrows, underlines, decorative strokes), which pins down the shape type immediately. It also names the sibling it competes with (figma_create_rectangle) and the condition that separates them, so an agent can route 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?

Explicitly says when to use a rectangle instead: for a divider inside an auto-layout, a 1 px rectangle with `sizing: { horizontal: "fill" }` stretches while a line keeps its length. It also states environment coverage (Design supported; FigJam and Slides unverified), which is exactly the qualification an agent needs before committing.

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 (non-read-only, non-destructive, idempotent), and the description adds real value beyond them: the remote fetch happens, previews can be refused with Figma's message, and the STALE/force interaction is spelled out. Minor tension: the description implies an external https fetch while openWorldHint=false, which an agent might read as "no network reach".

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 front-loaded sentences: what it does, how previews resolve, refusal behavior, and return shape, then a terse editor caveat. Dense but nearly every clause carries information; "in Figma's own words" is the only decorative touch.

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 7-parameter write tool with no output schema, the description covers outcome types, failure behavior, the return object shape, and the FigJam-only editor restriction. Notable omissions are fetch failure/timeout handling and whether a refused preview consumes anything, but the essentials 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 100%, so url, parentId, force, session, idempotencyKey and coordinates are all documented in the schema. The description reinforces the parent check and the STALE semantics of force but adds no 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?

States a specific verb+resource: paste a web link onto a FigJam board as a card, and explains the two resulting node kinds (EMBED vs LINK_UNFURL). No sibling tool creates link cards, so the agent can distinguish it 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?

"Editors: FigJam only, unverified" plus the parent-check/refusal sentence give clear conditions and constraints for use, and the embed-vs-unfurl explanation tells the agent what it will get. It doesn't name an alternative tool, but no sibling competes for this action.

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

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

Beyond the annotations (idempotent, non-destructive), the description discloses a real behavioral constraint: free Starter files cap at 3 pages, and the resulting failure is Figma's own error surfaced as-is, not a bridge error. That distinction matters for error triage, and the app-availability caveat (Design verified, FigJam/Slides unverified) is useful operational context.

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

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

It is short and the constraint note is dense with useful information, but the most important sentence — what the tool actually does — is a four-word fragment, while a plan-limit caveat leads the body. Front-loading favors the edge case over the core action.

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

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

For a create tool with no output schema, the description plus the detailed schema cover most of what an agent needs: what is created, plan cap behavior, environment support, idempotent retries, and the activate/force semantics. The only gap is that it never says what is returned (page id/name) or whether the new page is empty, but the schema does much of the load here.

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 80% and the parameter descriptions are unusually rich (force/STALE semantics, idempotencyKey retry behavior, session selection, activate default). The description adds nothing about any of the five parameters, so it earns only the baseline for high-coverage 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?

The description opens with the noun phrase "A new page." which essentially restates the tool name rather than stating a verb+resource action. It does identify the resource (page) as distinct from frames/sections, but there is no explicit statement that this creates a page, and no differentiation from the many other figma_create_* 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?

There is no when-to-use or when-not-to-use guidance and no named alternative (e.g., create_section, clone_node). The only usage-shaped information is the environment note ("Editors: Design; unverified: FigJam, Slides"), which tells the agent where the tool is available but not when to pick it.

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

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

Goes beyond the annotations by disclosing the Design-only editor scope, the fact that a style has no size (so gradient angles are only exact on square nodes, with the 135→~163 on 1280×400 example), and that `variableId`/`variableName` binds the first paint's colour so the style tracks a token. Annotations already cover safety (destructiveHint=false, idempotentHint=true), so remaining gaps like return shape are minor.

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 and dense — the core shape (color or fills, variable binding) comes first, then the gradient-angle caveat and the editor scope. Telegraphic fragments ('A local PAINT style: one `color`, or `fills`...') are efficient rather than confusing, though the angle caveat is lengthy relative to its importance.

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 create-mutation with no output schema, the description covers mode selection, variable binding, editor scope, and the trickiest edge case (gradient angle on sizeless styles). It does not address name-collision behavior or what is returned on success, leaving the agent to infer the latter from the absence of an output schema.

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

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

With 80% schema coverage the baseline is 3, and the description adds real meaning on top: how `variableId`/`variableName` bind the first paint, that `fills` entries follow figma_set_fills conventions, and the exactness caveat for gradient `angle`. It does not cover `force`, `session`, or `idempotencyKey`, but those are documented in 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 ('A local PAINT style') and enumerates the two construction modes ('one `color`, or `fills`'). It implicitly but clearly separates itself from figma_create_text_style/figma_create_effect_style by naming the style type, and from figma_set_fills by clarifying that this creates a reusable style rather than node 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 elsewhere in two situations: 'Change it later in place with figma_update_style' and 'for an exact CSS angle on a known node use figma_set_fills, or give `transform`.' It also names the editor restriction ('Editors: Design only') so the agent knows when this tool is not applicable 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 already declare readOnly=false, idempotent=true, destructive=false, openWorld=false, so the safety profile is covered. The description adds a genuine behavioral trait not in annotations: editor support ('Editors: Design; unverified: FigJam, Slides'), plus the multi-step note that a diamond requires a follow-up rotation. The force/STALE and idempotency behavior is delegated to schema descriptions.

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 definition, then examples, then editor support, with no filler. The em-dash density is slightly compressed but every clause (pointCount mappings, rotation, editor scope) 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?

For a 15-parameter creation tool with a nested sizing object and no output schema, the description covers purpose and editor context but does not compensate for the many undocumented optional parameters (positions, fill, stroke, parent). Adequate but with clear gaps given the schema's 47% 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?

Schema coverage is 47%, so the description must help but only partly does. It adds useful meaning to pointCount (side count, with 3/4 mapped to triangle/diamond and the rotation caveat), but leaves x, y, fill, name, stroke, and parentId undocumented in both schema and 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?

The description states exactly what is created (a regular polygon) and disambiguates it from sibling shape tools by specifying the side-count mechanism (pointCount 3 = triangle, 4 = diamond via rotation) versus star/ellipse/rectangle. Concrete use cases (badges, play buttons, decorative geometry) reinforce the resource identity.

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 clear when-to-use guidance through examples ('Badges, play buttons, decorative geometry') and even routes the diamond case through figma_rotate_nodes, an explicit alternative interaction. It lacks explicit when-not-to-use or named shape alternatives, keeping it at 4 rather than 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 declare this is a non-readonly, non-destructive, idempotent creation operation, so the safety profile is covered. The description adds useful platform-availability context by naming Design and unverified FigJam/Slides, but it does not explain creation side effects, parent requirements, or return behavior.

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

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

The description is only two sentences and contains no filler; the styling options and editor support are stated compactly. It is concise, though that concision contributes to its under-specification for such a large 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?

For a 14-parameter creation tool with nested sizing, low schema coverage, and no output schema, the description is far too thin. It should clarify where the rectangle is created (parentId), sizing semantics, idempotency/force behavior, and how to choose among sibling shape creators.

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

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

Schema description coverage is low at 36%, so the description should compensate for undocumented parameters. It mentions fill, cornerRadius and stroke, but omits many important parameters including parentId, sizing, x, y, name, force and idempotencyKey, leaving substantial ambiguity for a 14-parameter tool.

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

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

The description identifies the resource as a rectangle with optional fill, corner radius and stroke, but it is written as a noun phrase rather than stating the create action. It does not distinguish this tool from sibling shape creators such as figma_create_ellipse, figma_create_polygon or 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?

It gives editor availability (Design; unverified FigJam, Slides) but provides no guidance on when to use this tool versus other shape-creation tools. There are no exclusions, prerequisites, or alternative recommendations.

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 read-only, destructive, idempotent, and open-world behavior, and the description does not contradict them. It adds useful editor-support context ('Design; unverified: FigJam, Slides') and describes FigJam structural behavior, though it does not discuss return values or failure modes beyond what the schema already covers.

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

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

The description is fairly compact and front-loads the section concept and nesting model. The first sentence is dense, but each part contributes to understanding the tool's domain and the key alternative.

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

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

Given 11 parameters, no required fields, 91% schema coverage, and strong annotations, the description provides enough context to select and call the tool. A minor gap is that with no output schema, it does not say what a successful creation returns, but the essential creation and nesting semantics 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 description coverage is 91%, so the baseline is 3, but the description adds meaning for `name` by explaining when an empty name pairs with a title text, and for `parentId` by noting it can be another section. It does not add much beyond the schema for the other parameters.

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

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

The description clearly identifies the resource as a section and explains its role as a page-organising container, including FigJam nesting. It distinguishes the tool from `figma_create_from_spec` for the fill-and-fit case, though the description itself does not explicitly say 'creates' and relies on the title/name for the verb.

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 a concrete alternative: to fill and fit a section in one call, use `figma_create_from_spec` with `arrange` and `hug`. It also explains the `name: ""` untitled case and that `parentId` can be another section, but it does not broadly compare when to use a section versus a frame or page.

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, non-destructive, idempotent, closed-world behavior, so the bar is lower; the description still adds real behavior: auto-fit sizing unless width/height are supplied, preset colors that set fill, stroke and text together versus hex overrides, and the FigJam/Slides verification caveat. Missing only the STALE/`force` overwrite semantics, which live in the schema rather than the description.

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 capability, then structured by parameter in backticks, with sibling routing at the end. It is dense and occasionally elliptical ('…', trailing type lists), but almost every clause carries decision-relevant 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 nine-parameter batch-creation tool with no output schema, the description covers sizing behavior, the shape/label vocabulary, color model, layout semantics, sibling hand-offs, and an environment caveat. There is nothing an agent needs to call it correctly that 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 already 89%, but the description goes beyond it by enumerating shape types, defining `label` as a 1–2 character fixed-size marker, and listing the full preset color palette plus light- variants and the hex fill/stroke/textColor alternative. Container-level params (x, y, session, parentId, idempotencyKey, force) 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+resource+surface: FigJam shapes with text, batchable 1–200 per call, with named shape types and a label variant. It also distinguishes itself from the three nearest siblings (stickies for layout, connectors for joining, table for row/column data).

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

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

Explicit routing: 'Laid out like figma_create_stickies', 'Join them with figma_create_connectors', and 'Row and column data is figma_create_table, never a grid of shapes'. It also states when fixed sizing applies ('unless width and height are given') and warns editors are 'unverified in FigJam, 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 idempotentHint=true and destructiveHint=false, so the description needn't restate safety. It instead adds non-obvious behavior: 'Every position is checked before the first slide exists' (all-or-nothing validation, no partial writes), the returned fields ('id, row, col and index as read back'), and an editor scope caveat ('Editors: Slides only, unverified'). The concurrency/STALE behavior lives in the schema's force param rather than the description, which is the only 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 and scope, and every sentence carries information. The middle section cramming per-item fields, placement rules and cross-tool workflow into one dense passage is harder to parse than it needs to be, but nothing is disposable.

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-parameter mutation tool with no output schema, the description covers what it creates, the batch limits, placement semantics, validation timing, the return shape, follow-up tools, alternatives and environment requirements. An agent has everything needed to call it correctly and to know what comes next.

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?

Well beyond the 75% schema coverage: it explains that `row` is counted against the grid left by earlier items and that 'the current row count opens a new last row', that omitting both row and col appends to the end of the deck, and that on an empty deck the first slide makes row 0. It also justifies `background` placement ('it goes on the slide, since rows and the grid have no fill'), which the schema 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 and resource with hard scope: 'Add 1–20 empty 1920×1080 slides to a Figma Slides deck, in list order.' It also explicitly distinguishes itself from figma_create_frame (frames on a page), figma_move_slides (reorder) and figma_set_slide_grid (regroup), 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 workflow: create the empty slides here, then fill each via figma_create_from_spec with parentId = slide id, then verify with figma_check_layout at 3–5 slides per call. It also names exclusions ('Not for frames on a page') and a negative pattern ('Do not delete and rebuild slides to restyle a deck: edit them in place'), which is exactly the when/when-not guidance the dimension asks for.

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), and the description adds meaningful behavioral context beyond them: the slot-property relationship, instance fill mechanics, the grid refusal, the inability for figma_set_instance_properties to set a slot, and editor/platform availability including unverified platforms.

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

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

The description is compact and front-loaded: it starts with the core create action, then adds constraints and alternatives without redundant restatement. Each sentence contributes a distinct operational detail.

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

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

For a 9-parameter create tool with no output schema, the description covers the essential invocation semantics, constraints, sibling alternatives, and platform availability. The only minor gap is that it does not describe the return value, but the schema and annotations together make the definition sufficiently complete.

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

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

Schema description coverage is 78%, so the schema already carries substantial parameter documentation. The description still adds operational meaning for key parameters, especially that componentId must be a component or one variant (not a set) and that layout accepts horizontal or vertical because Figma refuses a grid on a slot.

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 specific verb and resource: add a slot to a component, defining what a slot is (a frame filled per instance) and the associated SLOT property. It also distinguishes the tool from related operations by noting a component or one variant must be passed, not a set, and that figma_set_instance_properties cannot set a slot.

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 clear usage conditions: pass a component or one variant rather than a set, use horizontal or vertical layout because Figma refuses a grid on a slot, fill it in an instance via parentId, and use figma_reset_slot to empty it again. These are explicit when-to-use and when-not-to-use constraints 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?

The annotations already declare this is a non-destructive, idempotent write, and the description adds useful context about editor support and shape semantics. However, it does not explain creation behavior such as where the node is inserted, what is returned, or permission/session implications beyond what the schema already provides.

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

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

The description is compact, front-loaded with the core shape concept, and then supplies use cases and editor caveats without wasted wording. Every sentence contributes either shape semantics or applicability context.

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

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

Given the robust annotations and partial schema descriptions, the description is adequate for selecting the tool and understanding its core geometry. It remains thin for a 16-parameter creation tool with no output schema: it does not cover return values or several creation-context parameters such as parent, session, and required sizing context.

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

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

The description adds real meaning to `pointCount` and `innerRadius`, especially the 0–1 inner-radius behavior and the spiky-to-polygon continuum. With 16 parameters and only 50% schema description coverage, many parameters such as `x`, `y`, `parentId`, `fill`, and `stroke` receive no description-level clarification, so the added parameter guidance is useful but partial.

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 identifies the resource precisely as a star or burst and explains its defining geometry via `pointCount` and `innerRadius`, which separates it from a generic polygon. It does not explicitly say 'creates' or name sibling alternatives, but the tool name/title and shape-specific language make the purpose clear.

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 provides concrete use cases such as rating stars, sale bursts, sparkles, and decorative shapes, giving an agent clear situations for selection. It also notes Design is supported while FigJam and Slides are unverified, but it stops short of naming when to use `figma_create_polygon` or `figma_create_vector` instead.

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

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

Beyond annotations, it explains layout behavior: grid placement from real sticky sizes, no overlap because rows are placed after text is applied, fixed size with no width/height, and the parent is never resized. It also discloses the return shape (`created [{ index, id, x, y, width, height }]` and bounds), which annotations alone do not cover.

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 key constraints are front-loaded and the dense prose is mostly information-bearing. It is longer than necessary because it repeats some schema-provided defaults, but it remains structured and readable.

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

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

There is no output schema, so the description appropriately explains the return value and bounds. It also covers the important parent-overflow behavior, FigJam-only scope, layout rules, and size constraints, making it complete 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 already 89%, so the schema carries most parameter meaning. The description adds useful semantics beyond the schema, such as color names landing on exact FigJam swatches and `wide` being for about 100 words or more, while also repeating some schema defaults like `columns` and `gap`.

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

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

The description states a specific verb and resource: create FigJam sticky notes, one idea each, 1–200 per call, laid out as a grid. It also distinguishes stickies from text-based annotations by saying prompts, labels, and instructions are text, not stickies.

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 explicit context: FigJam only, use `wide` for about 100 words or more, and use `figma_fit_sections` when `parentOverflow` occurs. It also says prompts/labels/instructions should be text rather than stickies, but does not name the specific text-creation sibling, so the alternative routing is slightly implicit.

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 is a write (readOnlyHint=false) that is idempotent and non-destructive; the description adds value beyond them by noting "One undo step" and disclosing that the result flags offBeat panels and readTime issues to fix before building. It doesn't spell out return structure or failure modes, keeping it from 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?

Front-loaded with purpose and artifact structure, then timing rules, then alternatives. It is dense but every sentence (snapping, offBeat/readTime warnings, sketch/retime workflow) carries operational information 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?

For a 17-parameter tool with no output schema, the description covers when to use it, how timing is computed, what the result flags (offBeat, readTime), and the follow-up path. Return-value detail is partial and the `source`/`image`/`styleframe` panel modes are only lightly sketched, leaving minor 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 high (88%), so the schema carries most parameter documentation. The description nevertheless adds semantics the schema doesn't: timing is derived from each panel's `durationS` and snapped to whole frames by default, with start/end expressed in seconds and frames at `fps` and bar.beat via `bpm`.

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 defines the artifact: a board of card rows, one per panel, thumbnail at `aspect` above caption rows. It explicitly contrasts with the animation sibling ("figma_set_keyframes animates"), so an agent can distinguish it 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 when-to-use (before animating), routes to concrete alternatives (figma_create_from_spec for sketching thumbnails, figma_set_keyframes for animation, figma_get_guide for the skill), and states the retiming workflow (edit the duration caption). It also names supported environments (Design) versus unverified ones (FigJam, 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 cover the safety profile (non-destructive, idempotent, closed-world), yet the description still adds real behavioral detail: fills are never removed and "" is refused, columns cannot shrink below a minimum so actual widths are returned, header styling defaults differ between rows and empty forms, and editors are unverified in FigJam/Slides. That is context the agent could not derive from the structured fields alone.

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 that is front-loaded with the identity claim and the mutually exclusive input forms before moving to optional styling. Every clause carries information, though the preset colour enumeration is long enough to slightly crowd the rest.

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 18-parameter creation tool with no output schema, the description covers input forms, defaults, styling, and resize behavior well. The one real gap is what the call returns (presumably the created node/id), which the agent must infer because no output schema exists to cover it.

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

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

With schema coverage at 83% the baseline is 3, and the description earns above that by listing the full preset colour vocabulary (black, dark-gray, …, light- variants, hex) that the schema only summarizes as 'Table preset or hex', by explaining the rows/numRows exclusivity, and by noting font settings apply to every cell. It leaves x/y/name/parentId/force/idempotencyKey untouched, but those carry their own schema 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?

States a specific verb and resource (a FigJam table) and immediately differentiates it from the nearest lookalike — 'never a grid of shapes' — which an agent can act on without comparing schemas against create_shapes_with_text. It also names the sibling that handles subsequent cell edits (figma_edit_table).

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 routing rules: use a table rather than a grid of shapes for row-and-column data, and supply either `rows` or `numRows`+`numColumns` — 'exactly one form' — not both. It further routes the agent to figma_edit_table for changes because cells have no ids.

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 (idempotent, non-destructive, closed-world), yet the description still adds real behavior: the documented font fallback chain and a `fellBack: true` flag in the result, plus the overflow consequence of omitting `width`. It omits the STALE-write refusal and the retry-key semantics, which live only in the parameter 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?

Roughly three dense sentences for a 17-parameter tool, with the placement/wrapping rule front-loaded and the font-fallback note last. The parenthetical asides make individual sentences long but nearly every clause carries actionable 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 17-parameter mutation with a nested `sizing` object and no output schema, the description covers layout and font behavior but leaves the write-safety story (STALE refusal, `force`, `idempotencyKey`) and multi-file `session` selection entirely to the schema. It is adequate to call the tool, but not fully self-sufficient.

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

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

Schema coverage is 76%, so the baseline is around 3, but the description genuinely adds meaning beyond the schema: `width` absence implies single-line overflow, `align` is conditional on auto-layout inheritance, and `parentId` defaults matter for placement context. Many of the 17 parameters (force, session, idempotencyKey, lineHeight, letterSpacing) are unmentioned, relying entirely on their schema 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 opening clause, 'A text node, placed into a frame by parentId', makes clear this creates a text node and where it lands, and the wrapping/alignment discussion reinforces that. However, it never uses an explicit verb, and it does not differentiate from near-siblings like figma_create_shapes_with_text, figma_set_text, or figma_create_text_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?

It gives concrete conditional guidance: inside a vertical auto-layout the node fills and wraps automatically, elsewhere you should supply `width` or risk single-line overflow, and `align` overrides inherited column alignment. It also scopes environment applicability ('Editors: Design; unverified: FigJam, Slides'). It stops short of naming an alternative tool when this one is the wrong choice.

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 (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the description earns credit for adding what annotations cannot: the style is local (not a library/published style) and requires a Design-seat editor. It also flags a hard input constraint — lineHeight/letterSpacing must be strings, bare JSON numbers are rejected — which would otherwise cause a failed call.

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 and mostly front-loaded: the resource and the highest-risk parameter formats come first, then the update path, then the editor constraint. A few clauses restate schema facts (case, decoration, paragraph spacing) and the leading noun fragment is slightly awkward, but there is 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?

For a 14-parameter creation tool with no output schema and strong annotations, the description covers the things most likely to break a call: the string-encoded metrics, the editor-seat requirement, and the mutation follow-up path. It does not say what the call returns (e.g. the new style's id) or whether styles are file-scoped via the session parameter, which is a modest remaining 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 79%, so the baseline is 3; the description exceeds it by spelling out the exact accepted string grammar for lineHeight ('auto', '32', '150%') and letterSpacing ('0.5', '-2%') and by flagging the breaking change that numbers are no longer accepted. It also enumerates the secondary properties (case, decoration, paragraph spacing/indent) so an agent knows the style carries more than size and weight.

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 fragment 'A local TEXT style' plus the enumeration of typography properties makes clear this defines a text style, and the sibling differentiation from figma_update_style ('Change it later in place with figma_update_style') and from paint/effect styles is implicit in 'TEXT style'. It stops short of an explicit creation verb, so the reader infers 'create' from the title/name rather than the sentence itself.

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 names one alternative and its condition ('change it later in place with figma_update_style') and states an access constraint ('Editors: Design only'), which is real guidance. But it gives no criteria for choosing a reusable style here versus setting text properties directly with figma_set_text_properties or placing text via figma_create_text, and no when-not guidance.

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

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

Beyond the annotations (readOnly=false, idempotent=true, destructive=false), the description discloses that duplicate names are refused, that extra modes require a paid plan, and where the tool is verified versus unverified at the editor level. It does not say what comes back (e.g. the new variable id needed for later aliasing/binding), 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?

The passage is dense and front-loads the value encoding, then scopes/codeSyntax guidance, then sibling routing. The telegraphic, fragment-heavy style ('A name the collection already has is refused.') is efficient but slightly harder to parse than flowing prose, so not a full 5.

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 12-parameter mutation with no output schema, the description covers the highest-risk semantics (value encoding, aliasing, scopes, duplicate refusal, editor support) and the schema documents most remaining parameters. The absence of any statement about the return value—important since aliasing another token requires the new variable's id—is the notable omission.

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 adds real meaning: it explains that `value` is always a string per type and introduces the 'alias:<variable name or id>' syntax not documented in the schema, plus the `scopes` convention of [] for an aliased-only primitive. It repeats some schema text for `value` and leaves `force`, `modeId`, `session`, and `idempotencyKey` entirely to their schema descriptions.

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

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

The description opens with 'One design token' and details the exact value encodings, making it clear this creates a single variable/token, and it explicitly contrasts with figma_create_variables for bulk creation and figma_bind_variable_to_node for binding. The core verb is only implied by the name, not stated in prose, which keeps it just shy 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 gives explicit routing: use figma_create_variables for a whole token set in one call, figma_bind_variable_to_node to attach one to nodes, and figma_add_variable_mode for extra modes (noting the paid-plan requirement). It also states a constraint (duplicate names in the collection are refused) and platform availability (Design editors; unverified in FigJam/Slides), leaving little ambiguity about when this is the right call.

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

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

With no output schema, the description carries the return-value burden and does: it discloses that a refused mode surfaces as a `warnings` entry instead of a silent drop — exactly the partial-success semantics an agent needs. It also documents the first-mode naming rule (never 'Mode 1') and the editor surface (Design; unverified FigJam, Slides), which goes meaningfully beyond the idempotent/non-destructive annotations.

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

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

Four dense sentences, each carrying distinct information (naming, plan limits, follow-up tool, editor availability) with no filler. The opening fragment lacks its verb, which makes the front-load slightly weaker than it could 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?

For a non-destructive, idempotent creation tool with no output schema and 80% parameter coverage, the description supplies the missing result-contract detail (warnings) and platform reach. It stops short of describing the returned collection identifier/shape or duplicate-name behavior, which an agent would still need to infer.

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 bar is baseline-3, and the description earns above it by explaining the `modes[0]` default-name rule and the paid-plan ceiling on extra modes, which the schema's 'first is the default' note does not convey. The `name` parameter is undocumented anywhere, but it is self-evident.

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 establishes the resource precisely by glossing 'variable collection' as a token group and describes the mode-naming behavior, which no sibling does. The verb is only implied — the sentence is a fragment ('A new variable collection...') rather than 'Creates...' — but combined with the title and the pointer to figma_update_variable_collection, an agent can tell it apart from figma_create_variable, figma_create_variables, and figma_add_variable_mode.

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 context: extra modes beyond the first are paid-plan only, so multi-mode creation may partially fail, and later mode changes belong to figma_update_variable_collection. It does not explicitly contrast with figma_add_variable_mode or figma_create_variables for bulk creation, so the alternative routing is only partly 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?

Goes well beyond the annotations: it discloses that everything is validated before the first variable exists so a refusal creates nothing, the 200-per-call cap, pacing for Figma responsiveness, alias target ordering with type matching, and editor availability (Design; unverified FigJam/Slides). The only reason it is not a 5 is that it does not describe what the response contains on partial or refused runs, which matters for a batch write.

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 (token set, one call, one undo step) and every sentence carries load-bearing information. Slightly dense in the values/alias sentence, where the em-dash chains pack three constraints together, but there is 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?

For a complex batch mutation with no output schema, the description covers atomicity, validation timing, ordering dependencies, size limits, idempotent existence handling, editor support and escape hatches to sibling tools. Nothing an agent 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 already 83%, but the description adds real meaning: the string literal formats for values ('#1a2b3c', '16', text, 'true', 'alias:<name or id>'), the constraint that alias targets must exist earlier in the same call with the same type, and the full behavior of ifExists. It does not add anything for force, session or idempotencyKey, which the schema already covers well.

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 a whole token set / variable collection entries in one call), plus the atomicity promise (one undo step) and the primitives-then-aliases ordering. It names the sibling it is not (figma_create_variable for a single variable), so an agent can distinguish it 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?

Explicit routing: 'For one variable figma_create_variable is enough; to change properties later use figma_set_variable_properties.' It also gives the decision rule for name collisions via ifExists (error/skip/update) and the ordering rule for aliases, so the when and the how are both 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 already declare readOnly=false, destructive=false, idempotent=true, so safety is covered; the description adds genuinely new context the annotations can't carry — editor availability (Design verified, FigJam/Slides unverified) and scaling behavior ("one keeps its proportions"). It does not restate the STALE/force overwrite protocol, but that lives in the `force` schema description, so the remaining gap is small.

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 capability, then parameter semantics, then the sibling routing rule, then editor availability — a deliberate most-to-least-important order. Every sentence is a distinct, load-bearing fact; even the example list ("a blob, a wave divider, a custom arrow") disambiguates the tool's purpose rather than decorating it.

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 36% schema coverage, the description leaves the agent guessing about placement parameters (x, y, parentId), what the tool returns (a node id?), and whether it defaults into the current page or a parent. With annotations covering safety and idempotency, it is adequate but not complete for a tool of this complexity.

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

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

Schema coverage is only 36% across 14 params, so the description carries real burden — and it does explain `path` (the `d` attribute, with the command alphabet M L H V C S Q T A Z, absolute or relative), `width`/`height` scaling, and the stroke-without-fill interaction. But x, y, name, parentId, fill, and strokeWeight get no semantic treatment in either place, so the compensation is partial rather than complete.

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 ("Draw any shape from SVG path data") and immediately distinguishes itself from the primitive shape tools (rectangle/ellipse/polygon/star) by naming concrete use cases — blob, wave divider, custom arrow, logo mark, chart line. An agent can tell this apart from figma_import_svg and the shape primitives 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?

"For a whole SVG file (an icon) use figma_import_svg" is an explicit, actionable routing rule, and "Give `stroke` without `fill` for an open line" gives a usage recipe. It stops short of naming the closest sibling alternatives (figma_create_rectangle, figma_create_ellipse, figma_create_shapes_with_text) as when-not cases, so the agent must still infer the boundary with the primitive shape tools.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known; the description goes further and describes the blast radius concretely ('every instance loses it, overrides included'), which is the detail an agent needs before a destructive call. It also discloses editor availability (Design; unverified FigJam/Slides), a caveat 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?

Three sentences, zero filler: the destructive consequence is front-loaded, then the exclusion, then the alternative, then environment caveats. Every clause carries decision-relevant 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?

With no output schema and full schema coverage, the description supplies exactly the missing layer: consequences, type restriction, sibling routing, and platform support. Nothing an agent needs to call this destructive tool safely 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 100%, so all five parameters (including force, idempotencyKey, and the stale-write semantics) are already documented in the schema. The description adds no parameter-level detail beyond the general rule about which property types are eligible, 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?

Specific verb (delete) plus resource (component property) and an explicit enumeration of the deletable property types. It also names the sibling it is not (figma_edit_component_property) and the one type it refuses (VARIANT), so an agent can distinguish it from nearby tools 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?

States the use case, states an explicit exclusion ('A VARIANT property cannot be deleted — it comes from the variant names, so rename the variants instead'), and routes renaming/rewiring to figma_edit_component_property. When-to-use, when-not, and the alternative are all present.

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 destructiveHint/idempotentHint annotations: partial-failure semantics ("one node failing does not fail the call"), the refusal rule for non-empty slide rows, the `emptiedRows` report channel, undo granularity ("One Ctrl+Z reverts the whole original call"), and editor support scope (Design verified, FigJam/Slides unverified). These are exactly the operational traits an agent cannot infer from 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.