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

Beyond the readOnlyHint annotation, the description discloses truncation behavior ('truncated to maxBytes with a flag when longer'), output encodings (base64/hex), and the non-decoding limitation. These are meaningful behavioral traits that an agent needs to interpret results correctly.

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 with zero fluff. The first sentence states the core operation, the second gives context about blob table contents and how indexes are referenced, and the third flags the format and truncation caveat. 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?

With no output schema, the description compensates by stating what the caller receives ('the bytes, base64 or hex, truncated to maxBytes with a flag when longer'). It covers parameter semantics and the key caveat (no decoding). Minor gaps exist around the exact response flag name and error cases for invalid indexes, but the description is adequate for a focused retrieval 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?

Even though schema coverage is 100%, the description adds real semantic value: it explains that `index` comes from fig_node's `vector.*` fields and what `maxBytes` does (truncation with a flag), grounding the parameters in actual usage. This goes beyond merely restating 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 opens with a precise verb and resource: 'Return the raw bytes of one entry in the file's blob table.' It further clarifies the payload types (vector geometry, glyph outlines) and explicitly states what the tool does not do ('does not decode the vector-network format'), making its unique role obvious and separating it from structural tools like fig_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 description clearly conveys when to use the tool: whenever raw blob bytes are needed, with references to how indexes are obtained via fig_node fields. It also provides an explicit exclusion (no vector-network decoding), though it does not name a specific alternative tool for decoded output, leaving that 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=true, so the description does not need to restate safety. It adds useful behavioral details beyond the schema: sorting by instance count (most-used first), the variant nuance (component-set when variant), and the filtering behavior. It does not contradict 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?

Three sentences, each adding value: the first lists outputs, the second explains filtering and sorting, the third suggests a follow-up. It is front-loaded with the core purpose and avoids fluff. Slightly long but well-structured.

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 tool's moderate complexity (4 params, no output schema) and the read-only annotations, the description covers the essential behavior: what it returns, sorting, filtering, and a follow-up path. It does not describe pagination explicitly, but the cursor parameter in the schema covers that. No critical gaps for an agent to call it correctly.

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

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

Schema coverage is 100%, so all four parameters are documented in the schema. The description reiterates the query parameter (case-insensitive substring) and implicitly references sorting but adds no new semantic detail beyond what the schema already provides. 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 lists components (SYMBOL nodes) in a file and enumerates the returned fields (guid, name, description, component-set, properties, instance count). It is specific and distinguishable from fig_instance (which is referenced as a follow-up), though it does not explicitly contrast with other siblings like fig_find or fig_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 description implies when to use it (to get a catalogue of components) and gives a follow-up suggestion ('Follow up with fig_instance on a specific INSTANCE guid'), but it does not explicitly state when not to use it or name alternatives. The guidance is adequate but not exhaustive.

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 annotations limited to readOnlyHint=true and openWorldHint=false, the safety profile is already covered, and the description adds substantial behavioral context: case-insensitive substring matching against names AND text content, per-hit contents (page, ancestor breadcrumb, matched field), and the list mode when query is omitted. Nothing in the description contradicts the read-only annotation — this is purely a query operation.

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

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

Three sentences with zero waste: the core purpose and filters are front-loaded, the return shape plus downstream workflow comes second, and the list-mode tip closes it out. Nothing repeats what the schema already states.

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 search tool with no output schema, the description covers matching semantics, result composition (page, breadcrumb, matched field), the list-all behavior, and the follow-up workflow into fig_node / fig_style. Combined with 100% schema coverage — including the cursor resumption note and the limit default — nearly everything an agent needs is present; only truncation/pagination behavior is left to the cursor parameter instead of the description.

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 file, limit, query, scope, types, and cursor are already documented in the input schema, making 3 the baseline. The description adds only modest value by clarifying that omitting `query` switches to a list-all mode, which ties query and types together semantically, but it provides no per-parameter 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 opens with a specific verb and resource — 'Search a file for nodes by name and by text content' — then pins down the matching semantics (case-insensitive substring) and optional filters (node types, subtree). It also differentiates itself from siblings by framing the tool as the find-and-jump entry point that leads to fig_node / fig_style, which is clearly distinct from fig_tree or fig_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 description gives clear workflow context: hits include a guid so you can 'jump straight to a guid and then call fig_node / fig_style,' telling the agent when this tool is the right entry point. It also documents the list-all mode ('Omit `query` to list every node of the given types'). It stops short of a 5 because it never explicitly names exclusions, such as preferring fig_tree when the full hierarchy is 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 annotations, the description discloses key behavioral traits: small images return viewable content, larger ones return metadata, and `savePath` writes exact bytes to disk. The limitation about .fig containing no rendered frame pictures is valuable and prevents misuse. 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?

Three dense sentences carry all essential information with no filler. The core action and input modes are front-loaded, and the limitation is saved for last. 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?

With no output schema and sparse annotations, the description carries the full burden and covers retrieval modes, output behavior, and limitations. The only minor gap is not defining the size threshold between 'small' and 'large' images, but this does not prevent correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial meaning: hash is a 40-hex id reported by fig_node/fig_style, guid resolves to image fills on the node, and hash can be the literal "thumbnail". It also explains the practical difference between inline results and savePath, which the schema alone does not convey.

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

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

The description states a specific verb (Fetch) and resource (bitmap stored inside the .fig), and clarifies scope with the note that it cannot screenshot a design. It also distinguishes itself from fig_render via the explicit limitation. An agent knows exactly what this 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?

It gives clear mode-selection guidance: use `hash`, `guid`, or `hash:"thumbnail"` depending on what is known, and `savePath` for exact bytes versus inline content. It also warns against using it for screenshot-like rendering. It does not explicitly name sibling alternatives, but the practical usage contexts are well 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 already establish readOnlyHint=true, and the description adds valuable detail about what the tool returns: the referenced symbol, resolved property assignments, and each override with its path, node, and changed fields. 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 sentences, front-loaded with the action and a detailed but efficient list of output components. Every clause earns its place and no filler is present.

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 explain tool with no output schema, the description sufficiently covers return values and scope. It lacks only minor details such as error conditions or nesting behavior, which are not critical for invoking 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 description coverage is 100%, so the schema fully documents both parameters. The description adds no additional meaning about 'file' or 'guid' beyond what the schema already says, so the baseline of 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 has a specific verb and resource ('Explain one component INSTANCE') and details exactly what the output covers: symbols, property assignments, and overrides with paths and fields. It is clear but does not explicitly name a sibling tool to differentiate from, so it falls short of the 5 criterion.

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 a clear use case: 'Use it to see how an instance differs from its component without diffing two subtrees.' This tells when to use the tool, though it does not explicitly mention alternatives or when not to use it.

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 readOnlyHint annotation, the description discloses rich behavioral context: exactly what full mode returns (geometry, fills/strokes/effects, corner radii, auto-layout, text basics, links, child summaries), what raw mode does, the one-node-per-call limit, and the potential for large payloads. This is substantial non-obvious behavior.

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

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

Two sentences with no filler. The action is front-loaded, and the second sentence packs the detail-level semantics into a compact, scannable format. Every clause earns its place.

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

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

With no output schema, the description compensates well by explaining the main return modes and warning about raw size. The main gap is that detail=summary is not described, and includeChildren's effect on full output is only implied. These are minor omissions for a tool with such rich description coverage.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real meaning to the detail parameter by explaining what full and raw return, and reiterates the guid format. However, it does not explain the summary enum value, which remains ambiguous for agents choosing between detail levels.

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 inspects one node by guid, with a concrete example ("2:1339"), and enumerates what the response contains. The focus on a single node distinguishes it from siblings like fig_tree or fig_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?

The description implies this is for looking up a specific node when you have its guid, but it never names alternative tools or says when not to use this one. It gives explicit guidance for choosing between detail variants (raw as escape hatch) but not for choosing among sibling tools.

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 mark readOnlyHint true and openWorldHint false, and the description reinforces them with 'Everything is read-only and offline' and 'local' file handling. It does not contradict annotations and adds the concrete context of summarizing without external calls, though it does not go into failure modes.

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 short sentences front-load the core purpose and summary contents, then the workflow. Every clause earns its place and there is no padding.

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

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

With a single parameter, no output schema, and read-only annotations, the description supplies enough context: what file is opened, what the summary contains, and how to proceed afterward. Nothing important is missing for correct invocation.

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

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

Schema coverage is 100% and the one parameter (file) is already documented as a .fig/.figma path. The description's 'local .fig file' and 'summarise' framing adds mild context but not much 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 names a specific verb ('Open... and summarise'), a concrete resource (local .fig file), and enumerates summary contents, so an agent immediately knows what fig_overview does and how it differs from the more granular sibling tools.

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

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

It explicitly says 'START HERE' and gives a recommended workflow: overview, then fig_tree, then fig_node/fig_style, with fig_find as a jump shortcut. This tells the agent when to use this tool and which siblings to prefer next.

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, etc.), the description discloses key behaviors: best-effort rendering with approximation/unsupported flags, fallback to SVG text when the rasterizer is missing, automatic scale lowering to respect maxSize, refusal of subtrees over maxNodes, and directory creation with savePath. These are not captured by structured 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 dense paragraph is front-loaded with the core purpose, then limitations, then defaults and parameter-specific nuances. Every sentence adds operational value without redundancy, and the structure is easy to scan.

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

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

For a tool with 8 parameters and no output schema, this description covers all parameters' defaults, constraints, fallbacks, and output modality (inline vs saved file). It also explains the report's role (approximated/unsupported) and points to alternative tools for exact values, giving an agent everything needed to invoke it correctly.

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

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

Schema coverage is 100%, but the description adds deep meaning: defaults for scale (2), maxSize (1568), and background (transparent); the condition for savePath (required when PNG > 2097152 bytes or SVG > 50000 chars); and the behavior that a page guid downscales to fit maxSize. This goes well beyond the schema's per-parameter 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 clearly states a specific verb ('Render') and resource ('a node') with explicit node types (frame, component, instance, group, shape, text, or whole page) and output formats (PNG or SVG). It also distinguishes from siblings by noting the offline nature and that this is for visual inspection.

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 says 'Rendering is best-effort: read `approximated` and `unsupported` in the report before trusting fine details; exact values remain available from fig_node / fig_style / fig_text.' This names alternative tools and the exact condition under which to prefer them. It also clarifies when to use savePath (when output exceeds size limits) versus inline return.

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 declare readOnlyHint=true, so the safety profile is covered. The description adds useful behavior: it flattens style, translates to CSS, and names shared styles/variables that resolve within the file. This goes beyond annotations by explaining the resolution behavior and output format, though it does not detail every output field.

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 a single, information-dense sentence that front-loads the purpose and lists key attributes. It is not overly verbose, though it is longer than ideal. Structure is logical and everything 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?

Given the tool's complexity (many style aspects, parent-layout behavior), the description covers a broad range of output features. It explains the translation to CSS and the naming of shared styles. The includeRuns parameter is documented in the schema, so the description need not mention it. Overall, it is complete for an agent to understand the tool's scope.

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 all parameters are documented. The description does not add substantial meaning to file, guid, or includeRuns beyond what the schema already provides; it focuses on output content rather than parameter semantics. Thus, 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 purpose: returning the flattened style of one node, translated to CSS terms. It lists specific style aspects (fills, strokes, effects, corner radii, typography, auto-layout) and even parent layout behavior, making it distinct from siblings like fig_node or fig_text which serve different purposes.

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 usage by stating it produces the style 'shaped for writing code', which suggests when to use it (e.g., when generating CSS). However, it does not explicitly contrast with siblings or state when not to use it. This is a minor gap, but the purpose is clear enough that an agent can infer appropriate usage.

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 mark readOnlyHint=true, and the description does not contradict that. It adds meaningful behavior: document order, per-run style overrides for Figma's UTF-16 code-unit spans, only-overridden fields being emitted, and token-cost warnings for includeRuns and includePath. This goes well beyond the annotation signal.

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, with the core purpose front-loaded and the usage guidance placed at the end. Every phrase earns its place; no filler or repetition of schema boilerplate.

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 describing return content, and it does: document order, guid, layer name, characters, page, and base typography. It also addresses scoping, styled runs, and cost implications, making it complete enough for an agent to select and invoke 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 100%, so the baseline is 3. The description adds real value beyond the schema by explaining what includeRuns actually returns (mixed-format spans per UTF-16 code unit, only overridden fields) and by describing scope's subtree filtering. This justifies a small uplift.

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: 'Extract every string of copy in the file', then lists exactly what is returned (guid, layer name, characters, page, base typography). It also distinguishes itself from generic tree walking and positions it for copy audits and translation passes, clearly differentiating it from sibling tools like fig_tree and fig_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?

Explicitly states when to use this tool: 'Use this for copy audits and translation passes rather than walking the tree.' This gives both a positive use case and a clear exclusion, and the mention of subtree scope tells the agent when scope applies.

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 annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds substantial behavioral detail beyond that: results are flat rather than nested, order is document order, hierarchy is reconstructable via depth/parent, subtrees can be truncated, and outline mode changes both format and density. This is exactly the kind of non-obvious runtime behavior an agent needs.

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?

Every sentence in the description earns its place: the core action is front-loaded, followed by output structure, format trade-offs, and truncation handling. There is no filler or repetition, and despite its density it remains easy to scan.

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

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

For a tool with six parameters and no output schema, the description provides a remarkably complete picture: what the response looks like, how to reconstruct hierarchy, how to detect/continue truncation, and when to switch formats. Parameter details like root default, file path, and types filtering are already fully covered by the input schema, so nothing important is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value: it explains the default depth, the meaning of depth relative to the requested root, the purpose of children counts for deepening exploration, and the behavioral difference between json and outline formats. It also clarifies that cursor resumes a truncated traversal.

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: 'List the layers under a node', and immediately defines the tool's distinguishing behavior with breadth/depth limits. It also clarifies the output shape (flat list, document order) and the outline alternative, making it easy to tell apart from broader siblings like fig_overview or fig_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?

The description clearly states when to use the outline format ('4x denser for browsing') and how to continue truncated results via nextCursor. It does not explicitly contrast this tool with sibling tools such as fig_find or fig_node, but it gives enough contextual cues that an agent can infer the intended use 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 readOnlyHint annotation, the description discloses important behavior: aliases are resolved only when the target is in the same file, external variables become opaque assetRefs, and values are formatted per type (hex, verbatim strings/numbers). This gives an agent meaningful expectations about output and cross-file 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?

The description is compact and front-loaded with the core purpose, then expands into output semantics and filters. Every sentence carries necessary information; there is no filler or repetition of schema details.

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 retrieval tool with rich annotations and fully described parameters, the description covers the essential semantics: what is listed, how values are represented, how aliases are handled, and how to filter. The lack of an output schema is compensated by the detailed return-value explanation in the description.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that 'set' accepts a collection name or guid and that 'query' is a case-insensitive substring match, which clarifies the two primary filtering parameters beyond the schema 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 states a specific verb and resource: 'List the design tokens in the file' and precisely enumerates what is returned (variable collections, modes, per-mode values, aliases, assetRefs). This clearly distinguishes it from sibling tools like fig_style or fig_components by focusing on variables and tokens.

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 clear context on what the tool returns and how to narrow results via 'set' and 'query'. It does not explicitly name sibling tools or say when not to use it, but the purpose and filtering instructions make the intended usage unmistakable.

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