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

Beyond the annotations, the description discloses a key behavioral trait: existing source reactions are replaced. This tells the agent what prior data is affected. It still omits permissions, error behavior, and return details, but the overwrite warning is substantive.

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, front-loaded with the core action and followed by a critical side-effect warning. There is no filler or 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?

For a three-parameter mutation with full annotations and no output schema, the description plus schema gives enough information to invoke the tool correctly. The main gaps are usage routing and failure-mode detail, which are minor for this simple operation.

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

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

Schema description coverage is only 33%: targetDocumentId is described, but nodeId and destinationId are undocumented. The description partially compensates by clarifying that the source is a node and the destination must be a FRAME, but it does not explain ID formats or the exact role of targetDocumentId.

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: 'Set a click navigation from a node to a destination FRAME.' It is clear what the tool does, but it does not explicitly distinguish the tool from sibling tools such as figma_update_nodes or figma_create_nodes.

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

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

The phrase 'Set a click navigation...' implies the intended use case, and 'Replaces source reactions' provides a caution about overwriting. However, there is no explicit when-to-use guidance, no prerequisites, and no comparison to 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?

Beyond the annotations, it discloses important behavior: the entire creation is rolled back if it fails, nodes are parented before sizing, and there is a hard cap of 500 nodes. It also states validation rules like INSTANCE requiring a local componentId and SVG requiring an svg source.

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 content is front-loaded and every sentence carries technical specification rather than filler. However, it is a dense run-on paragraph with semicolon-separated field lists, so structure and readability could be improved.

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 creation tool with no output schema and only partial schema descriptions, the definition covers the critical nodesJson contract, atomic rollback, limits, fonts, and positioning. It still leaves parentId semantics and some return-value detail implicit.

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

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

Schema description coverage is only 50%, but the description compensates heavily by documenting the nodesJson format in detail, including node types, styling, layout, sizing, text, SVG, and image fields. The main gap is parentId, which is undocumented in both the schema and description.

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

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

The description opens with a specific verb and resource: 'Create editable layers from a JSON array (max 500 nodes).' It clearly distinguishes creation from sibling operations like figma_update_nodes and figma_delete_nodes by describing bulk node construction from JSON.

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 practical usage constraints: max 500 nodes, use fonts from figma_fonts, position new roots clear of existing content, FILL only inside auto-layout, and HUG only for text/auto-layout. It does not explicitly say when to choose this tool over figma_update_nodes, which keeps it from a 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is partly covered. The description earns credit by adding recoverability ('Normal Figma Undo remains available') and a scoping constraint on when destruction is justified. It omits the practical limit that at most 200 nodes can be deleted per call and says nothing about effects on child nodes or connections.

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, zero filler, with the core action stated first and the scoping caveat immediately after. The recoverability note is one clause and 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 two-parameter destructive tool with no output schema, the description covers what is destroyed, when destruction is warranted, and whether it can be undone. The remaining gaps (batch size cap, cascade behavior on children) are secondary but real for a destructive operation.

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 50%: targetDocumentId is documented in the schema, while nodeIds carries only minItems/maxItems constraints. The phrase 'exact node IDs' usefully signals that names or paths are not accepted, but the 200-item cap and the requirement that IDs come from figma_document are not reinforced in the description.

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

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

States a specific verb and resource (delete nodes) plus a precision qualifier ('exact node IDs'), which is enough to place it against siblings like figma_update_nodes and figma_create_nodes. The destructive intent is unambiguous, though it doesn't explicitly name an alternative tool.

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

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

Gives a clear positive condition ('explicitly requested removal') and a useful negative boundary ('cleaning nodes created by the current task'), which steers the agent away from speculative or bulk deletion. It stops short of naming a sibling tool or spelling out an explicit 'do not use for' list.

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, idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds useful context beyond annotations by specifying that the node tree is 'bounded' and that this should be called before write operations, though it does not detail pagination or return format.

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

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

Two short sentences with no filler. The primary purpose is front-loaded, and the workflow 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?

With only three optional parameters and no output schema, the description lists what is read (pages, selected nodes, documentId, node tree), giving a reasonable sense of return contents. It covers the essential calling context for a read-only tool, though parameter-level details remain thin.

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

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

Schema description coverage is only 33%, so the description must compensate. It does add meaning for depth ('bounded node tree') and hints at nodeId ('selected nodes') and pageId ('pages'), but it does not fully document parameter behavior or defaults, leaving gaps.

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 ('Read') and names concrete resources: pages, selected nodes, documentId, and a bounded node tree. It is clear what the tool returns, but it does not explicitly differentiate itself from sibling read tools like figma_status or figma_fonts.

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 phrase 'Call before writes' provides explicit workflow guidance relative to the write-oriented siblings (figma_create_nodes, figma_update_nodes, figma_delete_nodes). It lacks named exclusions or alternatives, but the timing guidance is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is clear. The description adds the PNG output format and a maximum edge of 4096 px, but it does not describe the return value or how scale affects export size.

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 no wasted words. The primary action and format are front-loaded, followed by the size constraint.

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 export tool with no output schema and low schema description coverage, the description is too sparse. It omits the return format, scale semantics, and nodeId expectations, leaving important invocation details 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 only 33%, so the description must compensate for undocumented parameters. It does not explain scale or nodeId, and targetDocumentId is only documented in the schema, not in the description.

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

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

The description states a specific verb and resource: export a node as PNG. It also gives a clear purpose, visual validation. It does not explicitly name sibling tools or explain why to choose this over figma_document, but the export action is distinct from the other listed 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?

The phrase 'for visual validation' implies when the tool is useful, but there is no explicit guidance on when to use it versus alternatives. It also does not mention prerequisites such as obtaining the nodeId or targetDocumentId first.

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

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

Annotations declare readOnlyHint=false but destructiveHint=false, so an agent knows something is being mutated; the description clarifies that the mutation is selection/viewport state plus zoom. It does not say whether document content is untouched, whether the selection persists, or that nodeIds is capped at 50, all of which matter for a non-readOnly call.

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

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

A single front-loaded sentence with the action and effect stated immediately and zero filler. It is perhaps too terse for what it omits, but nothing in the text is wasted.

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

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

No output schema and thin annotations on a three-parameter tool: the definition should explain the targetDocumentId safety check's role in the workflow, the page-then-node ordering, and the batch limit. As written, an agent has enough to attempt a call but not enough to call it correctly on the first try.

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

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

Schema coverage is 67%, below the threshold where the schema carries the full burden, yet the description says nothing about any parameter. nodeIds has no schema description at all, and the 50-node cap and the pageId-before-selection sequencing are left entirely to the schema's structural keywords.

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 pair (select + zoom) applied to concrete resources (nodes, viewport), which distinguishes it from mutation siblings like figma_update_nodes and figma_export_node. It does not explicitly differentiate from figma_document or figma_status, which an agent might confuse it with when only navigation is needed.

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?

No guidance on when to call this instead of figma_document or figma_export_node, and no mention of the prerequisite page-switching flow implied by the pageId parameter. The agent must infer that this is the 'navigate the user's view' tool rather than a data-fetching 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?

The annotations already declare this as a safe, read-only, idempotent, non-destructive operation. The description confirms listing behavior but adds no additional behavioral context such as return format, pagination, or font metadata; with annotations covering the safety profile, this is adequate but minimal.

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 a single front-loaded sentence with no wasted words. It is appropriately sized for a simple one-parameter list tool.

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 tool is simple and the annotations are rich, but there is no output schema and the single parameter is undocumented in the schema. The description only minimally covers what the tool returns and how filtering works, leaving some practical gaps for an 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?

Schema description coverage is 0% for the single 'family' parameter, so the description must compensate. It only says the list may be optionally filtered by family and does not explain matching semantics, case sensitivity, or what a valid family value looks like.

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 (List) and resource (available fonts), and adds an optional filter. It is clear enough to distinguish this from the other figma_* tools, though 'available' is slightly ambiguous about scope (local, Figma, or remote fonts).

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 phrase 'optionally filtered by family' implies a basic usage pattern, but there are no explicit when-to-use or when-not-to-use guidelines. For a simple listing tool this is acceptable, but it does not help an agent choose against any alternative.

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 mutation, non-destructive, non-idempotent and closed-world. The description adds context annotations can't carry: canvas position is preserved and the move changes prototype-destination eligibility. It still doesn't cover what happens to a frame already on the target page or partial-failure 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?

Three tight sentences, front-loaded with the action and effect, followed by the prerequisite and the nodeIds caveat. Nothing 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 mutating, non-idempotent tool with annotations and no output schema, this covers the essential behavior and constraints. Remaining gaps are edge cases (re-running on already-moved frames, cross-file behavior) rather than blockers.

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

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

Schema coverage is 67% and nodeIds has no description. The description compensates by narrowing nodeIds to "exact FRAME IDs" and adding a real constraint not in the schema: never include a frame together with its ancestor.

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

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

States a specific verb+resource+scope: move exact FRAME IDs out of containers onto the current page. It also gives the downstream effect (screens become eligible as prototype destinations), which separates it from siblings like figma_update_nodes or figma_connect_screens.

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?

"Read the document first" implies a prerequisite step (figma_document) and the ancestor/frame exclusion is a clear usage constraint. It stops short of naming the sibling tools explicitly or saying when to prefer a different move/update 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety and locality profile is covered structurally. The description adds only the useful detail that the plugin is a 'local' one, and says nothing about what is returned (boolean? plugin version?) or failure behavior, so it adds modest value beyond structured data.

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

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

A single front-loaded sentence with no filler and no wasted clauses. It is appropriately sized, though a second sentence on return value/next step would have earned 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 describing results, the description should state what 'connected' looks like as a return value and what an agent should do on a negative result. For a health-check tool that other tools depend on, that is a meaningful 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter information is missing or needed.

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 ('Check whether') and a precise resource ('the local Figma plugin is connected'), which is unambiguous and clearly distinct from the mutation/read tools in the sibling list. It stops short of explicitly contrasting itself with siblings, but the purpose is self-evidently different.

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: an agent can infer this is a preflight/health check to run before invoking figma_document, figma_create_nodes, etc., but the description never says when to call it, when not to, or what to do if the check fails. No explicit alternative or ordering guidance is 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?

The annotations already declare non-read-only, non-idempotent, non-destructive behavior. The description adds important context beyond that: partial writes may occur and are reported on errors, so the agent should inspect before retrying. It does not cover permissions or merge semantics, but it discloses the key mutation risk.

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

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

The description is compact and front-loaded: it states the action first, then explains the critical updatesJson format and error-handling caution. Every sentence contributes useful information with no 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 mutation tool with annotations and no output schema, the description covers the essential input format and the partial-write retry behavior. It could further clarify whether updates merge or replace existing properties and what permissions are needed, but it is largely complete for correct invocation.

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

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

The schema describes pageId and targetDocumentId, and the description compensates for updatesJson's missing schema description by defining it as an array of {nodeId,props} and noting that props reuse create_nodes' editable properties without type/children. It defers the full property list to create_nodes, which is reasonable but not exhaustive.

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: "Update layers." It references create_nodes to clarify the editable properties and excludes type/children, making the update scope clearer. It does not explicitly distinguish itself from siblings like delete_nodes, but the purpose is clear.

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

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

Usage is implied: this tool updates existing layers and should be used with updatesJson rather than creation or deletion. The retry caution gives operational guidance, but there is no explicit when-to-use versus when-not-to-use or direct sibling routing.

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