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

The description discloses the byPlugin tagging heuristic with its exact time window and states that such changes are hidden by default. This goes well beyond the readOnlyHint annotation and tells the agent that attribution is heuristic, not guaranteed.

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, each earning its place: purpose, the byPlugin heuristic, and the continuation protocol. The most important scoping information is front-loaded.

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 polling tool with no output schema, the description provides enough to invoke it correctly: what is returned, the seq continuation contract, and how to include plugin changes. The exact shape of change entries is not specified, but the per-node summary and seq are sufficient guidance.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds meaningful usage semantics for since ('pass back the returned seq') and for includePlugin (plugin changes are hidden by default), raising it above the baseline.

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

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

The description states exactly what the tool returns: file changes since a previous call, broken into node creations, deletions, and property changes with a per-node summary. The 'since a previous call' scope differentiates it from generic status or history tools even without naming a sibling.

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 usage pattern: pass back the returned seq as since, and explains that plugin-triggered changes are hidden by default so the tool shows human edits between calls. It does not explicitly name alternatives or exclusion conditions, but the intended use case 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?

Beyond the lone openWorldHint annotation, the description discloses critical runtime behavior: async wrapping, available globals, JSON serialization with node collapsing, resize() side effects on text/auto-layout frames, undo checkpointing, and the need for helpers.reveal(). It also explains font loading requirements before text mutation. This is unusually transparent for a code-execution 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 description is long but every sentence earns its place; it uses bullets to separate behavioral gotchas and a compact helper reference. The main purpose is front-loaded, and subsequent details address exactly the failure modes an agent would encounter when calling eval. No filler or redundant restatement of schema fields appears.

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 complexity of arbitrary code execution and no output schema, the description is remarkably complete: it covers what can be returned, how nodes serialize, how to handle fonts and resizing, undo semantics, page switching, and available helpers. An agent has enough information to write correct eval calls and recover from common mistakes.

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?

Although schema coverage is 100%, the description richly extends the code parameter's meaning by documenting the execution model, supported syntax, helper functions, return-value behavior, and common pitfalls. It transforms 'JavaScript to run' into a practical programming contract. The timeoutMs parameter is simple, and 'Default 60000' already suffices.

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

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

The description opens with a precise verb and resource: 'Run JavaScript inside the Figma plugin sandbox, against the file where the bridge plugin is running.' It clearly distinguishes this from sibling tools like figma_metadata and figma_find, which inspect or search rather than execute arbitrary code. No ambiguity exists about what the tool does.

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 explicit alternative guidance for structure and style extraction: 'prefer figma_metadata with styles:true over a hand-written walker' and 'figma_tokens lists the file's variable collections and styles.' It does not exhaustively enumerate when not to use eval against every sibling, but it provides clear context for the most common overlapping case.

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

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

Beyond the idempotentHint/openWorldHint annotations, it discloses concrete output behavior: PNG/JPG attach inline as images (up to 2 MB), SVG/JSON come back inline as text (up to 200 KB). It doesn't mention PDF behavior, but the main return behavior is transparent.

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

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

Three short sentences, front-loaded with the core action, and no filler. The 'local files' phrasing is slightly at odds with the inline-return explanation, but the description is compact and scannable.

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?

It covers PNG/JPG/SVG/JSON outputs and size limits, but with no output schema it leaves PDF behavior and the meaning of 'local files' (where files land when inline=false) unexplained. That's a meaningful gap for a 6-parameter export 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 coverage is 100%, so the schema already explains scale, format, inline, nodeIds, contentsOnly, and useAbsoluteBounds. The description adds size limits and inline-return context, but most parameter meaning is already in the schema, so baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Export nodes to local files.' It also clarifies the main output families (raster images, SVG, JSON) and their intended roles, which sets it apart from sibling tools like figma_status or figma_find. It doesn't explicitly name alternatives, but the purpose is unambiguous.

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

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

It gives clear format-selection guidance: PNG/JPG for the 'screenshot path' and JSON for 'design-to-code tooling,' plus inline-vs-file context. It stops short of explicit when-not-to-use or sibling-tool comparisons, so it earns a 4 rather than a 5.

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

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

Annotations already declare readOnlyHint=true, so the description doesn't need to cover safety. It adds useful context by stating it returns ids, names, and positions, and implies a non-destructive locate-before-edit workflow. It does not disclose any additional behaviors like pagination, rate limits, or matching semantics beyond what the schema already covers, so a 3 is appropriate.

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

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

Two sentences with no filler. The first sentence states the action, scope, and filters; the second states the return value and intended use. Everything earns its place and key information is front-loaded.

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 read-only search tool with a fully documented schema, the description is complete. It covers what the tool searches, the filters, the return values, and when to use it. No output schema exists, but the description supplies the essential return info (ids, names, positions) and the default scope is in the schema. There are no missing prerequisites or side effects to disclose given readOnlyHint=true.

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% and every parameter (name, text, limit, scope, types) is fully documented in the input schema. The description only generically mentions filtering by type, name pattern, and text content, which adds no meaning beyond the schema. 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?

The description starts with a specific verb 'Search' and clearly defines the resource and scope: nodes on the current page or all pages, filterable by type, name pattern, and text content. It also names the return values (ids, names, positions) and frames the tool as the way to locate things before editing, distinguishing it from sibling tools that handle metadata, export, or changes.

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 provides clear usage context: 'the way to locate things in a big file before editing.' It communicates this is a lookup/search tool, not a mutation tool. However, it does not explicitly state when not to use it or name alternative sibling tools, so it stops 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?

Annotations carry only openWorldHint=false, so the description bears the burden of behavioral disclosure. It reveals critical behavior: undo's 60-second window, the one-step-per-call consolidation into the file's undo history, and the fallback that a person can Ctrl+Z afterward. It also clarifies snapshot is a restore point, which is meaningful beyond 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?

The two action-labeled clauses make the structure scannable and avoid repetition. The undo sentence is long and packs several conditions into a semicolon-connected run-on, but every clause earns its place and the content is dense rather than padded.

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-action tool with no output schema, the description covers both operations, their preconditions, the relevant sibling tools, the time window, and the post-window fallback behavior. Nothing essential is missing for an agent to decide when and how to invoke 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 description coverage is 67%, and title/description params are already documented as snapshot-specific. The description adds value by defining the action enum semantics in detail — what undo reverts, the timeout, and the scoped mutating tools — which goes beyond the bare 'snapshot'/'undo' enum values.

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 clearly defines two distinct operations: snapshot (save a named version) and undo (revert the last mutating call). Both use specific verb+resource phrasing, and the action labels make the tool's purpose immediately understandable. The title alone is vague, but the description fully resolves that ambiguity.

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 states when to use snapshot ('before risky edits') and exactly what undo applies to (the last mutating call among figma_eval, figma_place_image, or library import) with a 60-second condition. It does not explicitly name exclusions or alternative tools for inspecting history, so it stops short of a full when-not-to-use guideline.

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 only openWorldHint in annotations, the description carries the burden of behavioral disclosure and does so well: it notes the required 'teamlibrary' permission, indicates that import modifies the file ('bring ... into the file'), and discloses the instance side-effect. It stops short of describing duplicate-import behavior or return values, but the core mutation and permission traits are transparent.

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 permission requirement before enumerating actions. The semicolon-separated action list is dense but scannable; a more structured format would improve readability, but there is no wasted wording.

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 eight parameters, three action modes, and no output schema, the description covers the key workflows but leaves gaps: x/y semantics are absent, return formats for collections/variables are not mentioned, and error or duplicate-import behavior is undisclosed. It is adequate for action selection but not fully self-sufficient.

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 63%, so the description must add action-to-parameter meaning, which it does: collectionKey for variables, key for import, instance behavior for components. However, x and y are not explained anywhere, leaving their purpose unclear, so the compensation is strong but not 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 clearly names the resource (team library) and uses explicit verbs for each action: 'list' for collections/variables and 'bring' for import. It also distinguishes the three sub-actions and references figma_metadata for component keys, though it does not explicitly contrast itself with sibling tools like figma_tokens or figma_find.

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?

Each action is introduced with a clear directive ('collections:', 'variables:', 'import:') that tells an agent when to use that mode. It also provides useful workflow context by pointing to figma_metadata for component keys, but it does not state exclusions or explicitly say when to prefer a sibling tool over this one.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond the schema: it is a 'structural dump,' it is 'cheap' (implying low cost/performance), it has a default depth of 6 and node cap of 400 (though those are in the schema), and it explains what styles:true and css:true expand the output to include. It doesn't mention pagination or truncation behavior, but the maxNodes parameter covers the cap.

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

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

Three sentences, each earning its place. The first sentence defines the core output and the key usage pattern (omit nodeId). The second sentence explains the styles flag with a comprehensive list. The third sentence explains the css flag. No filler, no repetition of schema details that don't need emphasis.

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 read-only inspection tool with 100% schema coverage and no output schema, the description is quite complete. It covers what the tool returns, how to scope it (nodeId), and how to enrich output (styles, css). The only minor gap is that it doesn't explicitly describe the output structure or warn about the maxNodes cap truncation, but the schema covers maxNodes and the description's 'structural dump' phrasing implies a JSON tree.

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 baseline is 3. The description adds meaning beyond the schema by explaining the purpose of the styles flag ('fills, strokes, effects, opacity, corner radius, auto-layout and text styles per node — plus bound variables, named styles, and for instances the main component and its property values') and the css flag ('the design-to-code handoff'). It also clarifies nodeId semantics ('Omit for the current page'), which the schema already states but the description reinforces in context.

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

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

The description opens with a precise verb and resource: 'Structural dump of a node subtree' and enumerates exactly what is returned (id, name, type, x/y/w/h, text characters). It also distinguishes itself from editing tools by calling itself a 'cheap way to find node IDs before editing,' which separates it from siblings like figma_find and figma_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 explicitly states when to use it: 'Cheap way to find node IDs before editing.' It also gives concrete usage guidance for optional flags: 'Pass styles:true to also get...' and 'css:true adds the CSS Figma computes per node.' This tells an agent exactly how to invoke it for different needs and implies it is the read-only exploration tool among siblings.

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

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

The description discloses important behaviors: automatic downscaling over 4096px, conversion of non-native formats to PNG, and that the result reports what was done. The annotation openWorldHint=false is minimal, so the description carries the burden and does it well.

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 concise and front-loaded with the core action, followed by important behavioral details. Every sentence adds value, and it's appropriately sized for the tool's complexity.

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

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

The description covers the key behaviors and result reporting. It doesn't explicitly mention error cases or prerequisites (e.g., node must exist, file must be accessible), but the schema and annotations provide enough for an agent to call it correctly. The output schema is absent, but the description mentions the result reports what was done.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds context about the default maxSide (4096) and the default scaleMode (FILL), which aligns with the schema. It doesn't add much beyond the schema, but the baseline 3 is appropriate.

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

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

The description clearly states the tool's function: placing a local image file into a node as an image fill. It specifies the resource (node) and the action (place image), and distinguishes it from sibling tools like figma_export or figma_metadata by focusing on image placement.

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 provides clear context on when to use this tool (placing local images) and mentions automatic downscaling and format conversion. It doesn't explicitly name alternatives or exclusions, but the sibling list and the specific action make the use case clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavioral scope beyond annotations by naming the reported state: connection status, active file/page, selection, and code execution availability. It does not contradict the annotations.

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

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

A single, front-loaded sentence with a colon that sets the scope. Every element—connection, file/page, selection, code-execution availability—earns its place with no redundancy or filler.

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

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

For a zero-parameter, read-only status tool with no output schema, the description is largely complete: it names the key state dimensions an agent would need to decide about calling the tool. It could go slightly further by noting what happens when the bridge is disconnected, but this is a minor gap.

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

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

The input schema is empty with 100% coverage, so there are no parameters to explain. The description correctly focuses on the tool's informational output rather than param semantics, which earns the baseline for zero-parameter tools.

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 clearly identifies a status-reporting tool: 'Bridge + plugin health' and enumerates the exact state it returns (connection, open file/page, current selection, dynamic code availability). It is distinct from siblings like figma_eval and figma_metadata, though it does not explicitly name or contrast them.

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 a health-check use case: an agent would call this to verify plugin connectivity and dynamic code execution availability before taking actions such as figma_eval. However, it never explicitly states when to prefer this tool over alternatives or provides 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?

With readOnlyHint=true already covering side-effect safety, the description adds meaningful context about output shape: colors as hex, aliases as {name}, and inclusion of paint/text/effect styles. It does not mention limits or error behavior, but those are less important for an annotated read-only tool. No contradiction with annotations.

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

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

Two dense sentences carry both return content and usage ordering with no filler. The first sentence front-loads what the tool returns, and the second tells the agent when to use it and what to call next.

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 three optional, fully documented parameters and no output schema, the description adequately explains scope and return shape. It could additionally note the default variable cap or behavior when no collection matches, but those are minor gaps and the schema partially covers the cap.

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 collection, maxVariables, and includeStyles are already documented in the schema. The description only implicitly touches includeStyles by mentioning local styles and adds no filter, cap, or default semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description specifies a concrete resource: local variable collections with modes and per-mode values, plus paint/text/effect styles. It also names figma_metadata as a complementary tool, which helps distinguish this from siblings. It lacks a direct operative verb like 'return' or 'list', but the colon-definition and usage directive make the purpose clear.

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

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

It gives an explicit when-to-use: 'Read this before generating code or building on a design system.' It also points to figma_metadata with styles:true as the next step for node bindings. It does not state exclusions or when not to use this tool, so it falls just short of full guidance.

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