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

Annotations cover the safety profile (write, destructive, non-idempotent), and the description adds substantial context they cannot carry: every call is a full model turn so batch the whole change, responses over max_output_bytes are shrunk with the full value in bridge.state.lastResult, overlay appearance is read-only and yields a manual step, and state persists between calls via bridge.define/require. It also discloses hazards: never eval, never findAll the whole page, never assign `characters`.

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 critical framing (WRITE tool, use figma_inspect to read, do it in one call) is front-loaded, but the body is a dense semicolon-chained wall enumerating every bridge macro, which is hard to scan. Most sentences carry load-bearing information, yet the macro catalog dilutes the routing guidance an agent needs first.

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, high-destructiveness write tool with no output schema, the definition covers execution model, return-value behavior, size limits, batching expectations, and the read/write split against siblings. Nothing an agent needs to invoke it safely or correctly is missing.

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

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

Schema coverage is 100%, so parameters are already documented. The description still adds real meaning: it specifies the sandbox globals available inside `code` (figma, ensureFont, getFreePosition, bridge) and the specific bridge macros to prefer over raw Plugin API calls, plus where to put capture_node_ids and why output size matters.

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 an explicit label ('WRITE tool') and a precise verb list (create, edit, move, style, delete) against a named resource (nodes in the open Figma document). It immediately draws the boundary against the sibling that could be confused with it (figma_inspect for reads).

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

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

States when to use the alternative explicitly ('To READ ... call figma_inspect instead') and enumerates the read tasks that belong there (list children, find layers, check fonts/variants/table columns). It also routes specific sub-tasks to other tools/calls: capture_node_ids instead of a separate figma_screenshot, and figma_job_status for async results.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavior: it enumerates what comes back (names, variant values, keys, IDs) and states the context-protection intent, which matters because there is no output schema.

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

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

Two sentences, front-loaded with the verb and resource scope, then the distinguishing constraint and return payload. Nothing is redundant with the title or schema.

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

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

For a six-optional-parameter, zero-required read tool with no output schema, the description covers scope and return shape adequately, and cache/index details are correctly delegated to the schema and instructions. Pagination or result-count behavior beyond the limit parameter is not addressed, keeping it from a 5.

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 including caching semantics and the variants toggle is already documented. The description adds no syntax, format, or default information 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?

Uses a specific verb ('Find and inspect') with an enumerated resource set (components, component sets, variants, property definitions) scoped to the active Figma file, which distinguishes it from single-node figma_inspect and from figma_get_variables. It stops short of naming a sibling alternative explicitly, so it lands at 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?

Usage is implied by the goal statement ('without flooding LLM context') and by the schema pointing to figma_list_targets for the target param and figma_read_canvas for index behavior. The description itself gives no explicit when-to-use / when-not-to-use guidance or named alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the bar is lower. The description adds that it returns coordinates, a bounding box and a computed suggested position, but it never clarifies that the layout/gap/columns/direction parameters only shape the *suggestion* and do not mutate the canvas — a real ambiguity for a tool whose name implies layout changes.

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, front-loaded with the purpose followed by the return payload, with zero filler. Nothing in the text is redundant with the schema or annotations.

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

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

For a six-parameter read tool with no output schema and no annotations gap, the description should at least sketch the shape of the returned frame list and explain the relationship between the layout parameters and the suggestion. It covers the return values at a headline level but leaves the parameter-to-output mechanics and the overlap with sibling read tools unexplained.

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 including the two enums is already documented in the schema; baseline 3 applies. The description contributes nothing about how gap, layout, columns or direction interact with the suggestedNextPosition calculation, so it adds no meaning beyond the structured fields.

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

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

The description names a concrete verb and resource ('Inspect top-level frames and artboards on the active Figma page') and states the derived output ('suggestedNextPosition'), which is far more specific than the tool name alone. It does not, however, distinguish itself from overlapping siblings such as figma_read_canvas or figma_inspect, so an agent cannot tell from the description which one to reach for.

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

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

Usage is implied by the phrase 'to prevent overlap' and 'for placing new artboards safely', giving a motivation but not a decision rule. There is no explicit when-not guidance and no alternative tool named, even though figma_read_canvas and figma_get_selection are plausible substitutes.

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

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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so the bar is lower, but the description still adds value by enumerating what the payload contains (dimensions, coordinates, text, fills, parent, page, AutoLayout context). It does not state what happens when nothing is selected (empty result vs error), which is the main remaining behavioral gap.

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

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

One front-loaded sentence with the verb first and the property list tucked into a parenthetical; nothing is wasted. The parenthetical enumeration is dense but each item carries real information.

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

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

With no output schema, the description must convey return contents, and the property list does that adequately for a read-only, zero-required-param tool. Only the empty-selection behavior and shape of the returned structure are left unspecified.

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?

There is a single optional parameter whose schema description is fully covered (100%) and already points at figma_list_targets. The description adds nothing 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?

States a specific verb (get) and resource (currently selected nodes on the Figma canvas) and enumerates the properties returned, which lets an agent distinguish it from selection-agnostic siblings like figma_read_canvas or figma_inspect. It stops short of explicitly contrasting itself 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?

Usage is implied by the phrase 'currently selected nodes' – the tool only makes sense when something is selected – but there is no explicit statement of when to prefer this over figma_inspect, figma_read_canvas, or figma_screenshot. No prerequisites or exclusions are given.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds useful framing (scope spans all collections, modes and all four token types) but omits return shape, whether truncated results are signaled, and how the default limit behaves when exceeded.

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 front-loaded sentence with no filler; the resource scope lands first and the token-type enumeration is compact and informative.

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

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

With no output schema, the description carries the burden of describing return content, and it does name collections, modes and token value types. It stops short of describing result structure or truncation behavior at the 300-token default, which would matter on large design-token files.

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 are fully documented in the schema itself (limit default 300, target fileName, collection_name filter). The description adds no syntax, format, or filtering semantics beyond that, so the baseline 3 applies.

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

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

States a specific verb (Retrieve) and a precise resource (Figma Variable collections, modes, design tokens) with the token types enumerated. An agent can distinguish it from mutation sibling figma_set_variables_mode or canvas readers like figma_read_canvas without opening any schema.

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

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

Usage is only implied — the reader infers 'call this when you need design tokens'. There is no explicit when-to-use, when-not-to-use, or named alternative; the reference to figma_list_targets appears only inside a parameter description, not in the tool description.

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

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

Annotations already cover the safety profile (readOnly=false, destructive=false, idempotent=false), and the description adds genuine context beyond them: auto font loading when applying text overrides, the PNG screenshot return path via capture:true, and the AutoLayout insertion target. It stops short of stating what happens on duplicate insertion or undo semantics.

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

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

Two front-loaded sentences with no filler: the first establishes the action and destination, the second enumerates the optional capabilities. Nothing redundant with the schema is repeated.

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, nested-object tool with no output schema, the description covers the outcome (inserted instance) and notes the optional PNG return, which substitutes for missing return documentation. It omits multi-document targeting and placement fallback behavior, but those are covered in the schema.

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

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

Schema coverage is 100%, so all nine parameters including nested position/properties are documented in the schema, which sets the baseline at 3. The description adds only marginal meaning beyond that: it names variant selection and auto font loading for text_overrides, but does not clarify position/index behavior or scale 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?

States a specific verb+resource: create and insert an instance of a master component or component set into canvas or an AutoLayout container. This distinguishes it implicitly from figma_insert_svg (SVG content) and figma_find_components (discovery), though no sibling is named explicitly.

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

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

Usage is only implied by the description ('insert an instance... into the canvas or target AutoLayout container'). It notes capture:true for visual verification but never says when to prefer this over figma_find_components for discovery or figma_insert_svg for raw assets, and gives no prerequisites or exclusions.

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

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

Annotations already declare non-readOnly, non-destructive, non-idempotent, and closed-world behavior. The description adds useful context beyond annotations: automatic scale-proportional resizing, fill/stroke overrides, optional component creation, and optional PNG screenshot return. It does not mention permission requirements or effects on existing canvas selection.

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 front-loaded sentence that names the core action and key options without filler. It is dense but every clause maps to a real capability or parameter.

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 13-parameter tool with a nested position object and no output schema, the description plus full schema coverage is sufficient for correct invocation. It omits what the tool returns beyond the optional PNG screenshot, but annotations and schema carry the remaining safety and parameter detail.

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 thoroughly. The description mentions overrides, component creation, capture, and AutoLayout placement, but mostly restates capabilities already covered by the schema and adds no precedence rules for competing color overrides.

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 (Insert) and resource (raw SVG/vector code) and scopes it to the Figma canvas or a target AutoLayout container. It does not explicitly compare itself to related tools such as figma_insert_component_instance, so sibling differentiation is indirect.

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 no explicit when-to-use or when-not-to-use guidance and does not name alternatives like figma_insert_component_instance or figma_execute_code. Usage is only implied by the tool's action and optional features.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description confirms with "Changes nothing." rather than contradicting. Beyond that it discloses non-obvious behavior the annotations can't: the default is a truncated compact outline, truncation ends with "… pass offset=K", and max_output_bytes caps spill at 3900 — the things that actually bite an agent on a read 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 correctly — the one-call, use-this-not-figma_execute_code rule is the first clause. But the bulk is a single run-on paragraph cramming an outline format legend, alignment abbreviations, and five mode definitions into one block, which is hard to scan and partly duplicates the schema descriptions.

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

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

For a 17-param, nested-schema, no-output-schema tool this is nearly exhaustive: default mode, each alternative mode, pagination, size caps, document targeting via target/figma_list_targets, and the exact shape of what comes back. An agent can call it correctly without consulting any other source.

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 17 params. The description adds real meaning on top: the outline line grammar (TYPE "name" #id WxH @x,y, a:P/C mapping to MIN/CENTER/SPACE_BETWEEN, fill/hug), the REF-line payload of compare, and the ids-at-once batching rule. The inline legend is arguably output semantics more than parameter semantics, which keeps this off 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+resource ("READ the live Figma document") and immediately differentiates from the sibling write path ("not figma_execute_code"). The mode verbs (like, compare, props, find, find_text, view out/map/flow, check) are each given a concrete job, so an agent can pick a mode 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?

Explicit routing rules: "the tool for any read (not figma_execute_code)", "pass every node id you need at once instead of one call per node", and "never scan the page for reactions". It also names the exact intent each mode serves ("redo these like the reference" for like, "make these like that one" plus post-write check for compare).

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

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

Goes well beyond the annotations: it discloses that the call BLOCKS, that it returns the same result/screenshot a synchronous call would, that stalled:true means the plugin may be frozen, that a repeat call short-circuits with the same advice, and that a finished job is forgotten after one read. These are non-obvious behavioral traits (blocking + single-read retention) not captured by readOnlyHint/idempotentHint.

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

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

Front-loads the triggering condition and the blocking behavior, then layers the operational rules (no polling, stalled handling, retention). Dense but every clause carries 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?

No output schema exists, yet the description explains what is returned (same result/screenshot as the synchronous call) and covers the stalled edge case and read-once retention. An agent has everything needed to call and interpret 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 job_id origin and wait_ms default/max/peek semantics are already documented in the schema. The description reinforces job_id's provenance from figma_execute_code's running response but adds nothing about wait_ms, 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?

States a specific action (wait/block for a job) tied to a specific resource (a figma_execute_code job_id) and names the sibling tool that produces the job_id. An agent can immediately distinguish it from figma_execute_code or other read 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?

Explicitly says when to use it (after figma_execute_code returns status 'running' due to 45s timeout or async:true) and gives a hard usage rule: 'call it once, not in a polling loop.' It also adds the stalled-case escalation path (stop and ask the user), which is a genuine when-not-to-continue 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?

Annotations already declare readOnly, idempotent, closed-world, non-destructive, so no credit is needed for safety. The description adds real value beyond them by naming the returned fields (fileName, current page, focused) and the cross-tool contract for `target`. It stops short of covering edge cases such as what happens when zero documents are connected.

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. The resource and its returned fields come first, and the actionable guidance follows immediately.

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 enumerating the returned fields and explaining how the output feeds into other tools. For a zero-parameter discovery tool, nothing an agent needs in order to call it correctly is missing.

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

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

Zero parameters, so baseline is 4. The description instead documents the `target` parameter semantics of the downstream LIVE tools, which is useful but does not affect this tool's own 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 ("List every Figma document currently connected to this bridge") plus the exact fields returned (fileName, current page, focused). It is clearly distinguishable from siblings like figma_get_selection or figma_inspect, which operate on content rather than the connection registry.

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 explicit triggers: recovering from an AMBIGUOUS_TARGET failure, and proactively disambiguating when several files are open. It also closes the loop by telling the agent what to do with the result — pass the fileName as `target` on any LIVE 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?

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real context: it reads live desktop state rather than cloud state, output format matches get_file/get_node, and token cost is bounded. It does not mention failure behavior when no document is open or how target resolution errors surface, which keeps it from a 5.

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

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

Two sentences, front-loaded with the distinguishing fact (LIVE document) before the comparison to siblings. 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?

Six optional parameters with full schema coverage and no output schema, and the description covers the live-vs-cloud distinction, format parity and token budgeting. Minor gaps remain around multi-document targeting and no-document-open behavior, but nothing critical for correct invocation is missing.

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

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

Schema coverage is 100%, so depth, format, target, node_ids, budget_tokens and include_hidden are all already documented. The description reinforces that the output format semantics are identical to get_file/get_node, which helps interpret the format enum, but adds no new per-parameter detail beyond the schema baseline.

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

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

States a specific verb (read) and a precisely scoped resource (the LIVE, currently-open Figma document) with the output shape (Pseudo-JSX/Tree/JSON). It also distinguishes itself from the cloud-API siblings get_file/get_node and from figma_execute_code, so an agent can pick it without opening a schema.

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

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

Explicitly says to prefer this over hand-writing a tree walk in figma_execute_code and gives the reason (cheaper, format parity). It does not spell out the complementary case (use get_file/get_node when the document is not open locally) or point to figma_list_targets for multi-document targeting in the prose, so the routing guidance is clear but not exhaustive.

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

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

The annotations already declare destructiveHint=true and idempotentHint=false, but the description adds crucial behavioral detail: it removes nodes created by the write and restores modified properties, and deletions of pre-existing nodes are never recoverable. This gives the agent precise expectations about what rollback can and cannot undo, beyond the structured annotations.

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

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

Three sentences, front-loaded with the core action and immediately followed by scope and irreversibility constraints. Every sentence carries useful information, and the checkpoint_id prerequisite is placed naturally at the end.

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 destructive annotations, complete input schema, and absence of an output schema, the description supplies everything needed: what rollback does, which write calls it covers, what it cannot restore, and where checkpoint_id comes from. No essential behavioral or usage context is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description reinforces that checkpoint_id comes from a previous write call's response, but it does not add syntax or selection rules beyond what the schema already states. The baseline of 3 is appropriate when schema coverage is complete.

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

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

The description uses the specific verb 'Undo' and precisely scopes it to previous write calls, naming the sibling write tools it applies to. It also states exactly what is affected (created nodes removed, modified properties restored), so the agent can distinguish it from all other siblings.

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

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

It clearly explains the intended context: undoing a previous figma_execute_code, figma_insert_component_instance, or figma_insert_svg call. It also states the prerequisite that every write call returns a checkpoint_id to pass here. It does not explicitly name when not to use it beyond the irrecoverable-deletion warning, so it falls short of full when/when-not/alternative guidance.

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

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

Annotations already declare read-only/idempotent, but the description adds genuinely non-obvious behavior: each image costs ~1k tokens at default max_px and stays in context, plus the advice to capture at stage boundaries. That cost/context-persistence disclosure is exactly the kind of thing an agent cannot infer from structured fields.

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

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

Three tight sentences, front-loaded with the action and purpose, then cost implications, then the alternative-call routing. No filler; every clause carries operational 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 zero-required-parameter capture tool with a fully described schema and annotations covering safety, the description supplies the remaining decision-relevant context: cost per call, context persistence, and the preferred sibling path. Nothing needed to call it correctly appears missing.

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

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

Schema coverage is 100% and the schema descriptions already explain scale, max_px, target, node_ids and description in detail, so the description adds little parameter-level detail. Its mention of default max_px reinforces cost but does not decode any parameter beyond what the schema states.

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 ('Capture PNG screenshots of specific nodes or the current selection in Figma') plus the intent (layout, contrast, typography, spacing check), which separates it cleanly from siblings like figma_inspect, figma_read_canvas and figma_get_selection.

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

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

Explicit when-to-use and when-not-to-use guidance: prefer write-call `warnings` or bridge.check for mechanical checks, take one screenshot per finished stage rather than after every edit, and use capture_node_ids on figma_execute_code instead of this tool right after an edit. Alternatives and exclusion conditions are both named.

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

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

Annotations already declare it non-destructive, idempotent, and not open-world, so the safety profile is covered. The description adds scoping (specific node vs entire page) but omits notable behaviors visible in the schema such as the optional screenshot capture side effect and what happens if the mode/collection is not found.

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 front-loaded sentence with no filler; examples are compact and relevant. Slightly under-informative rather than verbose.

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 and full schema coverage mean the description needn't explain returns. For a non-destructive, idempotent state-change tool it covers purpose and scope adequately, though it could note prerequisites (connected document, existing collection/mode).

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 are already documented. The description only restates the mode concept and scope split, adding no syntax, naming, or format detail beyond 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 ('Switch the active Figma Variables mode') plus scope (artboard/frame or entire page), with concrete mode examples. Distinguishable from the read-only sibling figma_get_variables, though it doesn't name it.

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?

Usage is implied through the Dark/Light/Brand examples and the artboard-vs-page scope, but there is no explicit when-to-use guidance, no mention of consulting figma_get_variables to discover mode names or figma_list_targets to pick a document.

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