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

No annotations are provided, so the description carries the full disclosure burden for a mutating tool that repositions user content. It says nothing about whether existing positions are overwritten, whether the move is undoable, how invalid or cross-board node IDs are handled, or the 500-node ceiling (left to the schema). That's a significant gap for a repositioning operation.

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

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

Two sentences, zero filler, with the capability statement front-loaded ahead of the usage hint. Every sentence 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 and no annotations, the description is the only place to learn behavior, and it stops short of covering what the tool does not arrange (sections, tables, connectors) or what the result looks like. The fully documented schema compensates for parameter gaps but not behavioral ones.

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

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

Schema description coverage is 100%, so `layout`, `columns`, `spacing`, and `nodeIds` (with its 500 cap and sqrt default) are already fully documented in the schema. The description adds only a restatement of the layout values; baseline 3 applies.

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

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

Names a specific verb (arrange) and resource (nodes on a FigJam board) and enumerates the three layout modes, which matches the `layout` enum exactly. It's clearly distinguishable from sibling figjam_* tools, which all create content rather than reposition it, though it never says so 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?

"Use after batch-creating elements to organize them neatly" gives a concrete trigger and implies the workflow position relative to figjam_create_stickies/figjam_create_section. There are no exclusions or stated alternatives, so it falls short of a 5.

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

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

Since no annotations are provided, the description carries the full burden. It is accurate but non-technical; it doesn't disclose operational behaviors like placement defaults (for x, y), content sanitization, or rate limits. It avoids contradiction but provides limited deep behavioral insight.

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 highly concise. It is a single, focused paragraph where every sentence contributes directly to defining the tool's function and scope, without 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?

The description is nearly complete for a creation tool. However, it lacks contextual information regarding the default behavior for positioning (x, y) coordinates if they are omitted, which is a key functional detail for a canvas-based editor.

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

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

The input schema already has 100% description coverage. The description adds baseline semantic value by defining what the parameters ('code', 'language') are semantically intended for, specifically linking them to code snippets and technical formats.

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

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

The description clearly states the action and the resource ('Create a code block on a FigJam board'). It provides excellent semantic context by outlining common use cases like 'sharing code snippets' and 'technical documentation', which distinguishes it from general FigJam text tools.

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

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

It provides clear guidance on when to use the tool, focusing on specific scenarios (code, config, documentation). This helps the agent decide if a simple text box or a code block is more appropriate for the user's request.

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

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

No annotations exist, so the description carries the full burden. It usefully discloses the prerequisite (nodes must pre-exist) and the attachment semantics (magnet positions with AUTO default), but says nothing about failure behavior for invalid node IDs, whether the call is idempotent, or what the response contains (e.g. the new connector's ID).

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 prerequisite, then the magnet note in a short bolded block. Every sentence carries information, though re-listing the enum values already present in the schema is slightly redundant.

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

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

For a 5-parameter creation tool with no annotations and no output schema, the description covers purpose, prerequisites, ID sourcing and attachment options. The one meaningful omission is that, absent an output schema, it never tells the agent what is returned (such as the new connector's ID) for subsequent chaining.

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 an extra point by explaining what the magnet parameters actually do ('controls where the connector attaches to each node') and where startNodeId/endNodeId values come from. The remaining gap is minor redundancy with the enum already listing AUTO/TOP/BOTTOM/LEFT/RIGHT.

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 ('Connect two nodes with a connector line in FigJam') plus the domain of use. It is clearly distinguishable from the other figjam_* siblings such as figjam_create_sticky or figjam_auto_arrange, which create nodes rather than edges.

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

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

Names concrete scenarios (flowcharts, diagrams, relationship maps) and states the prerequisite that both nodes must already exist on the board, with IDs sourced from creation results. It does not explicitly point at a sibling (e.g. figjam_get_connections for verification), so it stops short of full when/when-not routing.

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

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

With no annotations, the description carries the burden, and it does disclose the key non-obvious behavior: creating a section does not automatically parent elements; you must set coordinates within its bounds and call section.appendChild(node). It also implies a node is returned. What it omits is where the section lands if x/y are omitted, and whether creation requires edit permissions or is undoable.

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

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

Three tight sentences: purpose first, definition second, workflow note last and visually flagged. Every sentence earns its place, and the operational caveat is separated from the core statement rather than buried.

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

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

For a 6-parameter, all-optional creation tool with no annotations and no output schema, the description covers what is created and the subsequent parenting step. The one remaining gap is the return value — the workflow depends on receiving a section node, but the description never states that the created section (or its id) is returned.

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 every parameter (x, y, name, width, height, fillColor) is already documented with ranges, defaults and hex pattern; the description adds nothing parameter-specific. The coordinate discussion in the note refers to child elements, not to this tool's own x/y semantics, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a section on a FigJam board') and immediately defines what a section is ('containers that can hold other elements'), which disambiguates it from siblings like figjam_create_shape_with_text or figjam_create_sticky. An agent can tell exactly what this produces 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?

'Use for grouping related content' gives a clear usage condition, and the note explains the required follow-up workflow (position children, then appendChild via figma_execute). However, no alternative or exclusion is named — e.g. nothing says whether to prefer figjam_auto_arrange or a shape-with-text container instead — so it stops short of full routing guidance.

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

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

No annotations are supplied, so the description carries the full behavioral burden for a write operation, yet it discloses only that shapeType defaults to ROUNDED_RECTANGLE. It says nothing about where a shape lands when x/y are omitted (all 10 params are optional), what the call returns, whether a board must be open/focused, or permission requirements.

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 usage context are front-loaded in one tight sentence, which is good structure. The second paragraph re-lists all 11 enum values verbatim from the schema, which is largely redundant and pads the definition.

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

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

There is no output schema and no annotations, and all parameters are optional, so an agent still lacks critical calling context: default placement when x/y are absent and what identifier is returned for later connector/shape operations. The purpose is well covered, but the operational picture is not.

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

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

Schema description coverage is 100%, so every parameter is already documented with units, ranges, and hex patterns; the baseline is therefore 3. The description adds only the shapeType default and a loose grouping of 'size, colors, font', which is marginal value over 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 ('Create a labeled shape on a FigJam board') plus the controllable attributes (size, colors, font). The explicit shape-type enumeration and the example use cases (flowchart nodes, process diagrams) make it unmistakable against siblings like figjam_create_sticky, figjam_create_section, and figjam_create_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?

'Use for flowchart nodes, process diagrams, and visual organization' gives concrete contexts where this tool is the right pick. It stops short of naming alternatives or exclusions (e.g., use figjam_create_sticky for notes, figjam_create_connector to link shapes), so there is no explicit routing rule.

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

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

No annotations exist, so the description carries the full burden. It usefully discloses the 200-item ceiling and the allowed color set, but says nothing about the failure mode (partial creation? atomic?), whether positions are optional/who assigns layout, or what identifiers come back for the created notes.

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 blocks, front-loaded with the core action and the cap. The bolded color list is largely redundant with the enum already present in the schema, but it is compact and does not obscure the main statement.

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 single-array-parameter tool with full schema documentation and no output schema, the definition covers purpose, scale, and an example use case. The remaining gap is only the result/failure behavior of a batch mutation, which is modest given the schema does the structural work.

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 baseline is 3. The description only restates facts already encoded in the schema (maxItems: 200 and the color enum), adding no meaning such as default coordinate behavior or text length limits.

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 ('Batch create multiple sticky notes on a FigJam board') plus a hard cap of 200, which implicitly separates it from the singular figjam_create_sticky sibling. It never names that sibling or any other FigJam creation tool explicitly, so the differentiation is inferred rather than stated.

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?

'Use this to populate boards from structured data (meeting notes, brainstorm ideas, etc.)' gives a genuine when-to-use. However, with a singular figjam_create_sticky sibling, the obvious batch-vs-single decision is exactly the one an agent must make, and no alternative or when-not guidance is provided.

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

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

No annotations are provided, so the description carries the full disclosure burden, and it discloses only the file-type restriction. It says nothing about what happens when x/y are omitted (auto-placement?), whether the sticky lands on the current page or viewport, what permissions are needed, or whether it is trivially reversible. For a mutation tool with zero annotation coverage, this is a significant 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 core statement is front-loaded in the first sentence and the FigJam restriction follows immediately, with no filler. The color enumeration partly repeats the schema's enum list, a minor redundancy against an otherwise tight block.

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

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

There is no output schema, so the description needn't explain return values, and the tool is simple with four flat parameters. Still, it leaves the default behavior of the optional x/y coordinates and the effect of the call on the board unaddressed, which is the main thing an agent would wonder about before invoking.

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, and the description earns extra credit by surfacing the YELLOW default for `color`, which the enum in the schema does not express. It adds little else about `text` or the x/y positioning semantics, so it stops short of a 5.

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

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

States a specific verb and resource ("Create a sticky note") and adds a real scope constraint ("Only works in FigJam files"), which lets an agent immediately rule it out for Figma design files. It does not, however, distinguish itself from the sibling `figjam_create_stickies`, so the singular-vs-batch distinction is left for the agent to infer from the names alone.

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

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

The FigJam-only restriction is genuinely useful gating information, but there is no guidance on when to prefer this over `figjam_create_stickies` (bulk) or `figjam_create_shape_with_text`, nor any prerequisite such as requiring an open FigJam file. Usage is implied by the environment constraint rather than stated as a routing rule.

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

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

With no annotations, the description carries the full behavioral burden, yet it discloses nothing about prerequisites (active FigJam file), what happens when `data` dimensions disagree with `rows`/`columns`, default placement when x/y are omitted, or cell-count limits. Only the data shape is explained, which is formatting, not behavior.

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

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

Two short blocks, purpose first, format second; nothing is padded. The format example partly duplicates the schema's own row-major description, which is the only minor redundancy.

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

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

A 5-parameter creation tool with no annotations and no output schema needs the description to cover prerequisites and edge-case behavior, and it only covers the data format. An agent still cannot tell what happens on dimension mismatch or where the table lands if x/y are omitted, and nothing is said about the return value.

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

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

Schema coverage is 100%, so the schema already documents all five parameters; baseline 3 applies. The description restates the 2D row-major array format with an example, adding mild clarification but not resolving the real ambiguity—how `data` length relates to the required `rows` and `columns`.

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 table on a FigJam board—and adds what the tool is for (structured data display, comparison matrices). It is clearly distinguishable from figjam_create_sticky or figjam_create_shape_with_text by the resource named, though it never explicitly contrasts with those 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?

"Use for structured data display, comparison matrices, and organized information" gives use-case context but reads as generic motivation rather than routing guidance. There is no statement of when to prefer this over stickies/shapes/code blocks, nor any prerequisite such as needing an open FigJam board.

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

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

With no annotations, the description carries the full burden; it does disclose the shape of the returned data and the filter-to-empty-set behavior, which is genuine value. It omits the operational traits that matter for a read tool: the 500-node default cap and truncation behavior (only in schema), permission/auth requirements, and whether it fails on non-FigJam files.

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

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

Front-loads purpose in the first sentence, then use cases, then filtering. Three tight blocks with zero filler and no repetition.

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 only two optional parameters and no output schema, the description usefully compensates by describing the return payload. It is nearly complete, missing only permission/error context that the absent annotations would otherwise have covered.

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 parameters are already documented, and the description largely restates them ("Omit for everything"). The one addition is a concrete example value (["STICKY"]), which is mildly helpful but marginal over the enum 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?

Specific verb+resource ("Read all content from a FigJam board") followed by an enumeration of what comes back (stickies, shapes, connectors, tables, code blocks, sections with text and positions). That clearly separates it from the figjam_create_* siblings, though it never distinguishes itself from figjam_get_connections, which covers overlapping connector/relationship 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?

Gives two concrete use cases (understand a board before modifying it; extract structured data from collaborative sessions) and explains when to pass nodeTypes versus omitting it. It stops short of naming an alternative tool or stating exclusions, so an agent must still infer that figjam_get_connections is the right pick for relationship-only reads.

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

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

No annotations exist, so the description carries the full burden; 'Read' plus 'Returns' establishes a safe read operation, and the return shape plus a 'summary of connected nodes' is disclosed. It omits which board is targeted (no params), whether large boards are truncated, and any permission prerequisites.

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 short sentences, front-loaded with the action and the return shape. The second and third sentences partially repeat the 'returns connectors/edges' point, which is minor waste but not bloat.

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

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

With no output schema and no annotations, the description does supply the edge shape, but it never says how the target FigJam board is determined (active file vs. selection) or how large graphs are handled. An agent could call it but may be unsure of scope.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly leaves parameter discussion out rather than inventing any.

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 ('Read the connection graph from a FigJam board') and even the shape of what comes back (connectors with start/end node refs and labels). It is unambiguous about what it does, though it never contrasts itself with the overlapping figjam_get_board_contents sibling.

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?

One sentence gives implied context ('understand relationships, flowcharts, and diagrams'), which is genuine usage guidance but not explicit when/when-not rules. An agent is left to infer that this is the connector-only view versus the broader board contents tool.

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

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

No annotations are supplied, so the description carries the full disclosure burden. It explains what properties are for (dynamic content in instances) and gives type semantics, but says nothing about whether adding a property mutates existing instances, whether the operation is reversible, what identifier comes back, or what error conditions are typical. That is a meaningful gap for an unannotated mutation tool.

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

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

Three short sentences, purpose first, type catalogue second, the one caveat last. Nothing is padded and 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?

For a 6-parameter tool with full schema coverage and no output schema, the description covers purpose, type selection, and the main alternative. It stops short of stating the return value (e.g. the new property key) and the effect on existing instances, which an agent would still want.

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%, including per-parameter notes like defaultValue requirements per type, so the schema already does the heavy lifting. The description's type list largely duplicates the `type` enum description verbatim, adding little beyond it. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Add a new component property to a component or component set') and then enumerates the supported property types with a plain-language gloss for each. An agent can tell this apart from figma_edit_component_property / figma_delete_component_property and is pointed at figma_create_slot for the slot case.

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 one explicit routing rule ('prefer figma_create_slot for new slots'), which is genuinely useful, but it never mentions figma_add_slot_property (a close sibling that also targets slots) or says when to use this tool versus edit/delete. Prerequisites — that nodeId must be an existing component or component set, that property names should be unique — are left 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?

With no annotations, the description carries the full load: it discloses the Desktop Bridge prerequisite and implies a mutation. It does not say whether existing variables receive default values in the new mode, whether duplicate mode names are rejected, or what happens on failure — notable gaps for a state-changing tool.

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

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

Three short sentences, front-loaded with the action, followed by the minimum conceptual context and the hard prerequisite. Nothing is redundant.

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

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

For a simple two-parameter mutation with no output schema and no annotations, the description covers purpose and prerequisite but leaves the post-condition of the new mode (default values for existing variables) and return/error behavior unstated.

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

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

Schema coverage is 100% and both parameters already include examples and a pointer to figma_get_variables for the collectionId. The description adds no parameter-level meaning beyond 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?

The first sentence states a specific verb and resource: adding a mode to an existing variable collection. It is clearly distinguishable from figma_rename_mode and figma_create_variable_collection, though it never names those siblings 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 supplies a real precondition (Desktop Bridge plugin must be running) and explains conceptually what modes are for, but gives no guidance on when to add a mode versus rename one, or how this relates to figma_rename_mode / figma_create_variable_collection.

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

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

No annotations are provided, so the description carries the full disclosure burden and largely drops it. It does not say what is returned (presumably a new shape node), what happens with an invalid slideId, whether the shape is layered on top of existing content, or how x/y are anchored (top-left origin?), even though the label 'position' is ambiguous.

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 well-formed sentence with the verb and resource front-loaded and the optional parameter acknowledged at the end. It is efficient, though it leaves out information an agent arguably needs.

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

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

There is no output schema and no annotations, so the description should at minimum say what a successful call yields (e.g., the created shape's node ID) and confirm the coordinate origin for placement. With 7 parameters and 6 required, the schema covers inputs well, but the return behavior and positional semantics remain undocumented.

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%, with units (pixels), ranges, an enum for shapeType and a hex pattern/default for fillColor already documented in the schema. The description only restates that fill color is optional and that shapes are rectangle/ellipse, adding no syntax or anchoring semantics beyond the schema — baseline 3.

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

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

States a specific verb (add) and resource (shape on a specific slide) and enumerates the allowed shape kinds (rectangle, ellipse). The 'to a specific slide' phrasing implicitly separates it from figjam_create_shape_with_text and figma_add_text_to_slide, but no sibling is named or contrasted.

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

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

The description only implies when to use it via the verb 'Add'; there is no explicit when-to-use statement, no prerequisites (e.g., a valid slide must exist), and no routing away from alternatives like figma_add_text_to_slide or figjam_create_shape_with_text.

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

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

With no annotations, the description carries the burden and does substantial work: it discloses structural preconditions that will cause failure, and explains that fileKey changes the target without altering the active file or target lock, plus Cloud Mode rejection. It stops short of saying what happens if a slot property with that name already exists, or what the tool returns.

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

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

Front-loaded with the action and the alternative, then the constraints, then a clearly labeled mode-specific block. The multi-file paragraph is somewhat verbose and duplicates the fileKey schema text, but the structure makes skimming easy.

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 mutation tool with no annotations and no output schema, the description supplies preconditions, optional-feature scope, and mode behavior. The remaining gap is error semantics (duplicate property name, invalid frame) and confirmation of what mutation is persisted.

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 every parameter is already documented in the schema, and the description's mention of 'description and preferredValues' plus the fileKey paragraph largely restates it. The only marginal addition is the SLOT-only scoping of the optional fields. Baseline 3 applies when the schema does the heavy lifting.

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

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

Opens with a specific verb+resource ('Manually add a SLOT component property') and immediately scopes it as the manual alternative to figma_create_slot, a real sibling in the list. An agent can distinguish it from figma_add_component_property and figma_create_slot without opening either schema.

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

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

Names the alternative (figma_create_slot) and enumerates hard preconditions: the frame must be a direct child of the component, must not use GRID layout, and must not be nested inside another slot. It does not explicitly state the condition under which the other tool should be preferred, which keeps it short of a 5.

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

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

With no annotations provided, the description carries the full behavioral burden. It states that formatting options are supported but does not disclose permissions needed, error behavior for invalid slide IDs, whether the operation returns the created node, or any side effects. For a mutation tool with 13 parameters, this leaves significant behavioral gaps.

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

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

The description is two efficient sentences with the core action front-loaded. The second sentence summarizing supported formatting categories is somewhat redundant with the schema but still serves as a quick capability overview. 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 creation tool with 13 parameters and no output schema or annotations, the description covers what the tool does but omits the return value, error conditions, and positioning context. The schema fully covers parameter semantics, so the remaining gap is primarily behavioral rather than parametric, making it minimally adequate.

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 13 parameters in detail. The description adds a high-level summary of font, color, alignment, and formatting support but no syntax, defaults, or parameter-specific meaning beyond what is already in the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description gives a specific verb and resource: "Add a new text element to a specific slide." This clearly distinguishes creation from mutation siblings like figma_set_text, though it does not explicitly name or contrast alternatives. The second sentence adds capability scope, making the purpose easy to grasp.

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 explicit guidance on when to use this tool versus alternatives such as figma_set_text or figma_add_shape_to_slide. Usage is only implied by the phrase "Add a new text element to a specific slide," with no exclusions or preconditions 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?

No annotations are present, so the description carries the full burden; it does disclose the environment prerequisite and enumerates in detail what the operation produces, which is the behavior an agent most needs here. It does not explicitly state that the call is read-only/non-mutating or whether it is expensive on large sets, which leaves a small gap for an unannotated tool.

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

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

Purpose and node scoping are front-loaded, but the return-value enumeration becomes a dense run-on with deeply nested parentheses and backticked property names, making it hard to scan. Because there is no output schema the detail is earned, yet it could be restructured into a short list instead of one sprawling sentence.

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

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

With no output schema and no annotations, the description supplies exactly what would otherwise be missing: the shape of the response across five numbered categories, the node-type constraint, and the plugin prerequisite. An agent can decide whether to call it and predict the payload without further information.

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

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

Schema coverage is 100% with a single required nodeId already documented as a COMPONENT_SET node ID, so the schema does the heavy lifting. The description reinforces the constraint that it must be the parent node rather than a variant, which adds a real usage guard 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?

States a specific verb and resource — analyze a Figma COMPONENT_SET to extract a variant state machine, cross-variant diffs, property mappings and slots for code generation — which is a distinctive, non-tautological purpose. The scope is clear enough that an agent knows what comes back, but it never distinguishes itself from plausible siblings doing adjacent work (figma_get_component_details, figma_ds_extract_component, figma_get_component_for_development_deep).

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 when-not: 'Use this on the parent COMPONENT_SET node, not individual variants,' plus a hard prerequisite ('Requires Desktop Bridge plugin'). It does not name any alternative tool to use when the node is not a COMPONENT_SET, so the routing guidance is clear but not complete.

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

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

With no annotations, the description carries the full burden and does disclose the important side effects: passing fileKey does not change the active file or target lock, and Cloud Mode rejects fileKey outright. It also flags which node kinds cannot be appended. It stops short of describing what the call returns or what happens to the appended node's position/layout, which matters for a 9-param mutation.

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

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

Front-loaded with the core action, then the constraint, then a clearly headed MULTI-FILE paragraph. The fileKey sentence largely duplicates the schema's own description verbatim, which is the only real 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 a 9-parameter, zero-required, no-output-schema tool, the description supplies the missing decision logic: two creation modes, the sibling it replaces, exclusions, and the multi-file targeting rule. No return-value documentation is needed since no output schema exists and the tool's effect is the appended content itself.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics by framing sourceNodeId and nodeType as two mutually exclusive modes and calling out that clone defaults to true (false moves rather than copies). It does not state that slotId or the instanceId+slotName pair is the required addressing combination, which is the main unanswered parameter question.

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 content to a slot on a component instance', and immediately explains the two underlying mechanisms (clone sourceNodeId or create via nodeType). It explicitly distinguishes itself from figma_set_instance_properties and cites the negative cases (widgets, stickies, raw ComponentNodes), so an agent can separate it from siblings 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 explicit routing: SLOT content cannot be set via figma_set_instance_properties, use this tool instead, and names figma_list_open_files for fileKey sourcing. It also states exclusions (widgets, stickies, raw ComponentNodes) and cross-references figma_get_slots for slotId, 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?

With no annotations, the description carries the behavioral burden and does well: it discloses that keyframe tracks replace existing tracks for a target, explains easing and duration variable binding, warns that main components cannot be animated, and clarifies that motion appears in preview/video export rather than static screenshots. It does not cover permissions, failure modes, or return behavior, so it is strong but not complete.

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 action and the mutually exclusive modes, then uses tight bullets for each mode and a final constraint note. Every sentence carries relevant information and there is no boilerplate.

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 complex nested schema and lack of annotations, the description covers the critical usage modes, constraints, and visual-output limitation. It stops short of describing success/return behavior or failure cases, which is a minor gap for a mutation tool without 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?

Schema coverage is 100%, so the schema already documents individual parameters. The description adds important cross-parameter semantics by requiring exactly one of preset, customStyleId, or keyframeTracks, and by explaining how easing and duration can bind to variables.

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

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

The description uses a specific verb and resource: 'Animate a node with Figma Motion.' It immediately distinguishes the tool's modes and routes preset discovery to figma_manage_animation_styles, so 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?

The 'Pass exactly one of' instruction gives clear mode-selection guidance for preset, customStyleId, and keyframeTracks. It also states that main components cannot be animated and must use an instance or frame, but it does not explicitly contrast this tool with sibling tools such as figma_get_animations, figma_remove_animation, or figma_export_animation.

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

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

With no annotations, this description carries the full burden and does well: it discloses that unknown property names change nothing and return the valid names, that replace:true discards the existing list, and that Desktop Bridge is required. It omits what the call returns on success and any limits on shader counts, keeping it just short of full disclosure for a mutation tool.

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

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

Front-loaded with the core action, then progressively refined into property syntax, index/replace behavior, target mapping, and failure behavior. Dense with parenthetical clauses, but essentially every sentence adds operative 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 10-parameter, nested-object mutation tool with no annotations and no output schema, the description covers the risky parts: destructive replace, index-based mutation, valid property discovery, variable binding, and the Desktop Bridge prerequisite. Only the success response shape and the interaction with Cloud vs Local Mode (documented only in the fileKey schema) are left unaddressed.

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 70% schema coverage, the description adds real meaning beyond the schema: the properties object is by name with a concrete example ({turbulence: 40, cloudColor: '#E8F4FF'}), colors accept hex strings or {r,g,b,a}, and any property can bind a variable via {variableId}. Index, replace and target semantics are restated compactly, though opacity/blendMode constraints merely echo what the schema already says.

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

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

States a specific verb and resource: apply a shader to a node's fills, strokes or effects, or mutate properties of an already-applied shader. The scope is precise enough to distinguish it from siblings like figma_set_fills or figma_list_shaders, which is named as the source of property metadata.

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

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

Gives clear routing rules: pass index to modify an existing shader, omit it to add on top, or use replace:true to swap the whole list; fill shaders go on fills/strokes, effect shaders on effects. It also points at figma_list_shaders for names/types/defaults and notes the Desktop Bridge requirement. It stops short of naming an alternative for non-shader fill/stroke work (e.g. figma_set_fills), so exclusions are 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?

With no annotations, the description carries the full burden and does so well: it states the operation is non-destructive, rearranges existing variants in place, preserves the node ID and instances, wraps the set in a labeled container, and is safe to re-run. These details give an agent the key behavioral profile needed before invoking a mutation.

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 purpose and usage, then follows with safety and layout behavior. It is appropriately sized and every sentence contributes 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 mutating layout tool with no annotations and no output schema, the description covers the important gaps: what it changes, what it preserves, how the grid is organized, and its repeat-run safety. Nothing essential for correct invocation 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?

The input schema has 100% description coverage, so gap, cellPadding, componentSetId, componentSetName, and columnProperty are already well documented. The description adds useful layout semantics about columns and rows, but does not add parameter-level meaning beyond the schema, so the baseline 3 is appropriate.

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

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

The description uses a specific verb and resource ('Organize a component set') and explains the purple dashed/grid layout it applies. It is clear what the tool does, but it does not explicitly name or differentiate itself from sibling tools such as figma_create_component_set or figma_analyze_component_set.

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 timing guidance: use after creating variants, adding states, or when component sets need cleanup. It also notes safety with placed instances and re-runs, though it does not name alternatives or state when not to use it.

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

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

With no annotations, the description carries the burden and does well: it discloses the audit's output (per-category scores and prioritized recommendations), the scope of checks, and the environmental dependency (Desktop Bridge). It stops short of stating explicitly that the operation is read-only / non-mutating on the document, which is the one behavioral fact left implicit.

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: purpose first, then the enumerated categories, then when-to-use and prerequisite. The long category list earns its place by defining audit scope, though it is the bulkiest portion and could be tightened.

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 read-only audit tool with no output schema, the description supplies what matters: the categories inspected, the shape of results (scores plus prioritized recommendations), the prerequisite, and the timing guidance. Whether it mutates the file is the only unaddressed 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 100%, so both parameters (nodeId with its fallback-to-selection behavior, targetSize with WCAG 2.5.8 default and platform overrides) are already documented in the schema. The description adds no parameter-level detail beyond that, 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 names a specific verb (audit) and a specific resource (component/component set), then enumerates the exact categories checked and the return shape (per-category 0-100 scores plus prioritized recommendations). This separates it cleanly from siblings like figma_lint_design or figma_scan_code_accessibility, which operate at file or code level.

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 clear usage window ('use after designing a component to validate accessibility before handoff') and a hard prerequisite ('Requires Desktop Bridge plugin'). It does not name an explicit alternative or state when-not to use it, which keeps it below a 5.

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

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

With no annotations, the description carries the burden and mostly does: it discloses the ~5 minute audit cache and when to bypass it with forceRefresh, and that payloads are chunked to avoid a giant response. It implies read-only operation (fixes happen via separate design-side write tools) but never states it outright, nor how long a cold audit takes or what happens on an invalid/unreachable file.

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 its result, then descends into categories, drill-down, caching, and the fixability tagging. Dense but every sentence carries information; the em-dash stacking and semi-colon lists make it slightly harder to scan than it needs to 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?

There is no output schema, so the description does real work describing the return shape: six 0-100 category scores plus a weighted overall, non-pass findings with remediation, and a per-finding fixability classification. Gaps remain on response size, error/failure modes, and whether the score is comparable across runs.

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 it by explaining the intent of the `category` parameter as the chunked drill-down path after a summary call, and by tying `forceRefresh` to the editing workflow. It adds workflow meaning rather than merely restating the enum values.

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: run a design-system health audit and return a scored report as data, with the six scored categories and weighted overall spelled out. It differentiates from the Design System Dashboard app ("no UI required", "same deterministic engine"), but never names the similarly-scoped siblings such as figma_lint_design, figma_ds_verify, or figma_get_design_system_summary.

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 sequencing ("Start with the default summary, then drill into one category at a time via `category`") plus the forceRefresh condition after editing the file, and the schema repeats "prefer per-category calls over 'full'". What's missing is any exclusion or comparison against the adjacent audit/lint tools an agent might otherwise choose.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the performance rationale and the Desktop Bridge dependency, but does not say whether partial failures are atomic, what happens on duplicate names, or what the operation returns. For a mutation tool this leaves meaningful behavioral gaps.

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

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

Four short sentences, front-loaded with the core action and followed by the alternative, prerequisite, and dependency. Every sentence adds actionable information with no filler.

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

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

The definition covers purpose, prerequisite, and plugin requirement, which is enough to attempt a call. However, with no annotations and no output schema, it should say more about mutation behavior such as partial failure handling, duplicate handling, and what is returned (e.g., created variable IDs).

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 the parameters, including per-variable fields, enum semantics, and value formats. The description adds a useful pointer for sourcing collectionId but no additional parameter-level meaning. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Create multiple variables') plus scope ('in one operation') and explicitly distinguishes itself from figma_create_variable by naming it as the repeated-call alternative. An agent can select this over the single-create sibling without inspecting 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?

Explicitly says to use this instead of calling figma_create_variable repeatedly and gives a prerequisite: get collection IDs from figma_get_variables first. It also states the Desktop Bridge plugin requirement. It stops short of naming when not to use it (e.g., use figma_batch_update_variables for existing variables) or what to do above the bulk limit.

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

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

With no annotations, the description carries the burden and does disclose two critical operational facts: the Desktop Bridge plugin requirement and that IDs must be sourced beforehand. It stops short of stating atomicity or per-item failure behavior for a batch mutation, which is the kind of context an agent would want before sending 100 updates.

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 sentences, each front-loaded with a distinct fact: purpose, alternative, prerequisite, environment requirement. Nothing repeats the schema or the name.

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

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

For a single-parameter mutation tool with no output schema and no annotations, the description covers purpose, prerequisites, and environment. The remaining gap is outcome behavior (partial failures, confirmation of applied updates), which matters at the 100-item batch scale but is a minor 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?

Schema coverage is 100% and the nested item descriptions already explain value formats per variable type and the ID formats, so the schema does the heavy lifting. The description adds the provenance of the IDs but does not mention the 1-100 array bound that the schema enforces, 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?

States a specific verb (update), resource (variable values), and scope (multiple in one operation), which immediately distinguishes it from the singular figma_update_variable and from figma_batch_create_variables. The title/sibling set leaves no ambiguity about what this does.

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 names the alternative it replaces ('Use instead of calling figma_update_variable repeatedly') with the reason (bulk speed), and gives a prerequisite step ('Get variable/mode IDs from figma_get_variables first'). That is a complete when-to-use and how-to-prepare instruction.

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

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

With no annotations present, the description carries the full burden and does well: it discloses the binary-search cost profile (~log2(N) API calls instead of N), the autosave default and why it improves attribution, and a known quirk (system 'Figma' user flagged via attribution_certainty='system_attributed'). It omits auth/permission requirements and what happens when no introduction point is found within max_versions_to_walk.

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

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

Front-loaded with the core purpose, then progressively narrower operational detail; every sentence conveys facts (cost model, return fields, autosave behavior, target constraint, fallback). Dense but slightly overpacked — the autosave and system-attribution points could be tightened without losing information.

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

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

Covers what an agent needs for a 7-parameter, zero-required, no-output-schema tool: what it returns (label/author/timestamp metadata), the cost of running it, target-selection rules, selection fallback, and a known attribution edge case. The absence of an output schema is compensated by the explicit return-description sentence.

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 100%, so baseline would be 3, but the description adds a genuine cross-parameter constraint absent from the schema: mutual exclusivity of target_component_property and target_child_node_id, and the node_id-to-selection fallback. It also explains the rationale for include_autosaves, which the schema only asserts.

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?

Uses a specific verb ('Find the version that introduced a specific change') plus a plain-language gloss ('answers who/when added this') that removes any ambiguity about the tool's output. The resource is precisely scoped to a node's history, which is distinguishable from siblings like figma_get_file_versions or figma_diff_versions by the attribution framing.

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

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

Gives clear context ('answers who/when added this') and a hard usage rule ('Specify EXACTLY ONE of target_component_property or target_child_node_id'), plus a fallback when node_id is omitted. However, it never names an alternative tool or says when NOT to use this — an agent choosing between blame, figma_diff_versions, and figma_get_changes_since_version gets no routing help.

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

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

With no annotations, the description does substantial work: it discloses that captures reflect current plugin-runtime state rather than cloud state, that downscaling is automatically applied to stay under the AI vision ceiling, and that a Desktop Bridge connection is required. It stops short of describing the return payload or failure modes.

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

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

The description is front-loaded with the core action and the important runtime-state caveat. Some sentences, such as the PNG compression rationale and JPG guidance, overlap with schema documentation or could be trimmed, but the overall structure is clear.

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

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

For a three-parameter screenshot tool with no annotations and no output schema, it covers the key context: plugin-runtime state, connection prerequisites, default export behavior, and an alternative tool. Return format and error behavior are not described, which keeps it from being fully complete.

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

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

Schema coverage is 100%, so all three parameters, their defaults, and the format enum are already documented in the schema. The description reinforces the AI-optimized defaults and format-choice rationale, but it largely repeats schema content rather than adding new parameter semantics.

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: capture a screenshot of a node using the plugin's exportAsync API. It also distinguishes plugin-runtime capture from cloud-state alternatives and explicitly contrasts itself with figma_get_component_image, making the tool's purpose easy to identify.

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 usage guidance: use this tool to validate changes immediately after making them, and use it instead of figma_get_component_image when verifying applied changes. It also explains the current-plugin-runtime context and when to choose JPG over PNG.

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

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

No annotations exist, so the description carries the full burden. It discloses return structure and that fix items target design-side (Figma calls) or code-side (file edits) depending on canonicalSource, which is meaningful. But it never clarifies whether the tool itself mutates anything or that fix items are advisory only.

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

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

Three tight sentences, front-loaded with the purpose before the workflow hint. Alternating between purpose and result contents is efficient with minimal 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 a complex nested-input tool with no output schema, the description does sketch the return shape (score, categorized discrepancies, fix items). But it does not explain the discrepancy categories or the parity score semantics, so an agent still has uncertainty about interpreting results.

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

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

Schema description coverage is 100%, so the nested codeSpec structure is already well documented field-by-field. The description adds only the workflow hint about filling codeSpec after reading source, which the schema partly implies. Baseline 3 for high-coverage schemas is appropriate.

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

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

States a specific verb+resource+goal: comparing a Figma component's design specs against code-side data to find discrepancies. It also names the return payload (parity score, discrepancies, fix items). It does not differentiate from related siblings like figma_ds_verify or figma_audit_design_system_report, so a 4 rather than 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?

Provides a concrete prerequisite ordering ('Read the component source code first, then pass the data in codeSpec'), which is genuinely useful usage context. However it gives no when-to-use vs when-not guidance and never routes the agent toward or away from alternatives such as figma_ds_verify.

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

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

With no annotations provided, the description carries the burden and does useful work: it discloses that the operation is safe, that it does not disrupt the plugin connection, and that it returns a count of cleared logs. It stops short of stating whether the discarded logs are recoverable, but for a zero-parameter buffer reset that is a minor gap.

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

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

Three short sentences, front-loaded with the action, followed by the safety caveat and the return value. No wasted words.

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

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

For a zero-arg, no-output-schema utility, the description covers action, side effects, and return value. There is nothing an agent needs in order 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?

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. Nothing in the description conflicts with the empty 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?

Names a specific verb and resource: 'Clear the console log buffer', which is unmistakable and immediately distinguishable from the read-oriented siblings figma_get_console_logs and figma_watch_console in practice. It does not explicitly call out those siblings, so it stops short of a 5.

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

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

The description never says when to clear versus when to read or stream logs, and names no alternatives. An agent must infer the workflow (e.g., clear before reproducing an issue) entirely from the tool name.

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

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

With no annotations provided, the description carries the full disclosure burden. It usefully states that 'the clone is placed at a slight offset from the original,' which is behavior beyond the input schema, but omits permissions, reversibility, whether the original is preserved, and what the tool returns.

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

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

The description is two short sentences with the core action front-loaded and the offset behavior immediately following. Every sentence adds useful information without 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 a one-parameter mutation tool with no annotations and no output schema, the description is minimally adequate. However, it does not state where the clone is parented, whether the original remains unchanged, or what the tool returns, leaving some gaps for the agent.

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

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

The schema has 100% description coverage for the single nodeId parameter, so the schema already documents the parameter fully. The description does not add further meaning or constraints beyond that baseline.

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

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

The description states a specific verb and resource: 'Duplicate a node.' This is clearly distinct from deletion or creation tools, though it does not explicitly differentiate from another duplication-oriented sibling such as figma_duplicate_slide.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives like figma_create_child or figma_duplicate_slide. It relies on the user inferring that duplication is the intended operation.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the parent-container invariant and mentions cleanup of empty or orphaned nodes on failure, but it omits permissions, return behavior, and whether cleanup itself is destructive.

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

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

The description is four short sentences, front-loads the purpose, and then adds constraints and failure behavior. Every sentence contributes useful guidance 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?

It gives enough information to invoke the tool correctly with a valid parent and node type, and the nested properties are fully documented in the schema. Minor gaps remain around the return value and the exact cleanup semantics, but the core call requirements are covered.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful parentId semantics by requiring the parent to be a Section or Frame rather than any node. It does not add further detail for the nested properties, but the schema already documents those.

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 gives a specific verb and resource: create a new child node inside a parent container. It is clear what the tool does, but it does not explicitly distinguish itself from sibling creation or cloning tools such as figma_clone_node or figma_create_component_set.

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 a strong usage constraint: the parent must be an existing Section or Frame and never a bare page. It also gives a fallback action, creating a Section first, but does not explicitly compare to alternative sibling 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?

With no annotations, the description carries the full burden and does so: it discloses the clone-per-combination side effect, that the base keeps its node ID so existing instances survive, that property definitions live on the set rather than variants, that components already in a set are rejected, the 100-variant cap, timeout auto-scaling, and the Desktop Bridge plugin requirement for autoArrange.

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

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

Front-loaded with the core action, then cleanly sectioned into Two modes and SIZE GUIDANCE, so an agent can skim to the relevant mode. It is on the long side and the size-guidance paragraph could be tightened, but the detail is load-bearing for a 9-parameter tool with no annotations.

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

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

No output schema exists, and the description compensates by stating what the result contains (each variant's key) and the critical follow-up that you must instantiate with a variant's key/nodeId via figma_instantiate_component rather than the set's key. Combined with mode coverage, limits, and prerequisites, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by explaining the expansion semantics of `properties` (a concrete 2-axis → 6-variant example) and the 1:1 index alignment of variantProperties, plus the naming convention that Figma derives. It does not add much for name/parentId/position, which is acceptable given the schema already documents 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?

Opens with a specific verb + resource ("Create a component set with variants in one call") and immediately frames it against the manual alternative (hand-written figma.combineAsVariants scripts). The two numbered modes make it unambiguous which creation path is being invoked, including the destructive side effect that the base component becomes a variant.

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 between the two modes (baseComponentId + properties vs componentIds ± variantProperties) and states the mutual exclusivity, plus a concrete size heuristic (split above ~40 variants, hard cap 100). It stops short of naming a sibling tool it should be chosen over instead, so no exclusion 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does disclose that the slide is blank and grid placement is optional, but it does not state default placement (for example, appended at the end of the deck) or permission requirements. This is a moderate gap rather than a serious omission.

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 waste, and the core action is front-loaded before the optional parameter 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?

This is a simple creation tool with two optional, fully documented parameters and no output schema, so it does not need much more. The only missing piece an agent might want is default slide placement when row/col are omitted.

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%, and both col and row are already documented as 0-based grid indices. The description adds only that grid position is optional, so the baseline of 3 is appropriate.

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

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 a new blank slide in the Figma Slides presentation.' This distinguishes it from siblings such as figma_duplicate_slide and figma_add_text_to_slide, which modify or populate existing slides. It does not explicitly name a sibling, which keeps it below 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?

The description never states when to use this tool versus alternatives (figma_duplicate_slide for copies, figma_add_text_to_slide for content). The clause 'Optionally specify grid position' is a parameter note, not usage guidance.

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

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

With no annotations, the description carries the full burden and does so: it discloses the automatic linked SLOT component property and the rename coupling, the GRID restriction, the Desktop Bridge dependency, and fileKey's Local-Mode-only semantics including that it does not change the active file or target lock and is rejected in Cloud Mode. Nothing an agent needs for safe invocation is omitted.

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 behavior, with the multi-file caveat relegated to a clearly labeled trailing section. It is dense but earns most of its length; the fileKey discussion repeats some schema text rather than trusting 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 six-parameter mutation tool with no annotations and no output schema, the description covers creation effects, constraints, environment requirements, and multi-file semantics. It does not mention what is returned (e.g., the new node ID) or how the slot's initial size defaults behave, which is a minor residual 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 description coverage is 100%, so all six parameters, including the fileKey and layoutMode enum, are already documented in the schema. The description adds only marginal semantic value beyond that, notably that the slot name propagates to the component property name. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Create a SlotNode inside a component using createSlot()') and immediately differentiates it from alternatives by contrasting slots with INSTANCE_SWAP as freeform drop zones. An agent knows exactly what this creates 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?

Explicitly scopes applicability: standalone COMPONENTs, variant COMPONENTs inside a COMPONENT_SET (once per variant), GRID layout disallowed, and Desktop Bridge required. It also routes multi-file usage to figma_list_open_files. It stops short of explicitly contrasting with nearby siblings like figma_add_slot_property or figma_append_to_slot, so not a full 5.

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

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

No annotations are provided, so the description carries the full burden. It does disclose a real operational prerequisite (Desktop Bridge plugin required) and the cross-tool dependency on figma_get_variables, which is valuable. However, it says nothing about mutation semantics such as duplicate-name behavior, whether the variable is created across all modes, or what happens on failure — gaps that matter for an unannotated write tool.

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

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

Four short sentences, each carrying distinct actionable information: what it does, when to use the alternative, the prerequisite lookup, and the type surface. No filler and the single-vs-batch distinction is front-loaded.

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

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

There is no output schema, and the description never says what is returned (presumably the new variable's ID), which an agent may need for follow-up calls. Otherwise the prerequisites, id source, and supported types make the definition sufficient for a 5-parameter creation tool.

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

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

Schema description coverage is 100% and the schema already documents every parameter, including detailed TIMING/EASING formatting and a valuesByMode example, so the baseline is 3. The description's type list ('COLOR, FLOAT, STRING, BOOLEAN, and motion TIMING/EASING') merely restates the enum and adds no syntax or constraint beyond what the schema provides.

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 single Figma variable') and immediately scopes it to one variable, distinguishing it from figma_batch_create_variables and figma_create_variable_collection. An agent knows exactly what this does 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?

Explicitly names the alternative ('use figma_batch_create_variables instead (10-50x faster)'), gives the prerequisite call ('Use figma_get_variables first to get collection IDs'), and states the environmental requirement (Desktop Bridge plugin). All three conditions that gate correct invocation are 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?

No annotations are provided, so the description carries the full burden. It usefully discloses that the resulting collection is empty and the plugin requirement, but says nothing about duplicate-name handling, whether modes are auto-created, or what identity is returned for the new collection.

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 tight sentences. The core action and the 'empty' constraint come first, the alternative routing second, and the plugin prerequisite last — every clause 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?

For a simple 3-parameter creation tool with full schema coverage and no output schema, the description covers action, scope, alternative, and prerequisite. The remaining gap is mutation behavior (collision handling, confirmation of created mode names), which no structured field 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 description coverage is 100%, so all three parameters (name, additionalModes, initialModeName) are already documented with examples. The description adds no syntax or constraint detail beyond 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+resource ('Create an empty variable collection') with a scope qualifier ('empty') that distinguishes it from the batch/setup path. It also names the sibling it is not, so the agent can differentiate without opening schemas.

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

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

Explicitly routes the agent: use figma_setup_design_tokens when variables and modes are needed in one step, otherwise this tool. The runtime prerequisite ('Requires Desktop Bridge plugin') is stated up front so the agent knows the invocation precondition.

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

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

No annotations are present, so the description carries the full burden, and it discloses almost nothing behavioral: not whether deletion is permanent, not whether replies in a thread are removed, not whether the caller must own the comment or hold edit permission, and not what is returned. 'Delete' implies mutation but the risk profile is left to inference.

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

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

Two sentences, no filler, with the core action stated first and the prerequisite second. Every clause 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?

For a destructive single-target mutation with no annotations and no output schema, the description is thin on consequences and permissions even though the parameters themselves are fully covered by 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 description coverage is 100% and both fields (fileUrl default behavior, comment_id source) are already documented in the schema. The description adds no syntax, format, or constraint 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?

Specific verb (delete) plus resource (comment) plus the identifier used to target it, with the containing file scope. It is immediately distinguishable from figma_get_comments and figma_post_comment in the sibling list.

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 to figma_get_comments as the way to obtain a comment ID before calling. There is no statement of when not to use it (e.g., thread replies, permissions), so it stops short of full guidance.

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

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

No annotations are provided, so the description carries the full burden, and it does disclose that this is destructive and which property types are valid. It stops short of stating irreversibility, what happens to instances bound to the deleted property, or any permission requirements.

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 short sentences, front-loaded with the action, then the type scope, then the risk warning. No wasted words.

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

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

For a simple two-parameter tool with a fully documented schema and no output schema, the description covers purpose, valid property types, and the destructive nature. Only irreversibility/instance-impact detail is missing, which is minor 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 100%, so both parameters (nodeId, propertyName) are already documented in the schema, including the suffix format example. The description adds no additional per-parameter meaning beyond what the schema provides, 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?

States a specific verb (Delete) and resource (component property), and further scopes it with the supported property types (BOOLEAN, TEXT, INSTANCE_SWAP, SLOT) while excluding VARIANT. This clearly distinguishes it from the add/edit component property siblings.

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

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

The type restriction ('not VARIANT') implies when the tool is applicable, and the naming makes the add/edit alternatives apparent. However, there is no explicit statement of when to use this versus figma_edit_component_property or any prerequisite/confirmation 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?

Since no annotations are provided, the description carries the full behavioral burden. It explicitly states the operation is 'destructive' and includes the crucial mitigating detail that the action can be undone with Figma's undo feature.

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