figlens

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

With no annotations, the description carries the full burden. It usefully discloses bundle contents, states behavior, evidence gaps, and that no MCP configuration change is needed, but it omits key mutation traits: whether an existing ZIP is overwritten, required permissions, and failure behavior.

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

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

Two dense, front-loaded sentences with no filler. The bundle contents are listed inline, and the states behavior follows immediately, though the final clause about MCP configuration is slightly disconnected.

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?

An output schema exists and parameter coverage is complete, so the description needn't explain return values. It still leaves mutation safety and overwrite behavior unstated, but for a tool whose schema and output contract are rich, it is largely complete.

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

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

Schema description coverage is 100%, so all six parameters are already documented. The description adds helpful semantics for states=true and the accepted node forms, but the schema already carries most of this information, making 3 the appropriate 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 — 'Write a design bundle zip' — and enumerates bundle contents (nodes, variables, assets, reference render, context.md), so the agent knows exactly what the tool produces. It does not explicitly distinguish this from sibling tools like export, inspect, or variables, which keeps it from 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 gives one clear conditional: pass states=true when the user requests related component states. However, it does not say when to use bundle versus siblings such as export, inspect, or nodes, nor when not to use it. Usage is implied rather than fully guided.

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

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

With no annotations, the description carries the burden well: it states the output-directory prerequisite, that raster formats return an inline image, that SVG can embed originals and become large, and that callers should check returned dimensions/bytes and isError. It does not discuss overwrite behavior or permissions, leaving some side-effect detail unstated.

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 front-loaded with purpose and then moves through prerequisites, format guidance, raster-only caveats, and error checking without filler. Every sentence contributes actionable 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?

Given seven parameters and an existing output schema, the description supplies the missing decision context: format choice, raster-only parameters, directory creation, and failure handling. An agent has enough to call the tool correctly without further prose.

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 adds cross-parameter meaning: 'scale, quality and maxSize affect raster formats only' and ties quality/maxKb to sizing for DPR. That is useful beyond the schema's per-field descriptions.

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 a node to SVG, PNG, JPG, WebP or AVIF.' It makes the tool's action and output formats unmistakable, and the sibling names do not include a competing export tool.

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

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

It gives clear format-selection guidance, including 'PNG suits inline references,' WebP for website bitmaps, and SVG for vector artwork. It does not explicitly compare against sibling tools or state when not to use export, so it stops short of full alternative routing.

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

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

With no annotations, the description carries the burden and does most of it: it declares case-insensitive matching, the scope of the search (stored layers only, no instance expansion), what is returned, and that truncation signals more matches. It does not explicitly state read-only semantics or cost, but the search framing makes the read nature clear.

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 what is searched and what comes back, then the scope limit and the escape hatch. Nothing is 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?

An output schema exists, so the brief return-value listing is a bonus rather than a requirement. For a five-parameter search tool the description covers matching semantics and scope well; only the relationship to the tree and nodes siblings is left for the agent to infer.

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 genuinely new semantics: matching is case-insensitive, a fact the schema's 'literal substring' wording does not convey. It also explains the stored-subtree scope that governs the node parameter, which the schema only hints at.

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

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

The description gives a specific verb and resource: it searches stored layer names and text, case-insensitively, returning ids, paths, sizes and previews. It separates itself from the inspect sibling for instance children, though it leaves the boundary with tree and nodes implicit despite the bare name '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?

It states an explicit exclusion and names the alternative: 'Does not expand instance children; use inspect on the instance', reinforced by the node parameter note. There is no guidance on when to reach for this versus tree or nodes, so it stops short of full routing guidance.

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

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

With no annotations, the description carries the full burden and does so well: it discloses depth bounding, a 200-node budget, a separate 200-item image-paint limit, and that image mode writes no files. It also sets negative expectations — "not blur diagnoses", "infers no business conditions", "renders no other variants" — which is exactly the kind of scope containment an agent needs on an unannotated tool.

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

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

Four sentences, no filler, and the output shape is front-loaded before the caveats and the sibling reference. It is occasionally terse to the point of opacity — "before masks, not blur diagnoses" reads as an inside reference — but nothing is 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?

An output schema exists, so return values need not be spelled out, and the description instead covers budgets, scope containment, and side-effect absence, which is the right allocation for an unannotated six-parameter tool. The remaining gap is that the two variant-related parameters are never addressed in prose.

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

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

Schema coverage is 100%, so the baseline is 3. The prose adds genuine meaning for `images` (source bitmap dimensions/bytes and per-paint crop rectangles, explicitly excluding blur diagnoses) and for `depth` via the 200-node budget, but it says nothing about `compareVariant` or `states`, leaving the schema to carry those alone.

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?

"Compact expanded node summary: bounds, layout, typography, text previews and child counts" names the resource and enumerates its contents, and the closing clause "nodes returns full design data" distinguishes it from the closest sibling. The verb is nominal rather than active, so the operation is inferred rather than stated, but the returned shape is unmistakable.

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?

Selection guidance is implied rather than stated: "nodes returns full design data" hints this is the lightweight alternative, and "For image decisions, images=true adds..." gives conditional guidance for one flag. There is no explicit when-to-use/when-not statement, no prerequisites (e.g., that it needs a saved .fig), and two of six parameters (states, compareVariant) get no usage framing at all.

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

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

No annotations are provided, so the description carries the behavioral burden. It usefully discloses that instances are expanded, that fills/text/auto-layout are included, and that output can be large, but it does not state read-only behavior, permissions, or error characteristics.

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 short and front-loads the resource plus key output details, with no filler. The sentence-fragment style slightly weakens clarity but keeps it efficient.

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 return shape and a useful size warning, and the input schema covers both parameters well. However, it omits sibling selection guidance and does not clarify read-only/safety behavior, leaving meaningful context gaps for an agent choosing between node-related tools.

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

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

Schema description coverage is 100%, so the schema already fully documents the file and node parameters. The description adds no parameter-level detail beyond what the schema provides; 'exact instance sublayer' is already covered by the node parameter description.

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

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

The description identifies the resource and output as 'A node or exact instance sublayer as Figma REST nodes.json' and lists included content, but it uses a noun phrase with no action verb. It also does not distinguish this tool from siblings such as inspect, tree, or 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?

There is no guidance on when to use this tool versus alternatives, and no exclusions or prerequisites are stated. The only usage-adjacent note is 'Can be large,' which is not selection guidance.

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

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

With no annotations, the description carries the behavioral burden. It implies a read-only listing operation and describes the returned fields (ids, types, names), but it does not explicitly state side-effect safety, permissions, or rate limits. The schema covers the output-mode parameter details, so this is adequate rather than rich.

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 wording. The core purpose is front-loaded, and the comparison to 'find' is placed immediately after as useful routing context.

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

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

For a read-only outline tool with a fully described schema, the description is nearly complete: it states what is returned and when to use it versus find. The main missing piece is explicit differentiation from the sibling 'nodes,' but no critical calling information is absent.

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 parameter meanings are already fully documented in the input schema. The description adds only the high-level notion of listing 'under a chosen root' and a 'shallow outline,' which aligns with the root and depth parameters but does not add syntax or usage detail beyond the schema.

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

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

The description states a specific verb and resource: 'List node ids, types and names under a chosen root.' It also distinguishes the tool from the sibling 'find' by explaining that tree is for locating pages/frames when names are unknown, while find searches known names or visible text.

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

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

It gives a clear use case ('when their names are unknown') and explicitly names the alternative tool ('find searches known names or visible text directly'). It does not cover when to prefer or avoid the other siblings such as inspect or nodes, but the main routing decision 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the scope behavior when node is omitted, but it does not explicitly confirm that the operation is read-only, nor does it describe permissions, error conditions, or return shape beyond naming the variable categories.

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 definition is a single compact sentence that front-loads the resource and appends the key scoping rule. It is efficient and avoids repetition, though the sentence fragment form is slightly less immediately scannable than a full verb-led statement.

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

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

With two well-documented parameters and no output schema, the description covers the core scoping behavior needed to call the tool. However, for a query tool with no annotations, it could do more to confirm read-only safety and describe what the returned variable data contains.

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

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

Schema description coverage is 100%, so both parameters are already documented in the input schema. The description reinforces the node-omission behavior with 'every local variable,' but adds no syntax or format details beyond what the schema provides, making the baseline score of 3 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 precisely: variables bound by a frame, including collections, modes, and aliases, and clarifies the default scope when no node is given. It is not phrased as a verb, but an agent can still tell this tool apart from siblings like tree, find, or inspect because it names a distinct data type.

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 'without a node, every local variable' gives a clear condition for the optional node parameter, but the description does not explain when to use this tool instead of siblings such as inspect or nodes. Usage is implied by the resource name rather than explicitly guided.

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, but the description adds non-obvious value by pre-empting the misleading topic names: 'no design file, project read/write, implementation, verification or cleanup is performed' clarifies that 'build' and 'yolo' do not trigger actions. Only the return format (e.g. markdown/text) is left unstated.

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 action ('Read built-in figlens skill guidance'), followed by topic routing, then a scope disclaimer. The topic list is dense but every clause maps to an enum value or a behavioral constraint, so there is little waste.

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

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

For a one-parameter, read-only lookup with no output schema, the description covers intent, per-value selection, side-effect scope, and result nature ('Returns the requested guide only'). Only the concrete return format is unspecified, which 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?

Schema coverage is 100% and the enum already lists the five topics, so baseline is 3. The description adds real semantic meaning to each enum value by describing the situation each guide is intended for, which the schema's one-line 'Guide to read' does not.

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

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

States a specific verb and resource: 'Read built-in figlens skill guidance for this agent', then enumerates the five guides available. The purpose is unmistakable despite the generic tool name 'workflow', and it clearly is not a design-file or export operation like its siblings tree/find/inspect/bundle/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?

Gives per-topic routing ('build for design-to-code and project reuse', 'planning-details for page/multi-page work or unresolved design dependencies', 'yolo for explicitly requested autonomous implementation'), and explicitly says ordinary design questions and exports should use the design tools directly. That covers when to use this tool and when not to.

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