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 the key trait: local-only, no cloud session, no document switch. It omits lifecycle details an agent would want (does the session expire, is calling twice with the same fileKey idempotent, does passing sessionId re-attach to an existing session).

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 followed by the reuse rule and the disclaimers. 'Reuse it across calls, including explicitly selected other files' is slightly compressed and takes a second read, but nothing 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?

A creation tool with no output schema and one undocumented required parameter. The description implies a UUID is returned and covers the local-vs-cloud scope well, but leaves the agent guessing about the purpose of 'description' and about session lifetime.

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

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

Schema coverage is 67%: fileKey and sessionId are documented in the schema, but the required 'description' parameter has no schema text and no explanation in the tool description either. The description adds no syntax or format meaning beyond the schema, so baseline 3 fits.

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

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

States a specific verb and resource ('Create a local task recording UUID') and immediately scopes it to 'the selected Figma file'. The final sentence distinguishes it from what an agent might otherwise assume (cloud session creation, document switching), which no sibling tool covers.

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?

'Reuse it across calls, including explicitly selected other files' tells the agent this is a per-task token rather than a per-call one, and the negative clause rules out two wrong intents. It stops short of naming an explicit alternative tool or a prerequisite sequence (e.g., call figma_status first), so not 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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that outputs are saved under .figma/assets and that original image bytes can optionally be included, but it omits key behavior such as overwrite semantics, batch limits (20 nodeIds), selection fallback, and any permission or rate-limit concerns for a filesystem-writing 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 tight sentences with no waste. The core purpose and output location are front-loaded, and every clause adds practical 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 five-parameter export tool that writes files to the workspace and has no annotations or output schema, the description is too thin. It should cover selection defaults, nodeIds batching, scale defaults, and overwrite/file-existence behavior to be complete enough for reliable invocation.

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

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

Schema description coverage is only 20%, with just nodeId documented in the schema. The description adds meaning for format choices and includeOriginalImages, but it does not explain scale (0.01–4), nodeIds batching, or the nodeId-vs-selection behavior, leaving most parameters underspecified.

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

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

The description states a specific verb and resource: 'Export nodes to workspace files' with supported formats PNG/JPG/SVG/PDF. It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as upload_assets or 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?

There is no guidance on when to choose this tool over alternatives like upload_assets, get_screenshot, or get_design_context. Usage is only implied by the word 'Export', with no conditions, exclusions, or prerequisites mentioned.

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

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

No annotations are provided, so the description carries the full behavioral burden. It implies a stateful effect (subsequent operations target the chosen file) but never states whether the selection persists across calls, applies per-session, or what happens with an invalid/stale connectionId — meaningful gaps for a state-setting 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 short sentences with zero filler: the condition first, then the parameter source. Every sentence earns its place and the most actionable detail (where to get the id) is not buried.

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

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

For a one-parameter selector with no output schema, the description covers what it does, the triggering condition, and the parameter's origin. What's missing — persistence of the selection and error behavior for unknown ids — is minor but not negligible for a state-changing tool with no annotations to lean on.

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 0%, so the bare string 'connectionId' would be opaque; the description compensates by telling the agent exactly where the value comes from (figma_status). It still lacks any format/example or validity notes, keeping it below a 5.

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

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

States a specific action: choose which Figma file to operate on when several are connected, and names connectionId as the selector. It is distinguishable from siblings like figma_status (which produces the id) and use_figma (which presumably consumes it), though the verb 'select' is only implied by 'specify which one to operate on' rather than stated as a tool name verb.

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 trigger condition: 'when multiple Figma files are connected simultaneously', and routes the agent to figma_status to obtain the required id. It does not say what to do when only one file is connected (skip this tool?) or whether selection must precede other calls, so the exclusions are incomplete.

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, so the description carries the burden. It does disclose the meaningful behavior — it writes a plugin scaffold to the local machine and returns an import path — which implies filesystem side effects. However it says nothing about overwrite semantics, whether it needs Figma running, or what happens on repeat invocation, which matters for a setup 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, zero waste: the first defines the action and its output, the second gives the invocation condition. Front-loaded and appropriately sized for a no-parameter 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?

With no input params and no output schema, the description supplies what the agent needs: that a manifest.json path is returned and when to call it. Minor gap is the absence of any note on prerequisites (e.g. pairing state or Figma being open) before this can succeed.

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

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

The tool takes zero parameters, so there is nothing to disambiguate; baseline 4 applies. The description appropriately spends its words on behavior and return value instead of parameters.

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 (生成 / generate) and resource (本机已配对的 Figma 伴生插件) plus the concrete artifact returned (manifest.json 路径). An agent can tell this is a setup/bootstrap tool distinct from runtime siblings like use_figma or get_design_context, though it never names a sibling 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?

The trailing clause '首次使用或重装时调用' gives an explicit trigger condition (first use or reinstall), which is the key usage signal for an idempotent setup tool. It stops short of stating alternatives or what to do if the plugin already exists, but the context is clear.

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

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

With no annotations, the description carries the full burden, and it does disclose the payload contents (document, plugin version, bridge status), so an agent knows what to expect back. However, it says nothing about what happens when no Figma document is connected — whether it errors, returns a null, or reports a degraded state — which is the key behavioral question for a health-check tool. Adequate but incomplete.

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

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

Two short sentences with no filler: the first defines what is inspected, the second front-loads the call-timing advice. Nothing could be removed without losing information.

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

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

For a zero-parameter tool with no output schema, the description covers what it reports and when to call it, which is what an agent needs to select and invoke it correctly. The only meaningful gap is unstated behavior in the disconnected/failure case.

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, which is the baseline-4 case; there is nothing for the description to disambiguate. The description correctly implies a no-argument call, consistent with the empty schema.

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

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

The description states a specific verb (查看/view) and three concrete resources: the connected Figma document, the plugin version, and the bridge status. That makes it clearly a diagnostic/status tool, distinguishable from action-oriented siblings like use_figma or create_session. It stops short of naming a specific sibling it should be preferred over, so it lands at 4 rather than 5.

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

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

It gives two explicit trigger conditions: on first use, and after an operation fails ('第一次使用、或操作失败后先调这个'). That is more concrete than most tools offer. There is no when-not guidance and no alternative tool is named, so it falls short of the top score.

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

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

With no annotations, the description carries the full behavioral burden. It implies a read-only operation but says nothing about selection fallback behavior (nodeId is optional), truncation when maxBytes/maxNodes budgets are hit, or whether screenshots are included; those limits are only implicit in the schema bounds.

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

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

A single front-loaded sentence with no filler. It is efficient, though it is arguably too terse given the tool's five parameters and missing behavioral context.

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 five parameters, no output schema and no annotations, the description leaves major gaps: return shape, default behavior, selection fallback and truncation semantics are all unstated. What the description needs to carry, it does not.

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

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

Schema description coverage is 60%: nodeId, profile and maxBytes are documented, but depth and maxNodes have no description anywhere. The description adds no parameter meaning at all, so it fails to compensate for the undocumented traversal and node-count parameters.

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 ('component, component set or instance properties and descendants'), so the scope is clear. It does not distinguish itself from siblings like get_design_context or get_metadata, which appear to overlap.

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 indication of when this should be used instead of get_design_context, get_metadata or get_motion_context. The agent must infer the choice from the name alone, and the one bit of guidance present ('summary for discovery; full preserves detailed fields') lives in the schema, not the description.

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

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

No annotations are provided, so the description bears the full disclosure burden. It usefully reveals a non-obvious default (screenshots included unless includeScreenshot:false) and a scope limit ('no cloud code generation'), but says nothing about permissions, whether the operation is read-only, or how output is shaped when the budget is hit.

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

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

Three tight sentences with zero filler, and the core purpose is front-loaded ahead of the alternatives and defaults. Minor density jargon ('native properties', 'cloud code generation') slightly reduces first-read clarity but costs little.

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 eight-parameter tool with no annotations and no output schema, the description covers purpose, the key default, and alternatives, but does not describe the returned structure or how the depth/maxNodes/maxBytes budgets interact. Adequate, with a visible gap around what the agent will actually receive.

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 only 50%, yet the description adds real meaning for two of the eight parameters: the includeScreenshot default and the quality/scale interaction are clarified in prose. It still leaves depth, maxNodes, maxBytes, and nodeId semantics to the schema, so the gap is only partly compensated.

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 concrete verb and resource ('Read a target subtree and CSS for design-to-code work'), which tells the agent exactly what comes back. It partially differentiates from siblings by naming get_metadata as the lighter alternative, though the boundary with get_screenshot and get_component_context is left implicit.

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

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

Gives explicit when-not guidance ('do not read an entire subtree for a few descendant values'), names concrete alternatives (bounded get_metadata or one scoped script), and states a conditional default for screenshots. An agent can decide between this and the sibling read tools without further inference.

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

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

With no annotations provided, the description must carry the behavioral burden. It usefully discloses that screenshots are included by default and that includeScreenshot:false is appropriate for structural checks, but it does not describe permissions, read-only semantics, output format, truncation behavior, or how omitted nodeId falls back to editor selection.

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

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

The description is two short, front-loaded sentences with no wasted text. It states the tool's purpose first and the key operational tip second. The only minor gap is that it could have packed slightly more routing guidance into the same concise format.

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 8-parameter tool with no annotations and no output schema, the description is quite thin. It covers purpose and the screenshot default, but omits return-format expectations, truncation behavior, nodeId fallback semantics, and guidance for several undocumented parameters. The schema covers some of this, but the description does not fill the remaining 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 50%, and the description adds meaning for includeScreenshot and its default behavior. It does not compensate for the undocumented parameters such as depth, scale, and maxNodes, so the parameter semantics remain partial rather than complete.

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

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

The description states a specific verb and resource: 'Read FigJam structure.' This is clearer than a tautology and distinguishes the tool from sibling tools like get_screenshot or get_design_context by naming FigJam as the target resource. It does not explicitly contrast itself with those siblings, so it stops short of a 5.

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

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

The description gives one concrete usage rule: set includeScreenshot:false for structural checks, because screenshots are included by default. However, it provides no guidance on when to choose this tool over get_screenshot, get_design_context, or get_metadata, and no exclusions or prerequisites are mentioned.

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, so the description carries the full burden. 'Read' implies a non-mutating operation, and 'public Plugin API' hints at an access path, but there is no disclosure of whether a session/plugin connection is required, whether results are cached, or what a 'library' object contains.

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

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

A single front-loaded sentence with no filler. The access-path qualifier is placed where it adds context without delaying the core statement.

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

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

With no annotations and no output schema, the description is the only source of behavioral and return-value information, and it says nothing about what the returned libraries look like or how to use them. For a no-param discovery tool this leaves a real gap in understanding 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?

The tool takes zero parameters, so the baseline is 4. Nothing in the schema needs explanation, and the description doesn't introduce any confusing parameter-like language.

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

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

States a specific verb and resource: 'Read available team variable libraries'. The 'public Plugin API' qualifier narrows scope further. It doesn't explicitly differentiate from siblings like get_variable_defs or search_design_system, which touch the same variable/design-system domain.

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

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

No guidance on when to call this versus get_variable_defs, search_design_system, or get_design_context — all plausible alternatives for variable-related data. The agent must infer the distinction from names alone.

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

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

No annotations are provided, so the description carries the full burden. It usefully signals a read operation and distinguishes plugin data from published mappings, but says nothing about permissions, auth requirements, return shape, pagination, or behavior when no links exist.

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 resource, followed by a concise data-source clarification. No wasted language.

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 one-parameter read tool with fully documented schema and no output schema, the description is mostly complete: it identifies the resource and the data source distinction. It lacks explicit usage alternatives and return-value information, but the core selection context is covered.

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

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

There is one required parameter, nodeId, with 100% schema description coverage including the editor-selection fallback. The description adds no additional parameter semantics, 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?

States a specific verb (Read) and resource (local DSH component-to-code links), and clarifies that this is plugin data rather than published Code Connect mappings. This distinguishes the data source, though it does not explicitly name the closest sibling such as set_local_component_links or get_component_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?

Implies the tool is for reading local plugin-stored component links rather than published Code Connect mappings. However, it gives no explicit when-to-use guidance, no exclusions, and does not mention alternatives like get_component_context or search_design_system.

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

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

With no annotations, the description carries the full burden and does disclose the important traits: bounded reads, truncation continuations to follow, cross-parameter preconditions for paging, and a safe-read/reconciliation rule. It omits auth or plan requirements and says nothing about error behavior or what a truncated response actually looks like.

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

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

Front-loaded with purpose then constraints; nearly every clause carries a rule an agent needs. 'Follow truncation continuations' is dense to the point of jargon — it tells the agent to do something without saying what a continuation looks like.

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 7-parameter, no-annotations, no-output-schema tool this is close to sufficient: it establishes the read-only profile, the paging model, and the default return shape (pages and current page). The gap is the response envelope under truncation and the maxBytes/maxNodes budget interaction, neither documented here nor in an output schema.

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

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

Schema coverage is only 43%, and the description compensates by adding real cross-parameter semantics absent from the schema: offset/limit page *direct children* and require nodeId with depth >= 1, plus the discovery-vs-full profile tradeoff. maxNodes and maxBytes (the two budget knobs) get no explanation in either the description or, for maxNodes, the schema.

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

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

States a specific verb and resource ('Read a bounded layer tree') and immediately names the cheaper mode ('prefer summary for discovery'). However, it never distinguishes itself from sibling tools like get_design_context, get_component_context or get_selection, so an agent must infer when this tree read beats those.

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 selection rules: omit nodeId to get pages plus current page, use offset/limit to page direct children, prefer the summary profile for discovery, and the constraint that only unpaged/unprofiled reads can reconcile an uncertain write. It stops short of naming any alternative tool it competes with.

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

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

With no annotations, the description carries the full behavioral burden, yet it only says data is read 'when exposed' and that cloud timeline/code conversion is not emulated. It says nothing about what failing/empty results look like, whether it requires an active editor session, or what is actually returned.

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?

It is short and the read-purpose is front-loaded, but the second sentence is jargon-heavy and its relevance to selecting or invoking the tool is unclear, so it does not fully earn 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 tool with no annotations and no output schema, the description should compensate by explaining the return content and preconditions. Instead it leaves the agent unsure what 'public motion data' or 'reactions' look like and when the call will yield nothing.

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

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

There is a single optional parameter documented at 100% schema coverage, so the schema already explains nodeId and the selection fallback. The description adds no extra meaning about how nodeId affects behavior, 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 verb and resource ('Read prototype reactions and public motion data'), which gives a rough sense of purpose, but the hedge 'when exposed' and the opaque clause 'Cloud timeline/code conversion is not emulated' blur what the tool actually returns. It never distinguishes itself from near-siblings like get_design_context or get_component_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?

There is no statement of when to call this versus the many siblings that read Figma design content. The only guidance is the implicit limitation 'when exposed', which tells the agent nothing about how to choose between this tool and get_design_context.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the key trait that the result is a real PNG image attachment rather than a URL or metadata, plus the exportable-node requirement. It says nothing about failure modes, selection fallback behavior, or how the 800/1600px caps interact with the output.

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 return format stated first and the constraint 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 3-parameter tool with no annotations and no output schema, the description covers the essential contract (returns a PNG attachment, needs an exportable node). It leaves unaddressed what happens with no nodeId when the editor has no selection, and gives no sense of the output's dimensions given the quality/scale controls.

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 67% – nodeId and quality are documented in-schema, including the overview/detail presets and explicit-scale override. The description adds no parameter meaning of its own and leaves `scale` (0.01–4) with only type bounds, so it neither compensates for the gap nor detracts.

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?

"Return an actual PNG screenshot" names a specific verb and output format, and "as a DSH image attachment" clarifies the delivery mechanism. It does not distinguish this from adjacent tools like download_assets or get_figjam, so an agent must infer the routing itself.

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?

"Requires an exportable node" is a real precondition, which is more than most tools offer. But there is no statement of when to prefer this over download_assets/get_figjam, and no mention of what to do when the node is not exportable.

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

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

No annotations exist, so the description carries the full behavioral burden, and it discloses almost nothing: no return shape, no indication of what happens with no selection, no mention of size limits or truncation behavior despite maxBytes/maxNodes params. Only the word "Read" implies a non-mutating 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 short, front-loaded sentences with no padding. The second sentence, however, duplicates what the schema already states about the profile enum, so it doesn't fully earn 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 tool with no annotations, no output schema, and three parameters, the description is too thin — an agent cannot tell what is returned, whether results are truncated, or how it relates to sibling read tools.

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

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

Schema coverage is 67% and the description adds no meaning beyond it — the profile hint restates the schema text almost verbatim. maxNodes has no description anywhere, and the interaction between maxBytes/maxNodes and truncation is never explained.

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 concrete verb and resource: read the current page and selected nodes. It doesn't explain how it differs from likely-overlapping siblings such as get_design_context, get_metadata, or get_screenshot, so the agent must infer the boundary.

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?

"Prefer summary for discovery" is guidance about a parameter value, not about when to call this tool instead of the many sibling read tools. There are no exclusions or preconditions (e.g., whether a session or active selection is 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 burden and discloses several non-obvious behaviors: collectionsOnly does not read variables, returned collections may not be a complete inventory, pagination/coverage must be checked before concluding absence, summary omits values, and no arguments preserves full results. It does not cover permissions or rate limits, but the key behavioral caveats are present.

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

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

The description is compact and front-loads the main purpose. Most sentences add concrete behavioral information, though phrases like 'Otherwise collections describe...' are slightly ambiguous and reduce readability.

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

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

This is a complex 9-parameter tool with no output schema and no annotations, so the description needs to be fairly complete. It covers core modes and important caveats, but omits explanations for type, modeIds, and limit/offset semantics, leaving an agent to infer too much from 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 description coverage is low at 22%, so the description should compensate. It adds useful meaning for collectionsOnly, query, requested IDs, summary/profile, pagination, and no-argument behavior, but it does not explain type, modeIds, limit/offset bounds, or several parameter interactions, leaving significant schema gaps.

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

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

The description states a specific verb and resource: it reads local variables or collection inventory. It also distinguishes two operating modes through collectionsOnly, though it does not explicitly differentiate itself from sibling tools.

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

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

It explains that collectionsOnly:true is for listing collections and that query then filters collection names, which is useful conditional guidance. However, it does not explicitly state when to use this tool versus alternatives or name any sibling tools, so usage guidance is implied rather than fully specified.

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

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

No annotations are provided, so the description carries the full disclosure burden. It says nothing about that this is a mutating write operation, permission or session requirements, what happens to existing nodes under parentId, failure/partial-import behavior, or the 500-node cap that the schema imposes.

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

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

Two front-loaded sentences plus a reference pointer, with zero filler. The core purpose precedes the alternative-tool caveat in the right order.

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

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

Given the loose nested schema and absence of an output schema, the description would benefit from noting the return value and how the scene JSON maps to nodes. However, the explicit pointer to the scene reference partially offsets the missing parameter detail.

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

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

Schema description coverage is 0%, so the description must compensate, yet it never explains the 'nodes' array shape (type/props/children recursion) or the optional 'parentId'. 'See the scene reference' is an external pointer rather than semantic guidance, leaving both parameters underspecified.

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 ('Import a local JSON scene as native editable Figma nodes') and names the sibling it is not suited for. An agent can distinguish it from use_figma 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?

Explicitly routes complex cases (components, variables, graphs, Slides) to use_figma, giving a clear alternative. It stops short of stating full preconditions such as where the JSON comes from or whether a session/parent must exist.

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 at all, the description carries the full burden, and it does disclose the single most consequential behavioral trait: the return shape changes based on arguments (legacy array with no args vs. fonts plus pagination otherwise). That is real value beyond structured fields. It falls short of a 5 because 'return fonts and pagination' is never explained — no mention of total counts, page size behavior, or that filtering is presumably read-only and side-effect free.

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, both doing work, with the core capability front-loaded and the invocation-dependent behavior immediately after. There is no filler, preamble, or repetition of the tool 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?

Given five undocumented parameters, no annotations, and no output schema, the description covers the riskiest fact (dual response shape) but leaves material gaps: parameter meanings, matching semantics, and what 'pagination' actually contains. It is enough to attempt a call but not enough to call it confidently or to predict the response structure.

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?

Five parameters with 0% schema description coverage, so the description must compensate and largely does not. It refers vaguely to 'filters' and 'pagination' without mapping them to query, style, family, limit, or offset, and never says whether query/style/family are substring, prefix, or exact matches. An agent can only guess that query/style/family are the filters and limit/offset the pagination.

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: 'Find available font families and exact styles,' which is clearly a lookup of font options. No sibling tool in the list deals with fonts, so there is no ambiguity to dispel, but the description also does not differentiate from anything. Clear, though not maximally sharp about what a 'font family' vs 'exact style' record contains.

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 does give invocation-mode guidance: call with no arguments to get the legacy array, or supply filters/pagination to get the richer response. That is useful implied usage, but there is no statement of when to prefer one mode, no prerequisites, and no alternative tools named. An agent must infer which mode it wants from the response-shape sentence alone.

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

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

No annotations exist, so the description carries the full burden. It does disclose real behavior beyond the schema: results return in query order, pagination is per kind, components are scoped to the current page unless pageId is supplied, and there is no cloud/Code Connect coverage. It omits permissions/auth, whether results are capped, and any indication of what a result object contains.

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 dense sentences with the core scope stated first and constraints after; nothing is padding. The telegraphic phrasing ("queries batches {entity,query} searches") is slightly awkward to parse but costs no length.

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 tool with no annotations and no output schema, the description covers scope and query batching but leaves the pagination contract (how limit/offset interact with per-kind paging) and return payload shape unexplained. An agent could invoke it, but would likely need a probing call to understand 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?

With only 27% schema description coverage across 11 parameters, the description has to compensate and does so for a subset: queries as batched {entity,query} pairs, legacy query/kind, and pageId's effect on component scope. limit, offset, includeLibraryKeys, disableCodeConnect, and fileKey get nothing here beyond their bare schema, so the gap is only partially closed.

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

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

Opens with a specific verb+resource pair ("Search local components, variables and styles") and immediately scopes it to local assets, which distinguishes it from library-oriented siblings like get_libraries. It stops short of naming a sibling outright, so an agent must infer which tool to use for cloud/library lookups.

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 cloud component-library or Code Connect search" is a useful exclusion, and "Legacy query/kind also supported" clarifies which parameter form is preferred. However, it never says when to reach for search_design_system versus get_component_context, get_variable_defs, or get_libraries, so the alternative-routing is left implicit.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the storage target and that nothing is published, but says nothing about whether existing links are replaced or merged, permission requirements, the 100-item limit, or what happens on failure — significant gaps for a mutation tool.

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

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

Two sentences, zero filler, with the core action front-loaded and the scope exclusion immediately following. Nothing is redundant with the tool name alone.

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, nested-object write operation with no annotations and no output schema, the description is thin. It should convey write semantics (overwrite vs append), required permissions or plugin-mode context, and what the 'links' payload represents, none of which are covered.

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

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

Schema coverage is only 50%: nodeId is documented in the schema, but the required 'links' array and its 'name'/'source' fields have no description anywhere. The description adds no meaning about what a link name or source should contain, so the coverage gap is not compensated.

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 ('Save local component-to-code links') plus the storage location (Figma plugin data), and its negation 'Does not publish Code Connect' scopes it clearly against a publishing counterpart. It does not name the read sibling get_local_component_links, so sibling differentiation is implied rather than explicit.

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?

'Does not publish Code Connect' is a useful exclusion that tells the agent which adjacent operation this is not. However, there is no positive trigger condition (when to prefer this over publishing) and no named alternative such as get_local_component_links or a publish tool, leaving usage mostly inferable.

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 disclosure burden. It usefully reveals the transformation semantics (raster/SVG becomes editable SVG layers or image fills) and a source-location restriction, but says nothing about whether files are copied or referenced, what happens on partial failure, or whether existing content is affected.

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. The capability statement comes first and the constraint second, which is the right front-loading for a quick scan.

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 annotations and no output schema mean the description is the only source of behavioral detail, and it covers the core operation adequately. The undocumented `parentId` and the absence of any return-value or batch-failure information leave meaningful gaps for an upload 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% across 2 parameters, so the description must compensate and only does so for `files` (raster/SVG, inside the Work workspace). The `parentId` parameter is never mentioned anywhere, leaving the agent with no idea where the imported layers will land.

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 (import) and resource (workspace raster/SVG files) and states the outcome: editable SVG layers or image fills. That distinguishes it from siblings like download_assets and import_scene, though it never explicitly contrasts with import_scene, which sounds close in function.

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

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

It gives one real precondition – files must live in the current Work workspace – which is actionable usage context. But it offers no guidance on when to choose this over import_scene or other import paths, and no exclusions or failure conditions beyond the workspace constraint.

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 what is supported (top-level await/return, query/result, auto layout, screenshots, io.write), that page context resets each call, that return values are affected IDs, and that errors carry safeToRetryWithoutCanvasRead. Remaining gaps are environmental rather than behavioral: it doesn't say what mutations can destroy or what permissions are needed.

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?

Sentences are short, front-loaded with the core action, and each carries a distinct operational fact: prerequisites, supported capabilities, session inputs, page-context constraint, return value, error field, featureVersion gate. 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 code-execution tool with no annotations and no output schema, it covers return shape (affected IDs) and error metadata, and points to figma-workbench for the API contract. But it leaves the actual API surface and failure modes largely to that external document, so a caller without that context is not fully equipped.

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 60%, so some parameters are documented only in the schema. The description adds provenance for description, fileKey and sessionId (they come from create_session), which is useful. However, the required code parameter and skillNames receive no semantic detail beyond what the schema already provides.

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

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

States a specific verb and resource: run JavaScript against the selected local Figma document. It is clearly the code-execution entry point among siblings. The phrase 'figma-use 16 contract' is opaque without prior context, which slightly weakens clarity for a first-time caller.

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 tells the agent to read figma-workbench first and to include description, fileKey and sessionId from create_session, establishing prerequisites and the cross-tool workflow. It adds a page-context rule (starts at first page, switch at most once). It does not name when another sibling should be used instead, so it stops short of full when/when-not guidance.

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