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

Annotations already declare this is a non-read-only, destructive, closed-world write, so the safety profile is covered. The description adds the sequencing constraint and hints that only 'supported' properties are applied, but never says what gets mutated, what happens to unsupported props, or what is returned. Adequate but thin for a destructive 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?

Two short sentences, front-loaded with the action and followed by the precondition. Every sentence earns its place 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?

For a tool with a 3-parameter schema, one of which is a deeply nested properties object, no output schema, and a destructive write annotation, this description is under-specified. It omits what the returned instance identifier is, whether props are optional, and how the large supported-property surface is scoped.

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% and the schema defines a large nested 'props' object (~30 fields) with no per-field descriptions, so the description carries the burden. It only says 'apply supported properties' without naming or scoping any of them, adding essentially no meaning beyond the schema's own constraints.

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 an instance of a local component') and adds the precondition that a component must already exist, which separates it from create_node/create_scene. It doesn't fully clarify how an instance differs from a plain node or scene, but the purpose is unambiguous.

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 second sentence gives a real prerequisite ('Build components with create_node or create_scene first'), which is useful ordering guidance. However, it offers no when-not guidance or alternatives for cases where create_node/create_scene might be preferred over instancing, so usage is only partially implied.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, covering the safety profile. The description adds useful context beyond the annotations: node placement target ('current page or parent') and capabilities ('text styles and color/numeric variable bindings'). It does not disclose side effects like auto-selection, idempotency, or failure behavior, so it remains at a solid 3.

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 with the core action front-loaded and capability notes trailing. No wasted clauses, though it is arguably too terse given the underlying complexity.

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

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

For a tool with a 3-parameter schema housing a deep nested props object, no output schema, and 0% description coverage, the two-sentence description is thin. It omits which props apply to which node types, required inputs for TEXT vs FRAME, and what is returned on success, which an agent would need to call it correctly.

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

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

Schema description coverage is 0%, so the description must carry the load, but it only alludes to the type enum values and vaguely to variable/text-style bindings. The large nested props object (~30 fields such as characters, fontSize, layoutMode, cornerRadius) is entirely undocumented in both schema and description, leaving the agent guessing.

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 ('Create') plus the resource ('node') and enumerates the exact node types it can produce (FRAME, RECTANGLE, ELLIPSE, TEXT, COMPONENT), which helps distinguish it from siblings like create_instance or create_page. It does not explicitly name those siblings, so it falls 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 gives no indication of when to use create_node versus create_instance, create_scene, or create_page, nor any prerequisites. The phrase 'in the current page or parent' hints at placement behavior but provides no decision guidance 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 declare destructiveHint=true but say nothing about the reuse-vs-create behavior, the plan-based page budget, or the cloud-file scope; the description supplies all three, which materially changes how an agent should call it. It still omits what happens to page contents or whether the call fails or silently reuses at the limit.

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 a distinct fact (reuse rule, budget, fallback tool, scope limit), with the core action and reuse behavior front-loaded. Slightly terse and telegraphic in places, but 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 one-parameter, no-output-schema, mutating tool whose annotations only flag destructiveness, the description covers the key behavioral facts an agent needs: budget limits, reuse behavior, fallback to get_document, and non-cloud scope. Only the semantics of the name parameter and failure behavior at the limit 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?

There is a single parameter with zero schema description coverage, so the description must compensate. It implies exact-match semantics for 'name' via the reuse rule, but never states format, uniqueness constraints, or that length is bounded to 100 characters.

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 page') and adds a surprising secondary behavior ('reuse an exact matching page name'), which helps an agent distinguish it from siblings like create_node or update_page. It also disambiguates with 'Does not create a cloud file,' clarifying what 'page' means here.

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 conditional route-away instruction: 'At the limit use existing page IDs from get_document,' which names a sibling and the condition that selects it. It stops short of a full when/when-not treatment (e.g., no guidance on renaming vs. creating, or on non-Starter budgets).

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 and destructiveHint=true, and the description adds context beyond them: the 100-node cap, cross-reference ordering rules, and notably the atomicity guarantee ('Newly created nodes are cleaned up on failure'). It does not disclose auth/permission needs or what happens on partial success beyond cleanup.

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 compact sentences, each carrying a distinct rule, with the batch limit and ref semantics front-loaded. No filler or repetition of name/title.

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

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

For a destructive batch-creation tool with no output schema, the description covers input rules well but never says what is returned (e.g. created node IDs/refs) so an agent cannot confidently chain follow-up calls. No mention of permissions or rate considerations either.

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%, so the description must carry semantic load. It does explain the two trickiest relationships (ref uniqueness, parentRef ordering, parentId for root nodes) and notes that props accept style-guide IDs, but the ~30 props fields are left entirely to the schema's enums and types.

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 ... native nodes') plus a distinguishing scope ('up to 100 ... in one call'), which separates it from the single-node sibling create_node. The parenthetical '(screens or components)' clarifies what native nodes are.

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

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

Gives concrete usage constraints: refs must be unique, parentRef must point to an earlier FRAME/COMPONENT node in the same call, and root nodes use parentId or the current page. It does not explicitly say when to prefer this over create_node or update_node, so guidance is strong but lacks alternative 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?

Adds meaningful behavior beyond the annotations: the namespace-collision failure mode ('Existing namespace is rejected'), the document-budget fallback, board placement, and the returned fields. It is consistent with destructiveHint=true (it creates resources) and openWorldHint=false (explicitly no cloud/REST), so there is no contradiction.

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

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

Front-loads the core action in the first clause, then layers pageId behavior, budget fallback, return values, error behavior, and scope exclusions in a compact block with no filler sentences.

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

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

With no output schema, the description usefully names the return fields (createdPage and actual IDs) and covers budget and collision cases. It still leaves unclear what the created board contains and how the generated variables/styles map to the new page, which slightly limits self-sufficiency.

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% across 6 parameters, so the description must carry the load, and it does for the one non-obvious parameter: pageId's optionality, target semantics, and budget-dependent fallback. The remaining five params (name, radii, colors, spacing, typography) are self-describing via defaults, but the description adds no explicit meaning for them.

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

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

States a specific verb and a concrete set of resources (style-guide board, variables, text styles) scoped to the OPEN file, which cleanly separates it from siblings like create_page, create_scene, and set_variable. The closing exclusions ('Does not create a cloud file or use REST') further pin down what kind of creation this is.

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 conditional guidance: pass pageId to target an existing page, otherwise a page is created within the document budget, and at the limit the current page is used with the board placed to the right. It does not name alternative tools or say when not to use this one, so it stops short of 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the bar is lower. The description nonetheless adds two traits annotations cannot express: the deletion is cascading (descendants go too) and it is recoverable via Figma Undo. That recoverability note is exactly the kind of context an agent needs before invoking a destructive 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 and scope, then constraints, then recoverability. Every sentence carries distinct information with no filler.

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

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

For a single-parameter destructive mutation with annotations covering the safety profile and no output schema, the description covers blast radius and reversibility adequately. The only real omission is any characterization of the nodeId argument.

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% and there is one parameter, nodeId, which the description never mentions. The field name is fairly self-explanatory, but the description contributes nothing about identifier format, scope, or whether the node may be a root-level frame.

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 (delete a scene node) and immediately bounds the scope to the node and all its descendants. The exclusions ('Cannot delete pages or the document') further separate it from the page/document siblings in the tool 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?

Gives a clear when-not condition (pages and the document cannot be deleted), which is genuine usage guidance for an agent scanning candidates. It stops short of naming an alternative tool for the page/document case, so it is clear context rather than full when/when-not/alternatives 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?

Annotations already declare this as a safe read (readOnlyHint=true, destructiveHint=false), so the safety profile is covered. The description adds genuinely new behavioral facts beyond the annotations: PNG output is capped at 4096 pixels per side and 8 MiB, which tells the agent when an export will fail or must be scaled down.

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 operation and followed by the actionable constraint. No filler, nothing 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 three-parameter export tool with no output schema, the description covers the format choice and size limits but omits how the result is delivered (inline data vs. file path) and what 'scale' does. Adequate but with visible gaps.

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

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

Schema description coverage is 0%, so the description must compensate and largely does not. It names the two format values (PNG/SVG) but says nothing about 'scale' or 'nodeId', leaving two of three parameters with no semantic guidance beyond types and bounds.

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+resource ('Export a node') plus the output formats (PNG/SVG) and the transport ('local Plugin API'). It does not explicitly distinguish itself from siblings, though the operation is clearly distinct from get_node/update_node/delete_node.

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

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

There is no when-to-use context, no prerequisites, and no mention of alternatives. The agent is told what the tool does but not when to reach for it over, say, a screenshot or get_node workflow.

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, non-destructive, closed world), so the description earns credit for the extra operational context: maxVisited bounds the amount of work performed, and file edits can shift offsets, warning the agent that pagination state is unstable. That is genuinely useful disclosure a caller could not infer from the schema.

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

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

Three short sentences, front-loaded with the core purpose and no filler. It is efficient, though the pagination sentence trades accuracy for brevity by citing the wrong parameter 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 6-parameter search tool with no output schema and zero schema descriptions, the definition is far too thin. It omits the meaning of query/type/limit/pageId and does not describe result shape, total counts, or how many nodes a page holds, leaving the agent unable to call it precisely.

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% across 6 parameters, so the description must carry the load, yet it only mentions maxVisited and refers to a non-existent 'nextOffset'. The purpose of query, type, limit, offset, and pageId is left entirely unexplained, and one parameter name given is wrong.

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 ('Search names and text') and scopes it to 'one page', which distinguishes it from document-wide tools like get_document. It is clear enough to act on, but it never names the closest siblings (get_node, find-style alternatives) or clarifies what a 'node' search returns.

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

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

The only usage instruction is 'Use nextOffset for pagination', but nextOffset does not exist in the schema (the parameter is 'offset'), so the guidance actively misleads. There is no statement of when to reach for find_nodes versus get_node or get_document, and no 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real context beyond them: the automatic connection behavior and the security guarantee that the persistent installation key is never exposed via MCP. That is meaningful behavioral disclosure an agent would not get from the annotations alone.

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

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

Three short sentences, front-loaded with the purpose, then connection behavior, then the security caveat. No filler, though the second sentence is a minor tangent for an agent whose only job is to call the 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?

A no-parameter, no-output-schema tool where the description carries the full disclosure burden, and it does cover the key points: what is retrieved, how the plugin connects, and what is conditionally returned. Slightly incomplete on what the returned status actually contains (connected/disconnected? key presence?).

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 the baseline is 4. The description uses the space instead to explain the conditional return value (pairingCode only for the manual plugin), which is useful given there is no output schema.

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

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

States a specific verb and resource: 'Get local bridge status.' That is enough to distinguish it from the design-manipulation siblings (create_node, get_node, set_selection), which all operate on document objects rather than a local bridge. It stops short of saying what 'bridge' is or what the status contains, 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 rather than stated: the note that the installed plugin connects automatically and that pairingCode is only returned for the manual plugin hints at when this call matters (manual setup scenarios), but there is no explicit 'use this when / not when' or alternative tool named. Adequate but leaves the agent to infer.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully confirms the closed scope ('does not read remote libraries'), but says nothing about pagination behavior or the shape of the returned listing despite a limit parameter existing.

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, front-loaded with what is listed followed by the scope caveat. Every clause carries information and 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 simple read-only listing tool whose annotations cover safety, the description gives the enumerated return contents and the filtering/scoping rules. The only real gap is the unmentioned limit parameter and pagination behavior, which is minor.

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%, so the description must compensate. It explains the 'prefix' filter semantics ('filtered by name prefix') but is silent on 'limit' (default 200, max 500), leaving half the parameters undocumented.

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 (List) and concrete resources (local variable collections, tokens with mode values, text styles), so the agent knows exactly what comes back. It also scopes itself ('local', 'does not read remote libraries'), though it never names a sibling tool to differentiate against.

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: 'optionally filtered by name prefix' suggests a lookup scenario, and the remote-library exclusion hints at a boundary. There is no explicit when-to-use, when-not-to-use, or named alternative among the get_*/find_nodes siblings.

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 and destructiveHint=false, so the safety profile is covered. The description adds valuable non-obvious context: the team plan is not exposed by the Plugin API and should be reported as unknown or with user-declared/observed-limit evidence. This is a real behavioral constraint beyond annotations, though it doesn't cover return format or error behavior.

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

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

The description is only three sentences but is poorly structured: the first sentence lumps multiple unrelated return items together, the second is a caveat about team plans that interrupts the main point, and the third is a timing instruction. The core action is front-loaded, but the middle sentence is dense and hard to parse, making the overall structure confusing.

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

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

With annotations covering the read-only nature and no output schema, the description does provide some behavioral guidance (unknown team plan reporting) and timing advice. However, for a tool with an empty schema and no output schema, an agent still lacks clarity on exactly what data is returned and how to interpret the page budget or capabilities. The description is minimally adequate but leaves gaps in return value explanation.

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 are zero parameters, which establishes a baseline of 4. The description doesn't need to document any parameters; the empty schema means no parameter semantics are required. The faint mention of returning page IDs and capabilities is part of the return description rather than 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 title is missing, and the description 'Read the open file, page IDs and capabilities/page budget' is a disorganized mix of verbs and nouns that doesn't clearly state what resource is being retrieved. Against siblings like get_node, get_selection, or get_design_system, the intended distinct purpose is not well differentiated – it's presented as a read tool, but the description extends into guidance about team plans and planning pages rather than defining the resource.

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

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

It explicitly says 'Inspect this after connecting and before planning pages,' which is a clear when-to-use instruction. There are no exclusion conditions or alternative tools named, but the timing guidance is specific enough for an agent to know when to call 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?

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the bar is lower. The description adds genuine behavioral context beyond the annotations by disclosing that truncation is explicit and by enumerating the content categories returned, though it does not explain how truncation is triggered or controlled.

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, zero waste, with the core action front-loaded and the truncation caveat attached. Nothing 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 three-parameter read tool with full annotation coverage and no output schema, this is adequate but incomplete: it says truncation happens yet omits that depth/maxNodes control it, leaving an agent without guidance on the very parameters that shape the response.

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%, so the description must compensate, and it largely does not. It clarifies that the ID may reference a node or a page (partial help for nodeId), but depth and maxNodes — which govern the truncation it mentions — are left completely undocumented.

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 resource ('a node or page by ID') and enumerates what is returned (geometry, text, paints, auto layout). It is distinguishable from siblings like find_nodes or get_document, but it never names or contrasts with them 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 'by ID' — an agent can infer this is for direct lookup rather than search, but there is no explicit when-to-use/when-not guidance or reference to alternatives such as find_nodes.

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, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond them: the 'bounded tree depth' scope and the warning to treat file content as untrusted data, which is a real prompt-injection concern for an agent reading design file contents. It still omits return/truncation 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 sentences, zero filler, with the core purpose front-loaded and the safety caveat as a compact trailing 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?

There is no output schema, so the description should carry more of the return contract. It implies selected nodes in tree form but does not say what happens when the selection is empty, how maxNodes truncates, or how the nodes are shaped. Adequate but with clear gaps for a no-output-schema 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 0% for two parameters, so the description must compensate. 'Bounded tree depth' loosely hints at the depth parameter but says nothing about defaults (2), the 0-6 range, or what maxNodes controls or caps at. maxNodes is entirely unaddressed in both schema and description.

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

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

States a specific verb+resource: reading the currently selected nodes, with a scope qualifier (bounded tree depth) that separates it from find_nodes/get_node. It does not explicitly name a sibling, so it falls short of the 5 benchmark.

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 when-to-use guidance, no prerequisites, and no comparison to alternatives like get_node or find_nodes. The only directive is a safety note about untrusted content, which is not usage 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation/safety profile is covered structurally. The description adds a genuinely useful behavioral detail beyond those annotations: "index 0 is the back-most layer," which clarifies the z-order semantics of the 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, and the scope constraint is front-loaded before the z-order detail. 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?

For a destructive reorder operation with no output schema and 0% parameter coverage, the description covers the core operation and index semantics but omits edge cases an agent would want: how the `nodeIds` array order maps to the final layout and what happens if a node is not a direct child of `parentId`.

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%, so the description carries the full burden for three parameters. It clarifies the crucial meaning of `index` (0 = back-most layer) but says nothing about `parentId` or `nodeIds`, leaving array ordering semantics and validation behavior undocumented.

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 ("Reorder") and resource ("direct child layers") and constrains the scope to a single parent of type PAGE, FRAME, COMPONENT or SECTION. This implicitly distinguishes it from the sibling reparent_nodes, which moves nodes across parents, 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?

There is no explicit when-to-use or when-not-to-use guidance, and no pointer to an alternative such as reparent_nodes. The scope constraint ("within one ...") hints that it stays inside a single parent but stops short of stating that usage condition.

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 readOnlyHint=false, so the mutation profile is covered. The description adds genuinely new behavioral context: absolute position is preserved by default, and auto-layout destinations are refused to avoid accidental layout changes, which tells the agent about a built-in guardrail it could not infer from annotations.

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

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

Two sentences, no filler, with the core action front-loaded and the guardrail constraint trailing as supporting detail. Every clause adds information an agent 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?

For a destructive mutation with no output schema and 0% schema coverage, the description covers the positional behavior and destination restriction well but omits how insertIndex orders the moved nodes, the nodeIds count limit (max 100), and what happens on partial failure. Adequate but with clear gaps.

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

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

Schema description coverage is 0% across 4 parameters, so the description carries the burden. It clarifies preserveAbsolutePosition (default true, preserves absolute position) and constrains parentId to page/frame/component/section, but says nothing about insertIndex (the insertion position within the new parent) or the nodeIds array limits, leaving half the parameters undocumented anywhere.

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 (Move) and resource (scene nodes) plus the valid destination types (PAGE, FRAME, COMPONENT, SECTION), which is well beyond a tautology. It stops short of explicitly differentiating itself from the close sibling reorder_nodes, which an agent could easily confuse with this 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?

The description implies usage by naming the allowed destination kinds and noting that auto-layout destinations are rejected, which tells the agent when the call will fail. However, it never states when to prefer this over reorder_nodes, nor any prerequisite such as needing node IDs from find_nodes/get_selection.

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 readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: WebP and other decodable inputs are normalized to PNG locally in the plugin. However, it doesn't state that the existing fill is replaced/overwritten or what happens on decode failure, so it stops short of rich behavioral disclosure.

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

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

Two sentences, zero filler, and the primary action is front-loaded with the normalization caveat 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, 4-parameter mutation with no output schema, the definition is adequate but thin: it leaves scaleMode, nodeId expectations, and failure/overwrite behavior unexplained, and there is no return-value note. The normalization disclosure is the one piece of real depth.

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%, so the description carries the full burden. It names the accepted image formats, which partially covers sourceMimeType, but says nothing about nodeId, scaleMode (FILL/FIT/CROP/TILE), or the 16 MB base64 cap. Three of four parameters remain semantically opaque.

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 ('Replace a node fill') plus the exact input form ('supplied as base64'), which implicitly distinguishes it from the sibling set_image_fill_from_path. An agent can tell what the tool 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?

No when-to-use, when-not-to-use, or alternative is given. The base64 wording hints at the split from set_image_fill_from_path, but the description never says to prefer the path variant when a file is on disk, leaving routing 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 destructiveHint=true already declared, the description adds real context the annotations cannot: the file is read locally, validated by binary signature, and sent only to the open Figma file (no remote upload). It omits that the operation replaces any existing fill on the node, which is the main destructive consequence.

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 with zero filler, front-loading the action and formats before the security/privacy context. Nothing is redundant with the tool name or annotations.

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

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

For a mutating, no-output-schema tool, the import mechanics and privacy guarantees are covered, but the definition leaves the scaleMode options unexplained and does not warn that the existing node fill is overwritten. An agent can call it, but not confidently or optimally.

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%, so the description must carry parameter meaning, but it only indirectly covers imagePath (accepted formats). nodeId is never mentioned and scaleMode with its FILL/FIT/CROP/TILE enum is entirely unaddressed, leaving two of three parameters undocumented anywhere.

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: importing a local image file into a node fill, and names the supported formats (PNG, JPEG, GIF, WebP). It is clear what the tool does, but it never distinguishes itself from the sibling set_image_fill, which an agent must choose between based on source type (path vs. bytes/URL).

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 phrase 'a local PNG, JPEG, GIF or WebP file' and 'read only on this computer', which hints that this is the path-based variant. There is no explicit statement of when to prefer this over set_image_fill, nor any prerequisite about the node already existing or being an image-capable node.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=false, so the safety profile is covered structurally. The description adds the 100-node and same-page constraints but never says that this call replaces the current selection or that focus defaults to true — the destructive aspect is left to the annotation alone.

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

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

A single sentence with no filler, front-loading the action and its limit. It is terse to the point of under-specification, but no sentence is wasted.

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

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

For a two-parameter mutation tool whose annotations carry the safety profile and which has no output schema, the definition is serviceable but thin: it omits required-parameter status, the focus default, and the fact that existing selection is overwritten.

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%, so the description must compensate. It does explain focus ('optionally focus them') and nodeIds ('up to 100 nodes from the same page'), covering both parameters at a high level, but omits that nodeIds is required, that focus defaults to true, and the 200-char string limit.

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: 'Select ... nodes' with scope 'from the same page' and a stated cap of 100. It implicitly separates itself from the read-side sibling get_selection, though it never names an alternative 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: the 'same page' constraint and 100-node cap hint at when the call is valid, but there is no explicit when-to-use, when-not-to-use, or pointer to get_selection for reading existing selection state.

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

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

Annotations already declare this is a destructive write (readOnlyHint false, destructiveHint true, openWorldHint false). The description adds that the tool updates only local tokens in a given mode, and that bound layers follow Figma variable behavior, which is useful behavioral context beyond the annotations. It does not detail permission requirements or rate limits, but the added caveats are valuable.

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 concise sentences, front-loaded with the core action and scope, followed by a useful caveat. No wasted words and appropriate length for the tool's complexity.

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 covers the core mutation and a follow-up note, but with no output schema and no parameter descriptions in the schema, it should provide more detail about the variableId parameter and any expected return or error behavior to be fully complete 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%, so the description must compensate for three undocumented parameters. It only explains that value is a COLOR or FLOAT and that modeId selects a mode, but does not clarify the format or role of variableId. This leaves a significant gap for an agent to construct a valid call.

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 (local token/variable), and scope (default mode or specified modeId). It also names the allowed data types (COLOR #RRGGBB or FLOAT), clearly distinguishing it from sibling tools that operate on nodes or pages.

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 implies usage for changing token values and notes a follow-up for bound layers and specimen captions. It does not explicitly state when not to use this tool versus alternatives like update_node, but the domain is specific enough that an agent can infer.

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 description adds valuable behavioral context beyond annotations: 'Edits are not transactional; inspect after errors' and 'Figma Undo is available.' This informs the agent about the lack of atomicity despite destructiveHint=true, and provides a fallback. However, it doesn't specify required permissions or whether partial updates are possible.

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 concise sentences, front-loaded with the core action. Each sentence earns its place: purpose, format clarification, and behavioral caveat. No redundancy or 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 mutation tool with many nested parameters and no output schema, the description covers the essential non-obvious aspects: fill/stroke format, non-transactional behavior, and undo availability. It omits details on whether all properties are optional, but the schema covers that via required array. It's largely complete for an agent to invoke correctly, though some parameter semantics (e.g., fontName, variableBindings) are not explained.

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

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

With 0% schema description coverage across many nested properties, the description must compensate. It clarifies the fill/stroke format: '#RRGGBB or null.' This addresses a key ambiguity among many parameters, though most others (x, y, width, etc.) remain semantically clear from their names and schema constraints. Given the low coverage, a 4 reflects adequate but not exhaustive compensation.

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: 'Set supported properties on one scene node.' This clearly distinguishes the tool from siblings like create_node, delete_node, or reparent_nodes. However, it does not fully differentiate from update_page, which is a similarly named update operation on a different resource.

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 use this tool versus alternatives like reparent_nodes, set_variable, or update_page. The description lacks any when-to-use or when-not-to-use conditions.

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

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

Annotations already disclose the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=false), so the safety burden is covered. The description adds a useful constraint about the background being a single solid #RRGGBB paint, but says nothing about reversibility, permissions, or whether renaming affects existing references. With annotations carrying safety, a 3 is appropriate.

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 with the primary action front-loaded and a formatting constraint appended. Every clause earns its place 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?

For a mutation tool with no output schema and 0% schema description coverage, the description is functional but thin. It conveys the two operations and the background format but does not explain return behavior, whether background replaces existing paint, or permission requirements, leaving meaningful gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies 'name' (rename) and gives format meaning for 'background' (#RRGGBB single solid paint), which adds value beyond the bare pattern. However, it leaves 'pageId' unexplained and adds no per-parameter detail on required/optional roles, so compensation is only partial.

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

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

The description gives a specific verb(s)+resource: 'Rename a page and/or set its canvas background.' This clearly distinguishes it from create_page and update_node by naming the page resource and the exact operations. It does not, however, explicitly contrast itself against the nearest siblings (update_node, create_page), so it falls just short of a 5.

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

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

There is no guidance on when to use this versus alternatives like update_node or create_page, nor any prerequisite or condition stated. The description only says what it does, leaving all routing decisions to inference.

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