figmcp

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

With no annotations, the description carries the full burden, and it does disclose one genuinely non-obvious behavioral trait: mapping a component inside a component set maps the entire set. It also discloses the cross-tool effect on get_design_context. However, it says nothing about whether an existing mapping is overwritten, whether the mapping persists across sessions, or what a successful call returns.

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

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

Two sentences, no filler, and the purpose plus downstream benefit are front-loaded before the input-scope caveat. 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 mutation tool with no annotations and no output schema, the description covers purpose, target selection, and the set-wide side effect, but omits overwrite/conflict behavior on re-mapping and any indication of the response. It is adequate to make the call correctly but not fully sufficient to predict the result.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns above baseline by explaining that nodeId may be an instance, a component, or a component set id and by clarifying the scope consequence of choosing a component inside a set. That scope semantics is behavior the schema's pattern-only nodeId description does not convey.

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

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

States a specific verb+resource ('Map a design component to a code component') and immediately names the downstream effect on get_design_context, which cleanly separates it from the sibling get_code_connect_map (read) and remove_code_connect_map (delete). An agent can identify this as the write-side of the Code Connect mapping trio without opening any schema.

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

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

The description implies when this matters ('so get_design_context names the code component for every instance of it') and constrains which node types may be passed, but it never states when to prefer this over remove_code_connect_map/get_code_connect_map, nor any prerequisites or conditions under which it should not be called. Usage is inferable rather than stated.

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

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

With no annotations present, the description carries the full burden, and it does disclose useful behavior: three distinct output categories with caps (up to 20 rawImages, up to 20 svgAssets) and default formatting. It omits where downloads land, whether anything is mutated, and error/limit behavior beyond the counts.

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 tightly packed sentences with no filler; the what-is-downloaded inventory is front-loaded before the format/scale controls. Every clause carries information.

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

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

For a tool with no output schema and no annotations, the description effectively substitutes as a return-value spec by naming the three asset groups and their caps, plus format/scale defaults. It stops short of describing response shape or failure modes, but covers what an agent needs to invoke it correctly.

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

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

Schema coverage is 50% and the two undocumented parameters are exactly the ones the description explains: defaultFormat (png, jpg, svg, pdf) and defaultScale (default png at 1). This meaningfully compensates for the gap, though the scale's 0.01-4 bounds and the fileKey no-op behavior are not restated.

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 (Download) and resource (assets) for a single node, then enumerates exactly what is produced: `export`, `rawImages`, and `svgAssets`. It does not, however, differentiate itself from overlapping siblings such as get_screenshot or save_design_export.

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

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

The description never says when to reach for this tool versus get_screenshot, save_design_export, or place_image, nor does it state prerequisites or exclusions. Usage is only implied by the enumerated asset types, leaving the agent to infer the route.

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

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

With no annotations, the description carries the full burden and does add genuine context: it composes the response into mapped vs unmapped components and discloses where the data lives (.figma-local/code-connect.json under the working directory), which implies a local read. It does not discuss permissions needed to read the file or whether it can fail.

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 packed into essentially one compound sentence with the return shape front-loaded and no filler. It is dense but not padded, and 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?

There is no output schema, so the description usefully explains the return value itself (the nodeId-keyed mapping and the unmapped components). The remaining gap is usage context relative to the add/remove siblings, but for a read tool with a 100%-covered schema and full return description it is largely complete.

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

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

Schema coverage is 100%, so the schema already documents both parameters (including that nodeId can be omitted to use the current selection, and that fileKey is accepted only for compatibility). The description mentions operating on 'a node' but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

The description names a specific verb (Get) and resource (the code-connect map), and details what is returned: a nodeId-to-code-component mapping plus the components not yet mapped. It is clearly distinguishable from add_code_connect_map and remove_code_connect_map by name and semantics, though it never explicitly names those siblings.

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

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

There is no statement of when to use this tool versus alternatives like add_code_connect_map, remove_code_connect_map, or the other read tools. The read-only intent is only implied by the word 'Get'. An agent gets no explicit routing guidance.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the return payload (reference code, assets, screenshot, variables), that the code must be adapted to the target project, framework-dependent output, and the large-node fallback governed by forceCode. This is material behavioral context an agent cannot 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?

Dense but front-loaded: purpose first, then return contents, then nodeId usage, then the large-node caveat. Every sentence contributes actionable information with no filler.

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

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

For a 12-parameter tool with no annotations and no output schema, the description covers the critical behaviors (output shape, framework selection, node targeting, size fallback). Remaining per-parameter Flutter nuances (screen, assetsDir, screenUtil) are left to the schema, which documents them at 100% coverage.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value beyond the schema by explaining the Figma URL → node id translation ('node-id=1-2' becomes '1:2') and the selection default, which the schema only partly states.

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

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

States a specific verb+resource ('Get design context for a Figma node') and explicitly positions itself as 'the primary tool for design-to-code workflows', distinguishing it from siblings like get_screenshot and get_metadata. It also enumerates the concrete artifacts returned (code, assets, screenshot, variables).

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?

Give clear operational context: nodeId specifies the node, the URL-to-node-id mapping is spelled out, and omission falls back to the current Figma selection. It also warns when large nodes yield metadata rather than code. It stops short of naming alternative siblings or when NOT to use this 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?

With no annotations, the description carries the burden and largely meets it: it discloses the XML output format, the default behavior when nodeId is omitted (returns pages and saved snapshots), and the injected 'Currently selected nodes:' block when a selection exists. It does not discuss result size limits or permission requirements, which is a modest omission for a read-only 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?

The routing warning is front-loaded ahead of the functional description, which is the right order for an agent deciding between tools. Sentences are dense and mostly earn their place, though the parenthetical page-id example slightly overlaps with schema documentation.

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

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

With no output schema and no annotations, the description must convey the return shape, and it does reasonably well: XML structure, field set, page-mode fallback, and the selection block. It stops short of noting what it deliberately omits (styles, variables, text content), which would help an agent decide against it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: nodeId may be a page id (e.g. 0:1), and omitting nodeId returns the document's pages rather than merely 'using the current selection' as the schema states. It also clarifies that fileKey is accepted for compatibility only and the desktop file is always used.

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 metadata for a node or page'), names the exact output format (XML), and enumerates the fields returned (node IDs, layer types, names, positions, sizes). It also explicitly positions itself against the sibling get_design_context, so an agent can distinguish it without opening either schema.

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

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

It names the alternative (get_design_context) and strongly deprioritizes itself with 'Always prefer to use get_design_context.' The implied use case ('useful for an overview of the structure') gives context, but it never states the positive condition under which this tool is the right pick, so it falls short of the full when/when-not/alternatives bar.

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

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

With no annotations, the description carries the burden and largely does so: it discloses the return payload (local URL, file path, width/height, original_width/original_height) and the resolution-capping behavior (maxDimension, up to 2x node size). It does not explicitly state side effects, permissions, or whether the file key is ignored beyond the schema note, but the payload disclosure is genuinely useful context.

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

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

Three dense sentences, front-loaded with what the tool does, then resolution semantics, then return shape. No filler or restatement of the name; every sentence carries new information.

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

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

There is no output schema, so the description correctly takes on the return-shape explanation, and a 5-param tool with full schema coverage is otherwise well served. The one gap is that contentsOnly is never explained in prose, leaving its practical effect to the schema alone.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: maxDimension "caps the longer edge," clarified as up to 2x node size, and enableBase64Response is framed as getting the image inline. It omits contentsOnly and fileKey behavior, which the schema covers instead.

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 ("Generate a screenshot") plus the target scope ("a given node or the currently selected node in Figma"). This distinguishes it from data-oriented siblings like get_metadata or get_design_context, but it never names an alternative, so the differentiation is implicit rather than stated.

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

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

Usage is only implied: "Omit it to use the current selection in Figma" tells the agent what happens without a nodeId, and "Set enableBase64Response to also get the image inline" hints at a workflow preference. There is no when-to-use-this-vs-download_assets or get_design_context guidance 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?

No annotations exist, so the description carries the whole burden, and it does so well: it declares the operation read-only, discloses the no-nodeId default, explains that values resolve against the node's own mode, and warns that without the plugin a saved snapshot yields raw values without names. These are non-obvious behaviors an agent 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?

Front-loads the core purpose and the example, then packs routing and caveats into a few tight sentences. The clause defining variables and styles is useful background but is the least load-bearing sentence; otherwise there is 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?

With two optional params, no output schema, and no annotations, the description supplies everything needed: what comes back (example value shape), how the node is chosen, how values are resolved, and what changes when the plugin is unavailable. Nothing essential is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including the omit-to-use-selection behavior and the fileKey compatibility note. The description adds only the mode-resolution context for the returned values, not node syntax or fileKey semantics. Baseline 3 is warranted.

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 ('Get variable definitions for a given node id') and grounds it with a concrete example value. It also pre-empts confusion with the get_design_context sibling by stating 'Use it for design tokens, and get_design_context for the layout.' The scope (resolvable design tokens attached to a node) 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?

Explicitly names when to use it ('design tokens') and names the alternative (get_design_context for layout), plus states the fallback when no nodeId is supplied ('with no nodeId it uses the selection'). It also flags the degradation path when the plugin is absent, which tells the agent when the output can and cannot be trusted for names.

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

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

With no annotations, the description carries the full burden and does so: it discloses that the file is copied into a local snapshot store, that an earlier snapshot of the same frames is replaced (overwrite/idempotency semantics), and that the source file and the Figma file are left unchanged. It also states the failure mode for non-export JSON. This is unusually rich behavioral disclosure for an unannotated tool.

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

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

Four sentences, all of which carry information, with the core purpose front-loaded before the operational details. It is slightly denser than needed but there is no padding 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 one-parameter, unannotated tool with no output schema, the description covers mutation semantics, source safety, and failure behavior, which is most of what an agent needs. It stops short of describing what the call returns (e.g., a snapshot handle) that would be read back later, which is the only meaningful remaining gap.

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

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

Schema coverage is 100% and the sole parameter already documents itself as 'Absolute path of the export JSON file.' The description adds context about what that JSON should contain ('frames with node trees, as the plugin produces'), but no new syntactic or format guidance. Baseline 3 when the schema does the heavy lifting.

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

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

States a specific verb+resource (import a design export JSON as a snapshot) and explains the payoff ('so its nodes can be read without the plugin'). It explicitly separates itself from the sibling that produces such exports ('an export made earlier with save_design_export or the plugin'). An agent can distinguish it from save_design_export without opening either schema.

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

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

Gives clear context for when to reach for it ('Use it for an export made earlier with save_design_export or the plugin') and names the failure condition ('Fails if the JSON is not a design export'). It does not spell out an explicit when-not-to-use case or a preferred alternative for other situations, so it falls short of a 5.

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

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

With no annotations provided, the description carries the full burden and does so well: it discloses format-dependent results, that nodeId replaces/creates fills (and is invalid for SVG), where the new layer is placed by default, how sizing defaults work, and a real platform constraint ('Images larger than 4096 px on a side are scaled down by Figma'). It also warns that fileKey is ignored in favor of the open desktop file.

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

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

A single dense paragraph with zero filler; the core action leads, followed by format outcomes, the alternative tool, and placement/sizing defaults. Every clause carries information an agent needs to call it correctly.

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

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

For an 11-parameter mutation tool with no annotations and no output schema, the description covers outcomes, placement, sizing, limits, and the sibling alternative. It stops short of describing what is returned (e.g., the created layer's id) and leaves x/y and scaleMode/keepFills entirely to the schema, which is a minor but real gap.

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

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

Schema coverage is 64%, and the description compensates on the weakest spots: width/height have no schema description but are explained ('one keeps the aspect ratio; default: the image's own size'), as are nodeId, parentId defaults, and fileKey. However x/y placement and scaleMode/keepFills behavior get no narrative treatment in the description beyond their schema text.

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

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

States a specific verb and resource ('Put an image file from this computer into the file open in Figma Desktop') and immediately names the outcome variants (raster -> image-fill rectangle, SVG -> editable vectors). It explicitly contrasts itself with the sibling use_figma, so an agent can distinguish the two without opening either schema.

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

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

Gives an explicit when-to-use rule ('Use it for the project's own assets (logos, icons, photos) while designing') and names the alternative with its exact call signature ('use_figma with figma.createImageAsync(url) takes images from the web'). It also states a within-tool branch condition (nodeId applies to fills and is not for SVG).

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

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

With no annotations, the description carries the full burden and does well: it discloses that only the local mapping file changes and never the design, and that the return value is the number of mappings removed (0 when none existed). It omits auth/permission requirements and any side effects on other consumers, so it is not exhaustive.

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

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

Front-loaded with the action and effect, then the parameter, then the scope guarantee and return value, closing with the undo path. Every clause 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 simple two-parameter mutation with no annotations and no output schema, the description covers the action, its scope limitation, the return value, and the reversal path. An agent has everything needed 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 100%, so the schema already documents nodeId (with pattern and instance-id examples) and fileKey. The description adds only that an instance, component or component set id is acceptable, which is largely redundant with the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (Remove) and resource (the code component mapping), and immediately scopes it against siblings by naming add_code_connect_map as the source and get_design_context as the consumer. An agent can distinguish it from add_code_connect_map/get_code_connect_map without opening any schema.

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

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

Gives clear context: use it to stop get_design_context from naming a component, and points to add_code_connect_map as the inverse operation to undo. It does not explicitly state exclusions or prerequisites (e.g. permissions, whether the node must currently be mapped), so it stops short of a full when/when-not treatment.

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

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

With no annotations, the description carries the burden and does well: it discloses the default target (the selection), the default destination (data folder), and exactly what the file will contain (tree, paints, styles, SVGs, renders, 2x preview). It stops short of file-level side effects such as overwriting an existing path or 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?

Two sentences, front-loaded with the action and scope, followed by a short purpose statement. The content list in sentence one is long but each item is informative rather than padding.

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

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

No output schema and no annotations, yet the description explains what gets written to disk, where, and from which node, which is everything an agent needs for a file-writing export tool. Return value detail is unnecessary since the artifact is the JSON file itself.

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

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

Schema coverage is 100%, so the schema already documents path, nodeId and fileKey, including the 'omit to use the current selection' default and the fileKey compatibility note. The description repeats the selection/path defaults without adding syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Write a full design export of a node ... to a JSON file') and scopes the default operand (the selection). The enumeration of exported content clearly separates it from siblings like import_design_export, download_assets and get_screenshot.

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

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

One use case is given ('hand a frame to a build script'), which implies when to reach for it, but there is no explicit when-not guidance or named alternative (e.g., get_design_context vs download_assets). Usage is implied rather than stated.

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

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

With no annotations, the description carries the full burden and does well: it discloses the prerequisite (plugin and Design mode), a real limitation (libraries not yet used by the file are invisible to the plugin), and the meaning of the instancesNotScanned field. What is missing is anything about result caps or how the limit interacts with the per-kind results, so the behavioral picture is strong but not exhaustive.

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

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

Purpose and scope are front-loaded in the first sentence, and each following sentence adds distinct information (query semantics, when to call, reuse recipe, caveats). It is dense rather than padded, though the inline figma API call recipe is long and could be tightened without losing meaning.

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 five-parameter read tool with no output schema and no annotations, the description covers what is returned per kind, the matching semantics, when to invoke it relative to use_figma, prerequisites, and known blind spots. An agent has everything needed to call it correctly and interpret the results.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by defining query semantics (every word must appear in name or description; empty lists everything) and by clarifying the visible scope that kinds draws from. It does not add anything for allPages or limit beyond what the schema already says.

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

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

States a specific verb (Search) and resource (the design system of the open Figma file), then enumerates exactly what is covered: local components/component sets with properties and variants, used library components with an instance to copy, and local styles/variables with default-mode values. This is enough for an agent to distinguish it from siblings like get_design_context or get_variable_defs without opening the schema.

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

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

Explicitly instructs 'Call it before designing with use_figma' and describes the follow-up reuse pattern (getNodeByIdAsync + createInstance, clone, getStyleByIdAsync, getVariableByIdAsync). It also states the query matching rule and the empty-query fallback ('leave it empty to list everything'), leaving no inference required.

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

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

With no annotations, the description carries the full burden and does so richly: it discloses undo semantics ("one undo step"), partial-failure behavior (changes before a throw persist), class-scoping of `code`, what is returned (nodes as {id, name, type, x, y, width, height} plus console.log), and many API constraints. These are exactly the side-effect and failure traits an agent needs before executing arbitrary code.

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?

Long, but front-loaded with purpose and structured as a scannable rules list where each bullet is directly actionable for writing plugin-API code. Some API detail (colour format, auto-layout properties) is verbose, but for a code-execution tool the density is largely justified and nothing reads as 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 no-annotation, no-output-schema code-execution tool, the description supplies what an agent needs to call it correctly: input contract, return shape, error behaviour, environment constraints, and a workflow loop with sibling tools. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema for `code` by specifying it is the body of an async function with `figma` in scope, that await should be used, and what a returned value looks like, which shapes how the agent authors the parameter. It adds little for fileKey/timeoutMs, but those are already fully documented in the schema.

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

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

States a specific verb pair and resource ("Create or edit designs in the file open in Figma Desktop") plus the mechanism (running JavaScript against the Figma plugin API). This is clearly distinguishable from siblings like get_screenshot, place_image, or search_design_system, which are read/lookup 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?

Routes the agent to siblings explicitly: use search_design_system first to reuse components/styles/variables, place_image for local files, and get_screenshot to check each step. It also frames the workflow ("Build a screen in a few calls... return the ids"). It lacks an explicit when-not-to-use statement, but the conditional routing is clear and actionable.

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

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

With no annotations, the description carries the full burden and does so richly: it discloses the return artifacts (analyzer errors, runtime errors such as overflows/missing assets, differing-pixel share, diff image), runtime cost (20 seconds to a few minutes), and fidelity caveats (fallback fonts for missing fonts, emoji lacking color fonts shifting subsequent text). These are exactly the traits an agent needs to interpret results.

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

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

The core purpose and outputs are front-loaded in the first sentence, and subsequent sentences add mode-specific instructions, a usage trigger, caveats, and timing. It is dense but nearly every clause carries information; the only mild cost is that the mode differences are packed into a single paragraph.

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

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

Despite having no output schema and no annotations, the description fully explains return values, both execution modes, preconditions for the `file` path, and the runtime envelope. For a verification tool with seven optional parameters, an agent has everything required to invoke and interpret it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning beyond the schema: it explains that `file` runs the widget inside its own Flutter project with its packages/assets, inside a MaterialApp, scaled by flutter_screenutil, and that the widget needs an argument-less constructor. It also clarifies that `viewport` switches from comparison to overflow/off-screen reporting.

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 ('Check Flutter code against the design') and goes further to explain the mechanism (flutter test at 2x, comparison with Figma's 2x render) and the exact outputs. An agent can distinguish this verification tool from siblings like get_design_context or get_screenshot without opening any schema.

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

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

It gives a clear condition for use: 'Use it after implementing a frame, and fix what it reports', and it distinguishes the two operating modes (with `file` vs without). It stops short of naming sibling tools or explicit when-not-to-use exclusions, so it lands just below the top tier.

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

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

With no annotations, the description carries the full behavioral burden, and it discloses the entire return payload (connection state, pairing code, current file/page/selection, project/Code Connect file, snapshots). It does not describe failure semantics or how to interpret the pairing code, which are minor gaps for a read-only status 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?

Two sentences: purpose plus a field inventory, then the usage trigger. It is front-loaded with the resource and wastes little, though the comma-separated field list is dense.

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

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

No output schema exists, so the description must describe the return values — and it does, itemizing the status fields. An agent has enough to know what it will receive and when to call it; only interpretation guidance for the pairing code is missing.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate and no schema gap to compensate for.

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 resource — the local Figma connection status — and enumerates exactly what it reports (connection state, pairing code, open file/page/selection, project and Code Connect file, saved snapshots). The generic name 'whoami' is fully rescued by the description, though it does not explicitly contrast itself with siblings like get_metadata or get_design_context.

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

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

It gives a concrete trigger: 'Use it when a read fails,' which tells the agent this is a diagnostic fallback. It offers no exclusions or named alternatives, but for a zero-param diagnostic tool the single condition is sufficient context.

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