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

Annotations only declare readOnlyHint/openWorldHint; the description goes well beyond them, disclosing that results are a single-snapshot edit view that shows nothing deleted and never reveals what an edit was, only when. It also explains rolling-up semantics, undated-node handling, shared limit behavior across pages, and count-scoping rules for page/exclude_pages.

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

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

Purpose is front-loaded, but the definition is one dense block of unusually long clauses mixing result-field semantics, counting rules, and repeated pointers to 'the server's instructions (figma-reader help)' that appear three times. Almost every sentence carries information, yet the packing makes key constraints hard to extract.

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

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

With no output schema, the description carries the output burden and largely does so, naming lastEditedAt, editedNodes, created, page, path, pathIds, undatedNodes, byPage, and excludedPages. Residual gaps remain around exact shapes of byPage/pathIds entries, but an agent has enough to call it and interpret results.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning: the returned 'since' is the instant the value was read as, exclude_pages defaults to the project's excludePages and is echoed as excludedPages, and the limit is shared across pages so one page cannot crowd out others. It also clarifies page/path/pathIds interplay beyond the schema's text.

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

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

Opens with a specific verb+resource+scope: 'Top-level layers created or edited since a date or duration, from Figma's edit times per node.' It then defines what a top-level layer is and explicitly distinguishes itself from the sibling figma_diff ('figma_diff lists removals'). An agent can tell this apart from figma_search or figma_get_tree without opening a 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?

States its operating context clearly (edit metadata from one snapshot, since a date/duration) and routes deletions to figma_diff. It does not, however, state when to prefer it over options like figma_search or figma_diff for non-removal history, so the when-not side is only partially covered.

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 only declare readOnlyHint and openWorldHint, so the description carries real weight and delivers it: ordering (newest change first), exclusions (internal pages, soft-deleted nodes, superseded library copies), default inclusion semantics, neverMarked accounting, and how dating works (exportedAt/account, or fileModifiedAt for a disk read). It adds substantive behavior beyond the safety hints, though the 'see the server's instructions' deferrals are gaps.

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 purpose is front-loaded, and the text is information-dense with little filler, but it is a single 130-word paragraph of nested clauses and parentheticals with no structural separation of usage, output fields or constraints, making it hard to scan. Size is large for a 5-parameter tool but mostly load-bearing rather than redundant.

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

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

With no output schema, the description takes on return-shape disclosure and enumerates the entry fields (id, type, name, page, path, pathIds, status, raw, previous, previousRaw, changedAt, by, note, neverMarked) plus the exception cases. It is largely complete, but key mechanics such as pagination/limit behavior and refresh/caching semantics are outsourced to external docs rather than explained.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates status semantics that the schema's own status description already covers ('none' marks that came off, 'any' is every record, default listing rule), adding only marginal clarification of how 'none' interacts with a prior 'previous' value; it does not document limit, page-exclusion or refresh beyond what the schema says.

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

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

The opening clause names a specific resource and scope: nodes marked Ready for dev or Completed plus those unmarked since, ordered newest change first, and it points at each node's own status record (contrasting with figma_get_node's devStatus view). The verb is implicit rather than stated (it never says 'list'), and the dense clause structure blurs the statement, but an agent can still identify the resource and its filter behavior.

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?

Scope rules are given (internal-only pages, soft-deleted nodes and superseded library copies are left out; default listing covers nodes marked now or before), and figma_get_node is referenced as the per-node alternative. However there is no explicit when-to-use-this-instead-of guidance versus figma_changes, figma_diff or figma_get_node, and operational details are deferred to 'figma-reader help' rather than stated.

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

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

Goes far beyond the readOnlyHint/openWorldHint annotations: it discloses exactly which attributes are compared (ids, names, parents) and which are ignored, how moves surface in from.page/to.page, that a node created and deleted between snapshots is in neither, how 'previous' is cached, and that refresh is ignored for .fig paths. This is unusually thorough behavioral disclosure for a read-only tool.

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

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

Front-loaded with the core purpose, but then collapses into a very long, heavily parenthesized wall of text with no paragraph or list structure, making it hard to scan. Most clauses carry genuine information, but the run-on structure hurts usability.

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

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

With no output schema, the description compensates by describing the return shape thoroughly: byPage fields (added, removed, renamed, movedIn/movedOut, removedNodes), counts and truncated, removedNodes with page/path/removedCount, and pathIds. An agent has enough to interpret results and call the tool correctly.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning beyond the schema: limit is shared across the covered pages so one page cannot crowd out others, exclude_pages applies before the limit, and refresh only affects new. These clarify interactions the parameter descriptions alone don't fully convey.

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

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

States a specific verb and resource ('Compare two snapshots of one file by node id') and immediately scopes it precisely: pages added/removed/renamed, top-level layers changed, and removedNodes subtrees. It explicitly says property edits (text, fills, sizes) are reported nowhere, so an agent can distinguish this diff tool from siblings like figma_changes and figma_locate.

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 rich conditional guidance: when to pass page vs exclude_pages, what default exclude_pages applies, and when old='previous' is meaningful. It points to figma_locate for resolving any id, but never explicitly contrasts this tool with figma_changes, leaving that alternative comparison to inference.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true, and the description goes further by disclosing write behavior (files land in out_dir), partial-failure handling (missing bytes reported as {hash, missing: true} with nothing written), and the per-image result shape including usedByTotal and the five-layer cap. It omits overwrite behavior and auth/rate-limit context, so it is strong but not exhaustive.

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

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

Two tightly packed sentences: the action is front-loaded, then the return contract. Every clause (hash, path, size, layer sample, usedByTotal, missing marker) carries information an agent needs absent an output schema.

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

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

With no output schema, the description fully carries the return-value burden and does so well, and it covers the write/partial-failure semantics. It stops short on overwrite behavior for existing files and any permission or refresh-cost considerations for a tool that re-exports the live file.

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 75%, so most parameters are already documented in the schema. The description only adds the node-vs-whole-file distinction for node_id; it does not clarify the effect of refresh or how out_dir interacts with repeated exports. Baseline adequacy, no extra value.

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: writing the original image assets used by a node or whole file in fill/stroke paints to a directory. This clearly separates it from rendering-oriented siblings like figma_screenshot and content readers like figma_get_text or figma_get_node.

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

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

The scope ('a node or the whole file', 'fill or a stroke paint') implies when the tool is applicable, but there is no explicit when-to-use vs. when-not, no naming of alternatives such as figma_screenshot, and no prerequisite guidance. Usage is inferable rather than stated.

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

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

With readOnlyHint=true already covering the safety profile, the description adds genuinely non-obvious behavior: exactly what a 'count' means (direct placements plus swapInstances), how internal-only pages are excluded from the lists but not from the counts, and the exception for library components on those pages. It also discloses how results are dated (exportedAt/account, or fileModifiedAt for disk reads).

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 front-loaded with the resource definition, but the middle is dense and hard to parse, packing count semantics, page exclusions and a nested exception into single sprawling sentences. The final dating sentence is convoluted and defers to external docs rather than stating the rule, costing clarity for a paragraph that should be tighter.

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

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

With no output schema, the description carries the burden of explaining the return shape, and it does so thoroughly for all three lists plus count semantics and exclusions. What is missing is any usage/routing context against the many sibling read tools, and the dating sentence is incompletely specified in-place.

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 file, query and refresh are already fully documented in the schema (including query's case-insensitive set/variant matching rule). The description adds nothing parameter-specific, so 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 first sentence states a specific resource and scope: the components a file defines plus the library components it uses. It then breaks that resource into three named lists (componentSets, components, libraryComponentsUsed), which unambiguously separates it from siblings like figma_get_styles, figma_get_variables and figma_get_tree.

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

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

There is no when-to-use guidance, no mention of when to prefer this over figma_get_tree/figma_get_node, and no statement of prerequisites or the effect of the refresh/query parameters on workflow choice. The only routing hints are indirect references to 'the server's instructions', which push guidance out of the description entirely.

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 and openWorldHint=true already covering the safety profile, the description still adds substantive behavior: instances are not expanded ('see mainComponentId'), devStatus is absent on unmarked nodes, and path/pathIds handling when the path does not split on ' / '. That is genuine context beyond the annotations, though the devStatus paragraph is so convoluted that its practical value is partly lost.

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

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

The content is substantive but the structure is weak: it opens with return data instead of the action, uses tangled clauses ('a record that is none and was none, with no user or note on it...'), and repeats the pointer '(see the server's instructions, or figma-reader help)' three times across description and schema. Dense but not tightly 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?

There is no output schema, so the description must carry return-shape information — and it does, enumerating geometry, fills, text runs, component info, bound variables, dev-mode annotations, measurements, and dating fields. For a 4-parameter reader it is nearly complete, missing only the node_id semantics and any pagination/size caveats.

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 75% (file, depth, refresh documented; node_id is not). The description adds no syntax or format detail for any parameter — it discusses output fields (mainComponentId, pathIds, exportedAt) rather than inputs. Baseline 3 is appropriate given the schema carries most parameter meaning.

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 the resource and its payload explicitly: 'Detailed design data for a node and its subtree: geometry, fills/strokes/effects (hex), auto-layout, text styling and runs, component/instance info, bound variables and style names.' That is far more specific than a bare 'get node' and lets an agent know it returns deep per-node data. It never names a sibling to distinguish itself (e.g. figma_get_tree, figma_get_text), so it falls short of a 5.

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

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

Usage is largely implied by the payload list rather than stated. There is one routing hint — devStatus details are covered by figma_dev_status — but no explicit when-to-use/when-not or comparison against the many sibling readers (figma_get_tree, figma_get_text, figma_get_components). An agent must infer the choice from the return-data 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?

Adds real behavioral context beyond the annotations: json is the default format, css is an alternative, and a file with no styles (or none of the requested type) returns an empty result in the chosen format. It does not explain that out_file writes to disk, which is what justifies readOnlyHint=false, but the added format/empty-result semantics are substantive.

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

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

Three tight sentences, front-loaded with the resource and its scope, followed by formats and then the empty-result edge case. Only the final empty-result sentence is slightly convoluted, 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?

For a 6-parameter read tool with no output schema, the description covers style types, output formats and the empty case, but leaves refresh, out_file side effects and css_prefix unexplained and does not describe the shape of the returned values beyond 'with their values'.

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%. The description restates the type enum values and adds the json default for format, but says nothing about file, refresh, out_file, or css_prefix. With the schema already documenting most parameters, this is a baseline 3.

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

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

States a specific verb+resource: retrieve styles with their values, and enumerates the style kinds (FILL, STROKE, TEXT, EFFECT, GRID). This is distinguishable from siblings like figma_get_variables or figma_get_components by resource type, though it never names them explicitly.

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

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

The description clarifies scope ('local and imported library styles') but gives no when-to-use guidance or alternatives. It never tells the agent when to reach for figma_get_styles versus figma_get_variables or figma_get_components.

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?

Far exceeds the readOnlyHint/openWorldHint annotations: it discloses hidden-layer exclusion, component-instance expansion with via/component/variant tagging, truncation and unresolvedInstances semantics (including unresolvedComponentsOmitted), and how limit is shared across pages. This is unusually rich behavioral disclosure with no contradiction of 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?

Purpose is front-loaded, but the rest is a dense run-on wall of clauses with parenthetical asides and two deferrals to 'the server's instructions / figma-reader help'. Every fact is relevant, yet it is not scannable and would benefit from sentence breaks or bullets.

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

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

With no output schema, the description carries the return-shape burden and does so: total/truncated/unresolvedInstances, byPage returned/total, and per-item tagged fields are all described. Auth/refresh prerequisites are only gestured at via 'the server's instructions', which keeps it from a 5.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: exclude_pages is explicitly 'never the project's excludePages', limit is shared between pages so 'one cannot crowd out the rest', and the fields keys map to the per-item output. It stops short of explaining refresh/date semantics fully, deferring to 'the server's instructions'.

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 opening clause states a specific verb+resource+scope: 'All text content under a node (or the whole file) in reading order, with node ids.' That is enough to separate it from figma_get_tree or figma_get_node, though it never names a sibling as the alternative, so it falls short of a 5.

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

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

It spells out how the scoping parameters behave (page vs node_id vs whole file, exclude_pages handling) but never says when to reach for this tool rather than figma_search, figma_locate or figma_get_node for the same question. Usage is implied by the scoping rules rather than stated as guidance.

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

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

Annotations only declare readOnlyHint/openWorldHint, yet the description discloses a great deal more: the header line format and its dating source, the exact truncation markers ('- ... N more children', '(N children)'), the level-dropping message with a worked example, and the vector-collapsing rule. This is unusually rich output-shape disclosure for a read-only tool.

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

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

It is front-loaded and information-dense, but the truncation and dating sentences are tangled run-ons, and it defers to external material ('as the server's instructions say (figma-reader help on the command line)') for a core concept. Every sentence carries content, but the packaging could be tighter.

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

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

With no output schema, the description carries the full burden of explaining the return shape, and it does so thoroughly — header line, per-layer outline format, three distinct truncation signals, and vector grouping. An agent knows what it will receive and how to interpret a cut-off result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics on top: max_nodes is spent a level at a time so 'a large first section cannot crowd out later pages,' and depth is counted with pages at level 0. That clarifies allocation behavior the schema only partially captures.

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 opening clause names a specific verb and resource ('Compact outline of the layer tree') and enumerates the fields it emits (id, type, name, size, hints). An agent can tell it produces a summary view rather than a full node dump, but no sibling (e.g., figma_get_node, figma_locate) is named to sharpen 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?

It gives conditional parameter guidance ('Omit node_id for all pages') and hints at escalation ('pass its node_id to open it'), implying figma_get_node for detail. However it never states plainly when to reach for this tool versus figma_get_node, figma_locate, or figma_search, leaving the routing to inference.

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

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

Annotations are sparse (readOnlyHint=false, openWorldHint=true), so the description must carry behavior, and it does: it discloses empty-file behavior per format, that aliases are resolved, and that the output is format-dependent. It does not address the tension of a read-style tool carrying readOnlyHint=false nor any caching/permission constraints, which is the remaining gap.

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

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

Three dense sentences, front-loaded with the resource and its scope before moving to formats and sibling routing. Every clause carries information; the only cost is slight packing of multiple facts per sentence.

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

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

There is no output schema, and the description compensates by naming the three output formats and their conventions plus the written-note behavior on out_file. For a 7-parameter read tool this is close to complete, with only auth/rate-limit and error-shape detail unaddressed.

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 71%, but the description adds genuine meaning the schema lacks: it explains each 'format' enum value (json default, css custom properties with extra modes emitted as [data-collection=mode], dtcg = W3C design tokens) and reinforces the empty-result case. That materially improves an agent's ability to pick and use 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 the exact resource and its shape ('design variables (tokens) with collections, modes, per-mode values and resolved aliases'), which tells an agent precisely what it will receive. It explicitly names the two neighbors it is not—figma_token_usage (derives tokens from raw values) and figma_get_styles (reads styles)—so it is distinguishable without opening any schema.

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

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

Gives a real precondition ('Works on any plan (no Enterprise REST API)') and routes away from siblings by stating what each alternative does. It falls short of an explicit 'use this when you want X, use that when you want Y' rule, but the context is clear enough for selection.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds valuable context about the source-specific behavior (local .fig files vs. recently viewed web files) and the totalUnfiltered field with query. This goes beyond the annotations and enriches the agent's understanding of what the tool does.

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 sentences with no wasted words. It front-loads the core purpose and then efficiently explains the key nuances of source and query. Every sentence earns its place.

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

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

There is no output schema, so the description should explain what the tool returns. It mentions searchedDirs and totalUnfiltered but does not describe the overall structure of the returned list (e.g., file names, paths, pagination). This leaves some ambiguity about the exact output format, making it only partially complete for a listing 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 67%, and the description adds meaning to the source parameter by explaining the local/web distinction and to the query parameter by mentioning totalUnfiltered. It does not add meaning to limit, but limit is already described in the schema. Overall, it compensates well for the 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 action and resource: 'List Figma files.' It further distinguishes between local and web sources, making the tool's scope clear and distinct from siblings like figma_load_file or figma_search. The verb 'list' is precise and the resource is unambiguous.

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

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

The description provides clear context on how to use the tool (source selection, query behavior) but does not explicitly mention when to choose this tool over alternatives like figma_search or figma_get_tree. Usage is implied by the purpose, but no exclusions or alternatives are named.

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 only cover readOnlyHint and openWorldHint, yet the description adds real behavioral context: caching and reuse by other tools, a stated latency risk ('can take a minute' for large files), and snapshot replacement semantics. This goes well beyond the annotations, though the later sentences are garbled and hard to act on.

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 opening sentence is strong and front-loaded, but the following run-on sentences drift into confusing digressions about snapshotPath, exportedAt, fileModifiedAt and account dating. It is over-long and the trailing clause adds ambiguity rather than information.

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

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

For a tool whose snapshot/caching semantics are genuinely complex, the description does attempt to cover export vs cache-read and dating, but it repeatedly outsources the authoritative rules to external docs and ends on an unclear note. With no output schema, it should be self-sufficient, and it is only partly so.

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 baseline is 3. The description elaborates on caching/replacement behavior but also introduces 'snapshotPath', which is not a parameter in the schema, creating mild confusion, and it never names the actual 'refresh' parameter or explains its default.

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 first sentence gives a specific verb+resource ('Export and decode a Figma file') and even enumerates the returned summary (pages, node counts, variable collections, styles, components), which is more specific than most siblings. It implies its role as the file-level entry point that other tools draw from, but never explicitly contrasts itself with figma_get_tree or figma_get_node.

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

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

'Snapshots are cached; other tools reuse them' hints that this is the load-first step and the refresh parameter controls re-export, so usage is implied. However, there is no explicit when-to-use / when-not / alternative guidance, and the reader is repeatedly deferred to 'the server's instructions' or 'figma-reader help' rather than given the rule inline.

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 establish readOnlyHint and openWorldHint, but the description adds substantial behavioral detail beyond them: the per-entry result shapes ({id, found: true, ...} vs {id, found: false} vs {id, error}), the fact that missing and invalid entries are counted rather than thrown, and the crucial failure mode that an unreadable file fails the whole call. This is genuinely useful context the annotations do not convey.

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 purpose is front-loaded, but the body is dense, run-on and awkwardly phrased ('found, missing and invalid count the entries', 'is said only of a file that was read'), forcing re-reads to extract the semantics. The information is valuable but not economically expressed.

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

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

With no output schema, the description carries the burden of explaining return values and does so in detail, including found/missing/invalid shapes, pathIds fallback behavior, and timestamp provenance. Remaining gaps are minor, mostly around the refresh parameter's caching implications.

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 file, refresh and node_ids; baseline is 3. The description adds only the id spelling variants ('12:34 or 12-34') and timestamp semantics, which is marginal beyond what the schema provides for the two primary 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?

The opening sentence states a specific verb+resource ('Look up a list of node ids in one call') and the batch nature separates it from the single-node figma_get_node, which it references by name. It is clear what the tool does, though the sibling differentiation is incidental rather than an explicit routing statement.

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?

'such as the ids a document or an earlier answer cites' gives a concrete usage context, so the agent can infer when this applies. However, there is no explicit guidance on when to prefer this over figma_get_node or figma_search, and no stated prerequisites beyond the passing reference to the server's instructions.

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 goes well beyond the annotations (readOnlyHint=false, openWorldHint=true) by disclosing that it opens a non-remote-controlled browser, that the window self-closes, that headless work resumes afterward, and that wait_seconds blocks until login completes.

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 sentences with no filler. Purpose, trigger condition, user interaction, and headless continuation are front-loaded in a compact, readable form.

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-optional-parameter tool with no output schema, the description covers the essential behavior, UI side effect, and blocking semantics. The only noticeable gap is timeout/failure behavior, which is minor given the tool's simplicity.

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 description must carry the parameter meaning. It states that wait_seconds blocks until login completes, which adds semantic value beyond the schema's min/max, but it does not explain the default behavior when omitted or what happens if the timeout is reached.

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 operation and resource ('ensure ... logged into figma.com') and explains the trigger condition ('if not') and action. It is clearly distinct from all sibling tools, none of which handle authentication or login.

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 communicates the use case (before headless work that requires an authenticated account) and behavior ('if not, opens a normal browser window'). It does not name alternatives, but no sibling tool provides this function, so no exclusions are needed.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true), the description discloses that rendering happens via the browser's Copy-as-PNG, that the system clipboard is untouched, that the live file is used, and that the return includes a note naming the Figma account. It doesn't cover auth requirements or failure modes, but the added context is substantial.

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

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

Three tight sentences, front-loaded with the core action and mechanism; the parenthetical about the clipboard preempts an obvious false assumption, and every clause carries information.

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

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

With no output schema, the description usefully describes the return (image downscaled to max_dimension plus an account-identifying note). Combined with annotations covering the safety profile, it is nearly complete, though auth/login expectations go unmentioned.

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 75%, so the schema already documents most parameters. The description adds the downscaling semantics for max_dimension and the shape of the returned note, but says nothing about save_path or node_id beyond what the schema states. 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?

States a specific verb+resource (render a node to PNG) and immediately scopes it: browser-based 'Copy as PNG' on the live file, not the snapshot. This distinguishes it from snapshot-based siblings like figma_load_file and from figma_export_image_fills without opening any schema.

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

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

The phrase 'Uses the live file, not the snapshot' tells the agent when this tool is the right choice versus snapshot-reading siblings, and the clipboard note clarifies the mechanism. It stops short of explicitly naming an alternative tool or an exclusion, so it falls short of a 5.

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

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

Annotations already settle the safety profile (readOnlyHint=true, openWorldHint=true), and the description goes well beyond them: truncation at 120 characters with charactersTruncated, unresolvedInstances for text that could not be resolved, via/component/variant/frame tagging, and the ordering rule that excluded pages are skipped before the limit is counted. It stops short of stating auth requirements, rate limits, or per-call cost, so it is strong but not exhaustive.

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

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

The purpose is front-loaded, but the body is one undivided block of run-on sentences covering matching, instance expansion, truncation, exclusion, and timestamps. Every clause is arguably informative, yet nested asides such as '(truncated, next to it, is about the number of results)' make it hard to scan; splitting into matching/behaviour/return sections would preserve the content at lower reading cost.

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 12 parameters, no output schema, and a subtle matching model, this description supplies exactly the missing context: what the returned fields mean (via, characters, charactersTruncated, unresolvedInstances, excludedPages) and where output is elided. An agent has enough to call the tool and interpret the result without further documentation.

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, but the description earns an increment by giving concrete, illustrative query forms ('Icons/Arrow/Left or /Card [v2]/ matches itself') and by clarifying cross-parameter interactions such as an invalid regex being an error and regex quoting behavior. Much of the remaining parameter detail duplicates the schema, which caps it below 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?

The opening clause gives a specific verb and resource ('Find nodes by name (and optionally text content)') and immediately scopes the matching semantics. It also distinguishes itself from the sibling figma_get_text by stating that search returns a truncated preview while 'figma_get_text returns the strings whole', so an agent can route between the two without opening a 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?

Usage context is clearly established: when to set include_text, when the text pass does not run, and the important workaround that 'layer names inside a collapsed instance live in its main component, so search that component instead'. What is missing is an explicit statement of when NOT to use this tool versus figma_locate, figma_get_tree, or figma_get_text beyond the single truncation contrast.

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 are sparse (readOnlyHint=false, openWorldHint=true) and do not explain side effects. The description adds a valuable behavioral guarantee: it does not launch anything, which is safety-relevant for an agent deciding whether to call it. This goes beyond the annotations, though it does not disclose return format or network behavior.

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

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

Two short sentences with no redundancy. The core state information is front-loaded, and the clarifying no-launch note is placed immediately after.

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 status tool with no output schema, the description is largely complete: it names what is reported and clarifies a key side-effect constraint. It could briefly mention what the agent will receive in the response, but the low complexity keeps this from being a major gap.

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

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

The tool has zero parameters and the schema is an empty object with 100% coverage, so there is nothing the description needs to add. The 0-parameter baseline of 4 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 identifies the resource as 'account, browser and login state', which clearly signals a status-checking tool. It lacks an explicit verb like 'reports' or 'checks', but the follow-up 'Does not launch anything' differentiates it from file-loading and login siblings.

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

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

There is no explicit when-to-use guidance or mention of alternatives. The note about local .fig paths never needing the browser implies a use context, but the description never says 'use this to verify login state before...' or contrasts it with figma_login or figma_load_file.

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 cover readOnly/openWorld, and the description goes well beyond them: it explains the aggregate shape (counts + bound variable/style), the typography edge case (entries carry only recorded properties; text with none is counted in textWithoutTypography), and the dating rules (exportedAt/account vs fileModifiedAt). These are genuine behavioral details, though it leans heavily on pointing to external 'server instructions' rather than stating rules inline.

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

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

Purpose is front-loaded in the first sentence, but the description is bloated: the typography-exclusion explanation is a long clause, and 'as the server's instructions say (figma-reader help on the command line)' is repeated, deferring to external docs twice.

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

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

With no output schema, the description carries the return-value burden and does so well -- it enumerates the aggregated categories, mentions counts and bindings, and handles the typography edge case. Remaining gaps are minor (include_hidden, exact grouping of output).

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 the schema documents file, refresh, and min_count while node_id and include_hidden are bare. The description only indirectly signals node_id ('scan a subtree') and refresh ('a file read from disk'); include_hidden is never addressed. It adds marginal value, aligning with the 3 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?

States a specific verb and resource -- scan a subtree/whole file and aggregate raw design values (colors, typography, radii, gaps, stroke widths, effects) with counts. It also distinguishes itself from the sibling style/variable tools by noting it is for 'files that do not define variables or styles'.

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 use condition ('to derive a token set from files that do not define variables or styles'), which implicitly excludes files that do have variables/styles. But it never names figma_get_variables or figma_get_styles as the alternatives to reach for in that case, so routing is left to inference.

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