figwright

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

The description goes beyond the minimal annotations by revealing key behaviors: the property is inert until bound, defaultValue must match the type, preferredValues only applies to INSTANCE_SWAP, and the return shape is { ok, componentId, propertyId, name } with instructions to pass propertyId to subsequent operations. These details are not present in annotations and add meaningful behavioral context.

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 dense but efficiently organized: it starts with the core action, then explains the inert/bind workflow, type constraints, an important exclusion, and the return value. Every sentence contributes necessary information without redundancy or filler.

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

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

The description is fully self-contained for a moderately complex tool: it defines property types, explains the attach step, gives default value rules, notes the variant-property exception, and describes the return value. Since no output schema exists, including the return shape and pointing to related tools for subsequent actions makes this exceptionally 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 the input schema already thoroughly documents each parameter. The description reinforces type constraints (e.g., 'defaultValue must match the type') and the INSTANCE_SWAP-only nature of preferredValues, but does not substantially add new parameter-level semantics beyond what the schema already states.

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: 'Declare a component property on a component (or its variant set)'. It clearly distinguishes the action from related tools by contrasting with bind_component_property and explicitly excluding variant properties ('VARIANT properties come from combine_as_variants, not here').

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 concrete usage guidance by explaining that the property 'starts inert' and must be attached via bind_component_property, with type-to-layer mappings. It also gives an explicit exclusion for variant properties and points to the correct tool (combine_as_variants), making when-to-use versus alternatives very clear.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description's 'Create' aligns. The return shape '{ ok, nodeId, name, type }' adds value beyond annotations, but no deeper behavioral context (e.g., where the page is created, side effects) is disclosed.

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?

One concise sentence with an added return-type note. Front-loaded, zero waste, and appropriately sized for a simple tool with one optional parameter.

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 low complexity (1 optional parameter), annotations, and inclusion of return shape, the description is largely complete. However, it could benefit from context like 'in the current document' to clarify scope, though this is inferable from sibling tools and the domain.

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% with the 'name' parameter described as 'Optional page name'. The description adds that the page is 'optionally named', which is essentially redundant with the schema. No additional parameter meaning is provided 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 explicitly states the action ('Create a new page') and the optional naming behavior, clearly distinguishing it from sibling tools like delete_page, rename_page, and navigate_to_page.

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 (when you want to create a page) but provides no explicit when-to-use guidance, exclusions, or alternatives. Context can be inferred from the tool name and sibling list, but it is not 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses the return format, the plan-gating behavior (Starter allows 1 per collection), and the failure guidance. This adds significant behavioral detail that annotations don't capture, though it doesn't mention potential edge cases like duplicate mode names.

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

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

The description is concise yet information-dense: it states what the tool does, what it returns, and how it behaves under plan constraints. No filler words; each sentence earns its place. Well-structured for AI consumption.

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

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

For a two-parameter tool with no output schema, the description covers the action, return value, and a key failure mode. It doesn't explicitly state prerequisites like collection existence or name uniqueness, but the core usage is sufficiently complete. A minor gap, hence 4.

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%, with both parameters (name and collectionId) having descriptions. The tool description adds only a minor example ("Dark") that repeats the name parameter's schema description, but does not add new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's action: 'Add a mode (e.g. "Dark") to a variable collection.' This is a specific verb+resource that distinguishes it from sibling tools like create_variable_collection or set_variable_value, and even includes the return shape for additional clarity.

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 for when to use the tool (when adding a mode to a variable collection) and includes a specific alternative guidance: when the plan blocks a new mode, fall back to a paired collection. While it doesn't explicitly enumerate exclusions, it offers a practical when-not-to and alternative.

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, and the description adds substantial context beyond that: it runs on the server filesystem, rootDir defaults to server cwd, detects Tailwind v3/v4, and reports svg loader mode. This gives the agent a clear behavioral picture of a safe, local read-only probe. It doesn't exhaustively list every behavior, but it's well above baseline for an annotated 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?

The description is dense but not bloated. It front-loads purpose, then usage guidance, then specific detection details. Each sentence adds distinct value (purpose, relationship to siblings, server-side execution, default, detection specifics). It could be tightened slightly, but overall it is well-structured and economical.

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 tool has no output schema, but the description compensates by listing what is detected (framework, language, styling system, component file extensions, svg handling, tailwindVersion, svg.mode). It also clarifies the operational context (server filesystem, no Figma, no file scan). For a simple probe with one optional parameter, this is sufficiently 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 coverage is 100% (one parameter, rootDir, fully described). The description adds meaningful extra semantics: 'rootDir defaults to the server cwd' and notes it is an optional override. This goes beyond the schema by clarifying the default and the scope of the parameter.

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 action and object: 'Detect the local project profile (framework, language, styling system, component file extensions, svg handling) by reading manifests and config'. It clearly distinguishes itself from siblings scan_components / component_map by positioning itself as the foundation and noting it is for 'inspection in isolation (no Figma, no file scan)'.

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?

Explicit usage guidance is provided: 'those tools run detection internally and return the same profile, so call this only to inspect detection in isolation'. It names the alternatives (scan_components / component_map) and states when not to use this tool, which fully addresses the when-to-use vs alternatives requirement.

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

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

The description discloses several behavioral traits beyond the sparse annotations: the operation is atomic and undoable when batched, returns an `appliedStyleId` that can be used to remove exactly that instance later, and is a Figma-Design-only beta feature. No contradiction with `readOnlyHint: false` or `destructiveHint: false`.

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 the core purpose and every sentence earns its place: input source, config tuning, return/removal semantics, batch staggering, and platform limitation. There is no filler or repetition of schema content.

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 nested configuration and no output schema, the description covers input provenance, key config behavior, return shape, removal strategy, and atomic batching. It does not enumerate every config prop, but the schema covers those details, making the description complete enough for practical use.

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 schema already documents all parameters (100% coverage), but the description adds valuable meaning: it tells the caller to obtain `styleId` from `get_motion_styles`, explains `timelineOffset` as the stagger lever with `node index * step`, and summarizes `config` as duration, offset, and preset-specific props.

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 uses a specific verb ('Apply'), a specific resource ('a Figma Motion animation-style preset'), and a target ('a node'). It clearly distinguishes this from the sibling `apply_style_to_node` by emphasizing Motion presets and referencing `get_motion_styles` as the source of style IDs.

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 guidance on sourcing `styleId` from `get_motion_styles` and explicitly instructs when to use `batch` for staggered entrances by increasing `timelineOffset`. It does not explicitly contrast with `apply_style_to_node` or `apply_manual_keyframe_track`, but the Motion-specific context is sufficient.

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 provide readOnlyHint=false and destructiveHint=false. The description adds meaningful behavioral context: it replaces any existing track on the field, returns `{ ok, nodeId }`, and notes the beta and Figma-Design-only restrictions. This exceeds what annotations reveal, though it could more prominently state the replacement side-effect.

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 well-structured sentences: purpose with examples, parameter walkthrough, and behavioral/return/platform note. Every sentence adds value and there is no redundancy.

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 complex tool with nested objects and no output schema, the description covers the return shape, replacement semantics, and platform/beta caveats. It lacks error/edge-case guidance, but the rich schema and sibling context make it reasonably 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%, with every parameter and nested property already described in the schema. The description's summary of `field` and `track` restates schema content without adding new meaning, so the baseline of 3 applies.

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

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

The description opens with a specific verb ('Set'), a clear resource ('hand-authored Figma Motion keyframe track'), and scope ('on a node for one field'), followed by concrete field examples. This makes the tool's purpose unambiguous and distinguishes it from siblings like `remove_manual_keyframe_track` and `apply_animation_style`.

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 scenarios through phrases like 'hand-authored' and 'Replaces any existing track on that field,' but it never explicitly says when to use this tool instead of `apply_animation_style` or when not to use it. The beta/Design-only note is a constraint, not a comparative guideline.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, so the agent knows it's a non-destructive mutation. The description adds information about the field slot and the return value, but does not disclose whether applying a style overrides an existing one or whether the style must already exist.

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

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

Two concise sentences front-load the purpose, then explain the parameter and return value. There is no redundancy or fluff.

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?

While the core behavior is clear, the description omits potential constraints such as required compatibility between the style type and the selected field, or whether existing bindings are replaced. For a simple mutation tool with no output schema, this leaves some gaps for an 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?

The schema description covers 67% of parameters, missing the `field` parameter. The description explicitly explains that `field` selects the applicable slot (fill/stroke/effect/grid/text), providing meaning beyond the enumeration. nodeId and styleId are already described in the schema, so the description adds targeted 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?

The description clearly states the tool's function with a specific verb ('Bind') and resource ('shared style to a node'). It also explains the `field` parameter's role and the return value, distinguishing it from sibling tools like set_fills or set_strokes.

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

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

The description does not provide guidance on when to use this tool versus alternatives such as set_fills, set_strokes, or create_paint_style. There is no explicit mention of prerequisites or when this approach is preferred over direct style application.

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?

While annotations only indicate a non-read, non-destructive operation, the description adds crucial behavior: atomic all-or-nothing with rollback, ordered result shape ({ ok, results } with per-op results), and rejection of destructive ops. This goes well beyond 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?

Two dense sentences, no filler. The main purpose is front-loaded, followed by structure, constraints, and return 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?

For a tool with no output schema and one complex nested param, the description adequately covers the op structure, allowed/disallowed tools, atomicity semantics, and return format. Complete enough for an agent to select and invoke 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?

The schema already documents 'ops' as an array of { tool, params } with high coverage. The description enriches this by clarifying that 'tool' must be an invertible write, giving concrete examples (set_fills, rename_node, move_nodes, create_frame), and specifying destructive names are invalid. This adds meaning 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 'Apply multiple invertible write ops atomically,' providing a specific verb (apply) and resource (invertible write ops). It distinguishes itself from sibling tools by explicitly restricting to invertible writes and rejecting destructive ops, making it a clear batch operation rather than an individual 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 clearly states when to use: when needing atomic application of multiple invertible write ops, with rollback. It also states when not: destructive ops are rejected. However, it doesn't explicitly contrast with calling individual write tools non-atomically, leaving that alternative implicit.

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

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

Beyond the annotations (readOnly=false, destructive=false), the description adds that missing nodes are skipped and that it returns { ok, affected }. This provides useful behavioral context about partial handling and the return shape.

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 long, front-loads the core action, and every sentence adds value: the batch action, the input format, the skipping behavior, and the return value. No extraneous text.

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

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

For a simple batch rename tool, the description covers the essential aspects: input format, behavior for missing nodes, and the return value. It doesn't discuss error handling, but given the tool's simplicity and the annotations, this is adequate.

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

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

Although schema coverage is 100%, the description reinforces the parameter structure by stating 'from a [{ nodeId, name }] list', which adds clarity about the exact expected array elements beyond the schema's generic 'Per-node rename 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 description clearly states 'Rename many nodes at once', specifying the verb and resource, and distinguishes itself from the sibling 'rename_node' by emphasizing the batch aspect. It also describes the input list format and the behavior of skipping missing nodes.

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 for use: 'many nodes at once' signals this is for batch operations. It doesn't explicitly mention alternatives or when not to use it, but the purpose is clear enough to guide selection in most cases.

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, destructiveHint: false), the description reveals key behaviors: the null-to-unbind mechanism, the requirement for the property type to match the field, and the need for the property to exist on the containing component. It also discloses the return shape. This adds meaningful context beyond the annotations, though it could mention whether existing bindings are overwritten.

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 dense paragraph with no filler. It front-loads the core action ('Attach'), then systematically explains type mappings, repeatability, unbinding, constraints, and return value. Every sentence earns its place, making it efficient and 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?

For a tool with 3 parameters, no output schema, and no nested objects, this description is complete. It covers preconditions, field/type mappings, how to unbind, and return value. It also situates itself within the component-property workflow by referencing add_component_property. There are no significant gaps.

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

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

The input schema already covers all three parameters with 100% coverage, so the baseline is 3. The description enhances this by mapping each field enum value to specific property types and node types (e.g., 'characters' requires a TEXT node), which is not in the schema. This adds real semantic value, earning a 4.

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

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

The description clearly states the tool's function: attaching a declared component property to a sublayer field so it drives that layer. It specifies exactly which field maps to which property type (visible for BOOLEAN, characters for TEXT, mainComponent for INSTANCE_SWAP) and distinguishes itself from sibling tools like add_component_property and edit_component_property by focusing on the binding action.

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 explicit usage context: it references add_component_property as the prerequisite, explains valid field/type combinations, notes that the same property can be bound to multiple layers, and gives special handling for null to remove bindings. It does not explicitly name alternative tools or state when not to use it, but the guidance is clear enough for an agent to select the correct tool.

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, the description discloses that variable's resolvedType must match the field's type, explains unbinding via null, and mentions the cornerRadius special behavior (binding all four corners at once). It also returns { ok, nodeId }. It does not detail error behavior or overwrite semantics, but the provided 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?

The description is two sentences, front-loaded with the main action, and every sentence adds value. It efficiently includes examples, alternatives, constraints, and return format with no unnecessary verbiage.

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 (binding fields, type constraints, unbinding), the description is remarkably complete: it covers the action, examples, constraint, alternatives, source of IDs, and return value. No output schema exists, but the description provides the return shape, making it fully usable.

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?

While schema covers parameters at 100%, the description adds meaning by listing valid field examples, highlighting the special cornerRadius case, and clarifying that variableId can be null to unbind. This goes beyond the schema's simple descriptions and helps the agent understand valid values and behavior.

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

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

The description clearly identifies the tool's action (bind/unbind a variable to/from a node field), provides concrete field examples, and explicitly distinguishes itself from the sibling tool bind_variable_to_paint. The verb 'bind' is specific and the resource is well-defined.

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 states when to use this tool (binding a node field) and explicitly directs users to bind_variable_to_paint for fill/stroke colors. It also gives a prerequisite by referencing get_variable_defs for obtaining bindable variable IDs, providing clear guidance on alternatives and prerequisites.

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 indicate a non-read-only, non-destructive mutation. The description adds valuable behavioral details: Figma stores bindings on the paint rather than the node, unbinding via null, and the 0-index default for paint selection. This goes beyond the annotation hints, though it doesn't fully cover error handling or edge cases.

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 exceptionally concise: three sentences, each packed with relevant information. It front-loads the primary action, then provides necessary elaboration without repetition or fluff.

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 4 parameters and no output schema, the description covers the main use case, the alternative tool, and the return shape. It lacks some edge-case details (e.g., behavior when index is out of range or paint is not solid), but it is otherwise complete for typical usage.

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 meaning by explaining the purpose of target/index defaults and clarifying that variableId null means unbind. It also introduces the 'must be SOLID' constraint not present in the schema, which aids correct usage.

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 action: 'Bind a COLOR variable to a SOLID fill or stroke paint', immediately clarifying what the tool does. It explicitly contrasts with bind_variable_to_node, distinguishing this tool's scope (paint bindings) from scalar node bindings, which is a clear sibling differentiation.

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

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

The description explicitly states when to use this tool vs the alternative: 'this is separate from bind_variable_to_node (which covers scalar fields like width / padding / radius)'. It also explains the paint/node distinction and the requirement that the paint must be SOLID, giving clear situational 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 already indicate a mutating (readOnlyHint=false) and non-destructive (destructiveHint=false) operation. The description adds valuable behavioral details: copy placement ('sibling right after the original'), deep copy ('full subtree'), instance preservation, and the return payload. This goes beyond the annotations without contradicting them.

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 well-structured sentences: the first states the core action and placement, the second covers the instance nuance and alternative, and the third (short) gives the return shape. Every clause adds value, with zero redundancy.

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?

Despite having no output schema, the description fully discloses the return format. It explains the scope (subtree), placement, behavior for component instances, and the alternative tool. For a single-parameter mutation tool, this is complete and self-sufficient.

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

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

The input schema already provides 100% coverage for the sole parameter with 'Node id to clone'. The description adds no extra parameter-specific meaning beyond what the schema states, so it meets the baseline for high schema coverage. The behavioral context (placement and subtree) indirectly clarifies the parameter's effect but doesn't add new syntax or format details.

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 uses a specific verb 'Duplicate' and identifies the resource ('a node') with the explicit scope of 'including its full subtree'. It clearly differentiates from sibling tool create_instance by noting that cloning a component instance keeps it an instance, making the purpose 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?

The description explicitly contrasts with create_instance: 'to make a fresh instance of a component use create_instance instead'. It also clarifies when to use this tool (when duplicating a node with its subtree) and the behavior for component instances, providing clear 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?

Annotations already indicate readOnlyHint=false, so the description adds value by disclosing the side effect: 'The components are reparented into the new set under parentId.' It also states the return shape, which helps set expectations. Minor gaps exist (e.g., no mention of permission/undo), but it goes beyond 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?

The description is three sentences with no fluff: the core action, a necessary prerequisite, and side-effect/return info. It is front-loaded and every sentence adds value.

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 action, prerequisite, side-effect, and return value. There's no output schema, so including the return format is beneficial. Minor edge-case behaviors (error conditions for non-COMPONENT nodes) are left to the schema, but overall it's sufficiently complete for a 3-parameter mutation tool.

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

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

Schema coverage is 100%, with each parameter described in the input schema. The description adds little beyond the schema, aside from restating the default parent behavior already present in the schema. Baseline 3 is appropriate given full schema coverage.

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 action: 'Combine two or more existing COMPONENT nodes into a single COMPONENT_SET (a variant set).' It uses a specific verb and resource, and differentiates from sibling tools like group_nodes or reparent_nodes by explicitly targeting variant-set creation.

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 provides clear context and a prerequisite: 'Name each component with Figma variant syntax... beforehand so the set derives its properties.' No alternatives or exclusions are mentioned, but the usage intent is well-understood.

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 far beyond the readOnlyHint annotation, detailing the AST scan, the override mechanism with docs/figma-component-map.md, handling of staleOverrides degrading to fuzzy results, mapping each component once, and reporting matchedProps/unmatchedProps. This extensive disclosure gives the agent a deep understanding of the tool's behavior without contradicting 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?

The description is relatively long but every sentence contributes substantive detail about the tool's logic, edge cases, and outputs. There is minor repetition of the 'reuse' theme, but overall it is structured and information-dense without unnecessary fluff.

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 and the absence of an output schema, the description provides a comprehensive overview including the return structure ('{ mappings ... unmapped, staleOverrides, profile }'), the override mechanism, and how stale entries are handled. It is sufficiently complete for an agent to select and invoke the tool correctly, though more detail on the 'candidate' fields could be added.

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

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

The input schema covers 100% of the parameters (nodeId, rootDir, threshold) with descriptive text. The tool description does not add significant parameter-level detail; it focuses on high-level behavior. Since schema coverage is complete, the baseline of 3 applies.

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

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

The description clearly states the tool's function: 'Map the Figma component instances in a selection/subtree to existing local code components, so they can be reused instead of regenerated.' This provides a specific verb (map), resource (Figma component instances to code components), and purpose. It also distinguishes itself from sibling tools like scan_components or get_local_components by focusing on mapping/reuse.

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 for when to use the tool: when you need to map Figma components to existing local code components for reuse. It implies the scenario ('so they can be reused instead of regenerated') but does not explicitly mention when NOT to use it or provide alternative tool names. Thus it meets the 'clear context, no exclusions' bar.

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?

Despite annotations being present (readOnlyHint: false, destructiveHint: false), the description adds valuable behavioral context far beyond that: it explains that converting preserves the node's position and parent unless overridden, defaults to the current page, and discloses the exact return shape. This tells the agent what side effects to expect and how results are returned, exceeding the baseline.

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 the core action and structured logically: purpose, two modes with an example, follow-up, options, and return. It is slightly longer than minimal (5 sentences) but each sentence contributes, and the em-dash aside is a natural clarification. It is not wasteful but could be tightened slightly.

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 7 optional parameters and no output schema, the description covers the main decision points, defaults, and return shape. It addresses both creation modes and implies the use case for importing SVG frames. It does not discuss edge cases like invalid node types or what happens to children, but for routine use it is sufficiently 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?

With schema description coverage at only 29%, the description compensates well. It explains the crucial fromNodeId at length (what it does, with an example, and the preservation behavior) and notes parentId's default. It also groups the remaining numeric/name parameters as 'sized / named / positioned,' giving them meaning without enumerating. This is a strong compensation, though it could still clarify specific units or coordinate origins.

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 'Create a reusable main component,' a specific verb+resource statement, and immediately clarifies the two operational modes (fromNodeId vs. empty). It distinguishes itself from the sibling create_instance by explicitly stating the follow-up step, so the purpose is unambiguous and differentiated.

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 when-to-use guidance: 'Pass fromNodeId to convert an existing node' and 'omit fromNodeId to create an empty component.' It also points to create_instance as the next step, offering alternative sequencing. However, it does not explicitly cover exclusions (e.g., unsupported node types) or compare against other sibling tools, leaving a small gap in full 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 declare readOnlyHint=false and destructiveHint=false, consistent with a creation operation. The description adds value by specifying the return shape ({ ok, styleId, name }) and conditional requirements (shadows need color+offset, blurs need radius), which are not in the annotations. This gives the agent more context about expected behavior and side effects.

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 deliver the core purpose, the parameter requirements, and the return value. No filler or redundant phrasing; every sentence adds new information. Front-loaded with the action verb.

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 creation tool with no output schema, the description provides the return shape and parameter guidance, which is sufficient for basic invocation. It doesn't mention error conditions or whether the style is added to the current page or document, but 'local' implies current context. The complexity of the effects array is addressed by the shadow/blur distinction.

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

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

Schema coverage is only 33% – only color and offset have descriptions. The tool description compensates by explaining the semantic distinction between shadow and blur parameters, which directly tells the agent when to provide color/offset vs radius. However, it doesn't explain 'spread' or the optional 'description', so some parameter semantics still rely on the schema field names.

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 'Create a local effect style' – a specific verb and resource that clearly identifies the operation. It distinguishes effect styles from other style types (paint/text/grid) via the 'effect' qualifier, and the 'local' scope differentiates from shared/team styles. The parameter note about shadows vs blurs further confirms this is specifically about effect 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?

The description implies usage for creating effect styles but does not explicitly contrast with sibling tools like update_effect_style or apply_style_to_node. It says 'local effect style', which suggests use for file-local styles, but no when-not guidance is provided. There's no mention of alternatives, so the agent must infer from sibling names.

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 indicate non-read-only and non-destructive behavior, so the description adds a return shape ({ ok, nodeId, name, type }) and default parent context. It does not disclose side effects on existing nodes, coordinate system details, or error behavior, but this is acceptable given annotation coverage and the simple creation task.

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 core action, and every clause earns its place—covers default behavior, the circle condition, and a pointer to a related tool. No redundancy or filler.

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

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

Without an output schema, the description provides the return shape, which is valuable. It covers the main functionality (create, optional attributes, parent default) and directs to set_arc for further shaping. It omits potential edge cases like invalid parentId or coordinate system units, but for a creation tool with a well-described schema, this is adequate and near 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 covers 100% of parameters with descriptions, so baseline is 3. The description adds meaningful nuance: 'circle when width equals height' clarifies the relationship between width and height, and 'default: current page' reinforces the parentId default (already in schema but helpful to highlight). No parameter semantics are contradicted.

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 verb and resource: 'Create an ellipse', with a helpful clarification that equal width/height produces a circle. It distinguishes from sibling tools like create_rectangle and create_text by focusing on ellipse-specific behavior, including optional attributes and default parent.

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?

Provides clear context: the tool creates an ellipse with optional sizing/naming/positioning under a parent (default current page). It explicitly routes to set_arc for transforming into pie/arc/ring, giving an alternative for subsequent needs. It does not explicitly contrast with create_rectangle, but the resource type is unambiguous.

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 say readOnlyHint=false and destructiveHint=false, indicating a mutation but not a destructive one. The description adds valuable context: frames can be sized/positioned and appended to a parent (defaulting to current page), and it discloses the return shape. It doesn't mention edge cases like invalid parents or selection changes, but for a create operation this is reasonably transparent.

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

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

Two sentences with zero waste. The description front-loads the core purpose, adds a key capability (auto-layout host), gives a sibling alternative, and concludes with the return structure. 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?

Given 6 optional params and no output schema, the description covers the essentials: what the tool creates, default behavior, guidance for related tools, and return value. It doesn't explain all edge cases (e.g., invalid parentId, insertion order), but for a create-node tool this is sufficiently complete for an AI agent to understand usage.

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 covers 67% of parameters (x and y lack descriptions). The description compensates by noting that sizing/positioning is optional and that parentId defaults to the current page. This adds meaning beyond the schema and clarifies optionality, though it doesn't explain units or coordinate origin, which are likely obvious to the target user.

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 uses the specific verb 'Create' with the resource 'frame' and clearly distinguishes it from siblings: it positions the frame as the primary UI container and the only auto-layout host, explicitly contrasting with create_section for canvas-level grouping. This is more than a tautology and fully clarifies what the tool does.

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

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

The description gives clear context: frames are for auto-layout UI, and it points to set_auto_layout for enabling auto-layout after creation. It also names create_section as the alternative for grouping. It doesn't explicitly say when not to use it (e.g., for simple shapes), but the primary use case and alternative are well communicated.

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 indicate the tool is not read-only and not destructive, which is minimal. The description adds meaningful behavioral context: the grid pattern structure (GRID via sectionSize, ROWS/COLUMNS via count+gutterSize+alignment) and the return shape ({ ok, styleId, name }). It does not disclose edge cases like naming conflicts, but what is provided goes beyond 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, no fluff. Front-loaded with purpose, then pattern details, application hint, and return value. Every clause is informative.

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 there is no output schema, the description correctly includes the return shape. It explains the core patterns and application workflow. It doesn't cover every parameter (offset, visible) or error conditions, but the tool is moderately simple and the description is sufficient for a typical use case.

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

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

Schema coverage is only 33% (only 'name' has a description). The description compensates by explaining the semantics of the pattern enum and how sectionSize, count, gutterSize, and alignment relate to each pattern. It does not cover offset, visible, or the top-level description param, but the main grid logic is clarified.

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 creates a reusable local layout-grid style, which is a specific verb+resource. It distinguishes this from siblings like set_layout_grids (which applies grids directly) and apply_style_to_node (which applies a style) by focusing on creation and reuse. The pattern details (GRID, ROWS, COLUMNS) further clarify the scope.

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 signals when to use this tool: for creating a reusable style, not for one-off grid application. It explicitly points to apply_style_to_node as the follow-up for applying the created style. It does not explicitly mention alternatives like set_layout_grids for non-reusable cases, but the 'reusable' qualifier implies the distinction.

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 that this is a mutating (readOnlyHint: false) and non-destructive action. The description adds valuable behavioral details: the two acceptable source identifiers, optional position/name/parent parameters, and the return shape { ok, nodeId, name, type }. It does not disclose error behavior when both or neither identifier is provided, but overall complements the annotations well.

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

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

Four tight sentences deliver all key information without redundancy. Every sentence earns its place: purpose, source identifiers, optional parameters, and return value.

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 main usage modes, optional placement, and the return contract, which is adequate for a tool with no output schema. However, it omits behavior when both or neither componentId/componentKey are supplied, leaving a potential ambiguity given no required parameters. Overall, it is nearly complete for typical usage.

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 descriptions cover componentId, componentKey, name, and parentId, while x and y have no schema descriptions. The description adds meaning by referring to 'name / position / parent', implicitly explaining x/y as position and reinforcing the semantics of the other parameters. This compensates for the 67% schema coverage, though x/y could have been more explicit.

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 uses the specific verb 'Instantiate' with the resource 'component', and clearly distinguishes between local and published component sources via componentId and componentKey. This sets it apart from sibling tools like create_component or swap_component, making the purpose 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 clearly indicates when to use this tool (to create an instance from a local or published component) and provides context for optional placement. However, it does not explicitly state when not to use it or name alternative tools, so it stops short of full usage 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 indicate readOnlyHint=false and destructiveHint=false, which are consistent with a mutation that is not destructive. The description goes beyond annotations by disclosing the 'local' scope (not in a library), the naming convention with slashes for folder grouping, and the return value shape '{ ok, styleId, name }'. This adds useful behavioral context not present in annotations or schema.

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

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

The description is concise and efficiently structured. It packs essential information into two sentences: the core creation capability, the input shape hint, naming convention, related workflows, and return value. Every sentence contributes value with no superfluous content.

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 three parameters, no output schema, and moderate complexity, the description is fairly complete. It covers purpose, input specifics, workflow, and return value. It does not discuss potential failure cases like duplicate style names or permission requirements, but these are not critical for a create-style tool with non-destructive annotations. The availability of related sibling tools (apply_style_to_node, update_paint_style) further rounds out the context.

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 schema has 100% description coverage, though some descriptions are minimal (e.g., 'Paints'). The description adds meaning by referencing 'same shape as set_fills' for the paints parameter, which is valuable for agents familiar with that sibling tool, and by explaining the name parameter's folder grouping convention via slashes. This exceeds the baseline for schema-covered 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 description clearly states the tool's function: 'Create a reusable local paint (color) style from SOLID or gradient paints'. It identifies the specific resource (paint style), the action (create), and the input types. It also distinguishes itself from sibling tools like create_text_style and update_paint_style by naming the exact workflows for applying and editing the style.

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

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

The description provides clear usage context by explaining the lifecycle: 'Apply it to nodes with apply_style_to_node, or edit it later with update_paint_style.' It does not explicitly list when not to use the tool, but referring to alternative sibling tools for application and editing gives good contextual guidance. The distinction from other create_*_style tools is implied by the tool name and the paint-specific focus.

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 already indicating readOnlyHint=false and destructiveHint=false, the description adds the return shape ({ ok, nodeId, name, type }) and the default parent behavior (current page). This goes beyond the annotations and clarifies the mutation effect without contradiction.

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 the key information front-loaded: action, options, use cases, alternatives, and return value. No redundant or filler text; 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?

For a simple creation tool with no output schema, the description adequately covers the return value, default behavior, and sibling alternatives. It is 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?

The schema covers all 6 parameters with descriptions (100% coverage), so the baseline is 3. The description adds light context about 'optionally sized/positioned' and 'default: current page' but does not add deeper syntax or format details 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 clearly states 'Create a rectangle' with optional sizing/positioning and append behavior, and distinguishes it from sibling tools like create_frame and import_image by specifying use cases. This is a specific verb+resource+scope definition.

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 names alternatives: 'for a container that holds other layers use create_frame, and for placed bitmaps use import_image.' Also provides use cases (solid shapes, dividers, color blocks), giving clear when-to-use and when-not-to-use 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?

The description discloses the return shape ('Returns { ok, nodeId, name, type }') and placement constraints ('Sections sit on a page or nest inside another section, but not inside a frame'), adding value beyond the basic readOnly/destructive flags. It doesn't mention error conditions, but for a create operation this is sufficient.

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, starting with the action and resource, then adding placement rules and return value. There is no redundancy or filler; 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?

For a simple create tool, the description covers purpose, placement constraints, alternative tool, and return shape. Combined with full schema coverage and consistent annotations, the agent has enough information 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?

All 6 parameters are already described in the schema with clear semantics (e.g., 'Parent page or section id (default: current page)'), so the description doesn't need to restate them. It doesn't add extra parameter detail, but the schema fully covers it, so baseline 3 applies.

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

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

The description begins with 'Create a section' and defines it as 'a canvas-level container for grouping and labelling regions of a page', clearly stating what the tool does. It distinguishes from create_frame by explicitly saying 'for a UI container or auto-layout use create_frame instead', making the purpose unambiguous.

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

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

It explicitly states the use case ('grouping and labelling regions of a page') and the exclusion ('not inside a frame'), and points to an alternative tool ('use create_frame instead'). This gives clear when-to-use and when-not-to-use 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 already indicate this is a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds valuable behavioral context: the default font is loaded automatically, the node is appended to a parent (defaulting to current page), and the return value includes { ok, nodeId, name, type }. This exceeds the structured annotations without contradicting them.

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: the first front-loads the core action and key options, the second gives targeted alternatives and return value. Every sentence earns its place, and there is no redundancy or filler.

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

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

Given the tool's simplicity, the description covers the essential aspects: creation, optional placement, parent default, and return metadata. Since there is no output schema, the explicit mention of the return value is especially useful. It does not cover error conditions or permissions, but for a create operation with good annotations and schema, this is sufficient.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that parentId is optional and defaults to the current page, and that characters are required, but does not add new semantic meaning beyond what the schema already provides for x, y, fontSize, or characters. It does not significantly enhance parameter understanding.

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 ('Create a new TEXT node') with a clear resource and details about optional sizing, positioning, and parent assignment. It also distinguishes itself from sibling tools like set_text and set_text_properties, making its purpose 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 explicitly provides when-to-use guidance by naming alternatives: 'To change the text of an existing node use set_text; for font, size, or color use set_text_properties.' It also clarifies the default parent behavior, giving clear context for tool 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?

While annotations only provide readOnlyHint=false and destructiveHint=false, the description adds meaningful behavior: 'The font is loaded before assignment' and explains edge-case unit semantics (AUTO omits value). It stops short of describing potential failure modes or side effects, but the added context goes beyond 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?

The description is three sentences, front-loaded with the primary purpose, followed by key behavioral details and an explicit alternative. Every sentence serves a purpose, with no redundant or filler content.

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 is remarkably complete given the tool's complexity: it covers creation, reusability, application method, font loading, unit specifics, the alternative for one-off use, and the return shape. Minor gaps exist around error conditions or naming uniqueness, but the core usage context is well-covered.

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

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

Schema description coverage is only 17%, so the description must compensate. It does explain lineHeight and letterSpacing unit semantics, and the font loading behavior relates to fontName. However, it doesn't elaborate on fontSize, description, or the exact structure of fontName beyond what the schema offers, leaving some parameters without additional semantic depth.

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 it creates a reusable local text style (a typography token) for TEXT nodes, using a specific verb and resource. It distinguishes itself from sibling tools like set_text_properties and other create_style tools by specifying text typography and reuse.

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 provides an alternative: 'For one-off formatting of a single node use set_text_properties instead.' It also implies when to use this tool by mentioning that the style can be applied later via apply_style_to_node, making the usage context clear.

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

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

Annotations only indicate readOnlyHint=false and destructiveHint=false, but the description adds valuable context beyond that: the variable starts empty, EASING/TIMING are rejected, and the return value is { ok, variableId, name }. It also differentiates this tool from related ones by explaining what it does NOT do (set values or bind).

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 three sentences: the first states the core purpose, the second explains the workflow, and the third notes a limitation and return value. Every sentence adds value and the most important information is front-loaded. No filler or unnecessary repetition.

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 create operation with no output schema, the description covers the essential behavior: what it creates, the allowed types, the initial empty state, the required follow-up actions, the unsupported types, and the return format. Considering the sibling tool landscape, it fully equips the agent to use this tool correctly within the broader workflow.

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 covers 100% of parameters with descriptions, so baseline is 3. The description repeats the resolvedType enum values but does not add new meaning for each parameter beyond what the schema already provides. It does mention the types in the context of the tool's purpose, but that is not extra semantic detail.

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: 'Create a variable in a collection with resolvedType BOOLEAN / FLOAT / STRING / COLOR.' This clearly identifies the tool's function and scope. It also distinguishes itself from sibling tools like set_variable_value and bind_variable_to_node by explaining the variable starts empty and requires subsequent steps.

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 explicit usage sequencing: 'set per-mode values with set_variable_value, then attach it with bind_variable_to_node or bind_variable_to_paint.' It also gives a clear exclusion: EASING and TIMING variables cannot be created by plugins and must be made in the Figma UI. This guidance is actionable and helps the agent decide when to use this tool.

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 indicate non-read-only and non-destructive behavior. The description adds valuable behavioral context: Figma auto-creates a default mode, and the return shape is explicitly given as { ok, collectionId, defaultModeId, name }. This goes beyond the annotation information and helps the agent understand side effects and output.

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

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

The description is two sentences, concise and front-loaded with the main action. It includes only essential information about the default mode and return value, with no unnecessary detail or repetition.

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 simplicity (one parameter, no output schema), the description covers purpose, side effect, and return value. It does not explain edge cases or error behavior, but such detail is not critical for this straightforward creation tool. The provided information is sufficient 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?

The input schema fully describes the only parameter 'name' with an example ('Theme'). The description does not add additional parameter semantics beyond the schema, so the baseline score 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 clearly states the action: 'Create a variable collection.' It is specific to the resource and distinct from sibling tools like 'create_variable' and 'add_variable_mode.' The added note about Figma auto-creating a default mode further clarifies the tool's purpose.

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 the tool is used when creating a variable collection, but it does not explicitly state when to use it versus alternatives or provide exclusions. No mention of when not to use it or other contexts, leaving usage guidance somewhat implicit.

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

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

Given destructiveHint=true, the description adds meaningful context beyond annotations: it specifies exactly what gets destroyed (property and every sublayer reference) and that it refuses VARIANT properties. It also discloses the return value, making the tool's behavior predictable.

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, front-loaded with the main purpose, then exclusions and return info. Every sentence contributes essential information without redundancy or irrelevant 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?

Despite no output schema, the description explicitly states the return object { ok, componentId, propertyId, name }, covers side effects (sublayer references), and explains refusal behavior. This is complete for a destructive tool with two parameters.

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% with descriptive parameter texts, so the baseline is 3. The description adds minimal extra value by reminding users to obtain property ids from get_component_api, but this is already implied in the schema description for propertyId.

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 removes BOOLEAN / TEXT / INSTANCE_SWAP properties from a component and all sublayer references, which is specific and distinguishes it from sibling tools like add_component_property or edit_component_property. It also explicitly excludes VARIANT properties, further clarifying its scope.

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 provides explicit when-not-to-use guidance: 'VARIANT properties are the variant-set structure — delete their variants instead; this refuses a VARIANT.' It also directs users to get current property ids from get_component_api, which is a clear prerequisite. This is beyond typical guidance and helps the agent choose correctly.

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 destructiveHint=true, and the description reinforces it with 'Permanently delete.' It adds context beyond annotations: missing/non-removable nodes are skipped, and the return shape `{ ok, affected }` is disclosed. No contradictions.

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, each earning its place: the action, the exception behavior, the alternative, and the return value. Front-loaded with the primary purpose, no redundancy or filler.

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

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

For a destructive tool with one parameter and no output schema, the description is complete: it states permanence, skips semantics, provides a reversible alternative, and specifies the return object. No critical information 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% because nodeIds has a clear description ('Node ids to delete'). The tool description adds that invalid/missing ids are skipped, which slightly enriches parameter semantics, but the core meaning is already fully documented by 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: 'Permanently delete nodes by id.' It clearly distinguishes from siblings like set_visible by noting the deletion is permanent and by offering a reversible alternative. The scope 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?

Explicitly states when to use this tool vs. an alternative: 'To hide nodes reversibly instead of deleting them, use set_visible(false).' Also clarifies behavior for missing/non-removable nodes, so an agent knows how edge cases are handled.

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 indicate destructive behavior, but the description adds valuable context: deletion is blocked for the current page and the last remaining page, and the return value is { ok, nodeId }. This goes beyond the annotations and helps the agent anticipate edge cases.

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 concise sentences: the first states the primary action, the second notes constraints and return value. Every word earns its place; no redundancy.

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

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

For a simple tool with one parameter and no output schema, the description fully covers the action, constraints, and return shape. The schema handles the parameter definition, and the description provides all necessary behavioral context.

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% for the single parameter (pageId) with a clear description. The tool description does not add additional parameter semantics, but the schema already fully documents the parameter, so baseline 3 is appropriate.

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

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

The description uses a specific verb ('Delete'), a clear resource ('a page'), and the method ('by id'). It distinguishes from sibling tools like delete_nodes by focusing specifically on pages, and adds constraints that clarify scope.

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 states explicit conditions for use: the current page and the last remaining page cannot be deleted. However, it does not explicitly mention alternatives (e.g., delete_nodes for non-page nodes), though the tool's name and scope make this reasonably 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?

The description adds value beyond the destructiveHint annotation by specifying the return payload (`{ ok, styleId, name }`). It confirms the destructive nature and scopes to local styles, though it does not detail side effects or error conditions.

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, front-loaded sentence that immediately states the action and resource, followed by the return value. No wasted words.

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 only one parameter, no output schema, and clear annotations, the description is largely complete for this simple tool. It covers what is deleted, by what identifier, and what is returned. Minor gaps like error handling or style-in-use behavior are not critical given the 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 description coverage is 100%, so the parameter `styleId` is already well-documented in the schema. The description's mention of 'by id' confirms the parameter's purpose but does not add new meaning 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 clearly states the tool deletes a local style by id and enumerates the style types (paint/text/effect/grid). This specific verb+resource combination distinguishes it from sibling tools like delete_variable and delete_page.

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 that this deletes local styles by id, implying it is the appropriate tool for that action. It does not explicitly name alternatives or exclusions, but the context is sufficiently unambiguous.

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 flag destructiveHint=true, so the description adds value by detailing the side effect: 'any node or paint bound to it reverts to its raw value.' It also discloses the return shape, which is useful since no output schema exists.

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, no filler, front-loaded with the core action and side effect. Every sentence serves a purpose.

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 single-parameter destructive tool with no output schema, the description covers purpose, side effect, alternative, and return value. It is complete for the tool's complexity.

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 already covers the only parameter (variableId) with a clear description, so the description adds little beyond 'by id'. Baseline 3 is appropriate given 100% schema coverage.

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?

Uses specific verb 'Delete' with resource 'variable' and clarifies it's a single variable. Explicitly contrasts with delete_variable_collection for whole collections, distinguishing it from 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?

Explicitly instructs when to use delete_variable_collection instead: 'To delete an entire collection and all its variables use delete_variable_collection.' This provides a clear alternative and when-not condition.

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 destructiveHint annotation, the description discloses the full destructive scope (removes collection, all variables and modes) and the side effect that bindings revert to raw values. It also specifies the return shape, enriching the tool's behavioral context.

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 three sentences with no fluff. It front-loads the action and consequences, then gives the alternative, then the return value—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?

The description is self-contained, covering purpose, destructive impact, side effects, alternative usage, and return value. Given its cascading deletion behavior and lack of an output schema, this level of detail makes it fully sufficient for an agent.

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 sole parameter collectionId is already fully described in the schema (100% coverage). The description only repeats 'by id' without adding extra format, source, or prerequisite details, so it meets the baseline but does not exceed it.

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 uses the specific verb 'Delete' and identifies the resource (variable collection), while explicitly contrasting with delete_variable for single variables. This clearly distinguishes it from sibling tools and states the operation's scope.

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 states 'To delete a single variable instead, use delete_variable,' providing a clear alternative and when-not-to-use guidance. This helps the agent choose between delete_variable_collection and delete_variable.

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?

Even with readOnlyHint=true, the description goes beyond by disclosing that the tool writes a baseline file under .figwright/snapshots/, never touches git, and never mutates Figma. It also transparently explains the update:true re-snapshot behavior and the default nodeId/rootDir behavior, providing a complete picture of side effects and state changes.

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 dense single paragraph, but every sentence contributes: purpose, lifecycle, statuses, diff contents, update flag, defaults, file location, git behavior, and mutation guarantee. It could be slightly more scannable with bullets, but it is not padded or 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?

For a tool with no output schema, the description covers all necessary contextual information: status return strings, what changes are included, the update mechanism, path defaults, the baseline file's relationship to git, and that Figma is never mutated. This is complete enough for an agent to invoke the tool correctly without further probing.

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?

Despite 100% schema coverage, the description adds meaning beyond raw parameter names: nodeId defaults to selection and accepts pasted URLs, update:true means 'accept the changes' and re-snapshot, rootDir defaults to server cwd. These semantic details are not present in the schema and help the agent use the parameters correctly.

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 action: 'Diff a Figma node against a saved baseline of itself.' This clearly distinguishes it from sibling tools like get_design_context by focusing on change detection rather than full context retrieval. The scope is explicit (per-node, per-property) and the lifecycle (baseline-created vs diff) is stated.

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 strong use case ('edit only the affected code instead of regenerating') and explains the first-call vs later-call behavior. However, it never explicitly names alternatives or states when not to use this tool; the guidance is implied rather than direct, so it stops short of a 5.

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

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

Annotations already mark the operation as destructive, but the description adds valuable context: it is 'permanently breaking' the link, the frame 'keeps its current appearance,' and layers become 'directly editable.' It also discloses the return shape { ok, nodeId, name, type }, exceeding what annotations or schema provide.

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 that are tightly packed with purpose, effects, alternative usage, and return value. No filler or repetition of schema details. Each sentence contributes meaning.

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

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

For a simple one-parameter destructive operation, the description covers what the tool does, the permanent consequence, the retention of appearance, the editability result, the alternate tool, and the return format. It is fully complete given the tool's simplicity and existing annotations.

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 schema covers 100% of the single parameter with a clear description ('Instance node id to detach'). The tool description does not add additional parameter-level semantics, but the baseline of 3 applies because the schema handles the parameter meaning sufficiently.

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 uses the specific verb 'Detach' with a clear resource ('a component instance into a plain frame') and explains the consequence ('permanently breaking its link'). It also distinguishes itself from the sibling tool swap_component by explicitly naming the alternative.

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 states exactly when to use this tool (when you want to detach into a plain frame) and provides an explicit alternative for a different use case: 'To switch an instance to a different component instead of detaching, use swap_component.' This is clear guidance with an exclusion.

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 reveals critical behavioral details beyond the annotations: renaming returns a new propertyId (keeping the #id suffix but changing the name part), requires using the returned propertyId later, and existing bindings keep working. It also explicitly states the return shape. These are non-obvious side effects that the annotations (readOnlyHint=false, destructiveHint=false) 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?

Four sentences pack all essential information with no filler. The description is front-loaded with the core action, then covers usage constraint, behavioral nuance, source of IDs, and return value—all in a compact, structured manner.

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?

Despite having no output schema, the description states the return object explicitly. It covers preconditions (property ids from get_component_api), special cases (INSTANCE_SWAP only), and post-conditions (renaming ID change, bindings preserved). Given the tool's moderate complexity and five parameters, this description is sufficiently complete for an agent 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%, so the baseline is 3. The description adds value by clarifying that at least one of name/defaultValue/preferredValues must be supplied, and that preferredValues is only applicable for INSTANCE_SWAP properties. It also explains the propertyId format implication ('#id suffix is kept'), which is not fully captured in 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 'Change an existing component property' and enumerates three specific operations: rename, change defaultValue, or change preferredValues (for INSTANCE_SWAP only). This clearly distinguishes it from sibling tools like add_component_property or delete_component_property by focusing on modifying existing properties.

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 instructs 'Supply at least one' and tells the user to get current property ids from get_component_api, which serves as a prerequisite. It implies when to use this tool (when an existing property needs modification) but does not explicitly mention alternatives or exclusions, so it's clear 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?

Beyond the readOnlyHint annotation, it discloses the tool's inability to paginate or merge nodes, warns about slow performance on large pages, and specifies return behavior including null path when missing/not exportable and empty:true for blank PDFs. This is rich context that goes well beyond 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?

Each of the four sentences carries distinct information: core function, API limitation, usage/alternative, and return values/edge cases. It is front-loaded and every sentence earns its place without fluff.

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 has no output schema, the description fully explains the return object and failure modes, while also covering purpose, limitations, alternatives, and parameter usage. This is a complete picture 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 descriptions already cover both parameters (nodeId and outPath) with 100% coverage. The tool description repeats the nodeId semantics and adds a performance caution for large pages, but does not significantly enhance understanding beyond what the schema provides.

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

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

The description clearly states it exports a node or the current page to a single-page vector PDF, specifies valid node types (frame/section/component), and distinguishes itself from save_screenshots by noting raster vs vector output. This is a specific verb+resource+output combination.

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 names save_screenshots as an alternative for raster output (PNG/JPG), explains the API's pagination limitation to prevent mis-use for multi-page exports, and gives concrete guidance on when to pass nodeId vs omit it for the current page.

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?

Despite readOnlyHint: true, the description adds substantial behavioral context: it is a heavy render that should be called alone, failure modes are clearly described (path:null with a reason, and Figma's own error when reason is 'failed'), and prerequisites are stated. These details go beyond what annotations alone provide.

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 dense but every sentence serves a purpose: purpose, node selection, prerequisites/failure modes, concurrency warning, and return shape. It is slightly wordy in the middle section listing failure cases, but generally well-structured and front-loaded with the primary action.

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 all critical operational aspects: input requirements, output formats, failure conditions, performance constraints, and the returned object shape. With no output schema, it fully communicates what the agent can expect, making it complete for a tool of this complexity.

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

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

The input schema already has 100% parameter coverage with detailed descriptions for all 7 parameters. The tool description reinforces the nodeId semantics ('Pass any node in the frame or the frame itself') but does not add additional meaning beyond the schema. 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 clearly states the verb 'Export' and the specific resource: 'an animated Figma top-level frame' to targeted output formats ('MP4 / WebM / GIF file on disk'). It also details the node-acceptance nuance (any node in the frame or the frame itself), which differentiates it from sibling export tools like export_pdf.

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 explicit context on when to use the tool (requires Figma Design editor and animated content) and when not to use it (static frame, nested frame, FigJam, Dev Mode all yield path:null). It also warns against concurrent calls. However, it does not explicitly name alternative sibling tools like export_pdf for static exports, 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 only flag readOnlyHint=false and destructiveHint=false, so the description adds valuable behavioral context by disclosing that fonts are loaded before each edit and that the operation affects text nodes. It also explains the scope default and case sensitivity, which are beyond the structured fields. 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?

The description is concise and front-loaded, with the first sentence stating the core purpose. Each subsequent sentence adds a distinct piece of useful information (scope, case sensitivity, font loading, return value) with no redundancy or fluff.

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

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

For a tool with no output schema and four parameters, the description covers the essential usage semantics, return value, and a side effect (font loading). It could mention potential error conditions or confirm the batch nature, but it is largely complete for selecting and 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?

With 100% schema coverage, the description adds helpful context to parameters: it clarifies that 'root' defines the scope (defaulting to page), that 'caseSensitive' overrides the default case-insensitive matching, and that 'find'/'replace' are substring-based. This enrichment goes beyond the bare schema descriptions, meriting a 4 rather than 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?

The description clearly states the verb ('replace'), resource ('substring across all TEXT nodes under a scope'), and distinguishes it from sibling text-editing tools by emphasizing the bulk scope operation. The alternative of searching the whole page when no root is given further clarifies its purpose.

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

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

The description provides clear usage context, including the default scope (whole page) and case-sensitivity behavior, which implies when to use this tool. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of a 5.

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

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

The readOnlyHint annotation already declares a safe read operation, and the description adds valuable context by specifying the return structure and the conditional page-scan behavior. It does not disclose performance implications, but the annotation covers the safety profile adequately.

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, front-loaded sentence that efficiently conveys the core purpose and both usage modes without redundant wording or unnecessary detail.

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

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

For a simple read tool with one optional parameter and no output schema, this description fully covers the return format and both invocation paths. An agent can invoke it correctly without needing additional assumptions.

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

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

The input schema fully documents nodeId, including the omit-to-scan-current-page behavior. The description echoes this but adds no new parameter-specific details beyond the schema, 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 clearly states the tool 'Return[s] Dev Mode annotations' and specifies the exact output shape. It also distinguishes two modes (with or without nodeId), making its purpose unambiguous and differentiating it from sibling read tools like get_metadata or get_selection.

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 when to use each mode: include nodeId for a specific node, or omit to scan the current page. It does not explicitly mention alternatives or when-not-to-use, but the dual-mode guidance is sufficient for effective 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?

Beyond the readOnlyHint annotation, the description discloses meaningful behavior: instances resolve to their main component/set, the exact return shape, and the property naming convention for set_instance_properties. It also notes safety on large files, adding practical context.

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

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

Three dense sentences, each earning its place. The first sentence states the core purpose, the second details the return structure, and the third covers naming semantics and differentiates from get_local_components. No wasted words.

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 compensates by explaining the return object shape, property map types, and naming conventions. It also addresses performance context and input variations, making it complete for practical use.

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 a genuinely useful nuance beyond the schema: 'an instance resolves to its main component / set'. This extra semantic detail merits a 4.

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: 'Return a component's full property API — the prop contract behind its instances.' It clearly scopes the tool to a single component and explicitly contrasts it with get_local_components, making it easy to distinguish from 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?

The description explicitly says 'Unlike get_local_components (a subtree inventory), this targets one component and is safe on large files.' This names the alternative and gives a clear when-to-use signal. It also lists accepted id types, further guiding invocation.

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=true, so the description carries the transparency burden. It discloses error behavior when neither nodeId nor selection is available, graceful degradation from full to compact to sectionPlan, dedupe semantics with flags and preserved overrides, and the hypothesis-based nature of projectTokens. This is far beyond what annotations provide.

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 dense single paragraph, front-loaded with the main purpose and containing no filler. However, the length and density could benefit from bullet points for scannability, especially the degradation and token-matching caveats. Every sentence earns its place, so no waste, but structure is a minor miss.

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 explains return shapes (sectionPlan, projectTokens, dedupe flags), error cases, and the over-budget degradation path. It also covers edge cases like multiple tokens sharing a value and how to verify matchedBy. This is comprehensive for a tool of this complexity.

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 operational depth: detail levels map to output shapes, depth=0 means unlimited with truncation flags, and dedupeComponents collapses subtrees while preserving textOverrides and propertyOverrides. For example, it explains that deduped instances still carry visible text, which is not inferable from 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?

Description states 'Get a depth-limited, token-efficient node tree' and positions it as 'the main design-grounding read', clearly distinguishing it from sibling tools like get_document and get_node. The verb 'get' plus the resource 'node tree' with scope qualifiers makes purpose 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?

Explicitly directs 'prefer it over get_document / get_node for anything large', and gives specific tactical guidance: 'pass detail: compact explicitly for a cheap structure scan' and warns 'do not retry unscoped — call again per section nodeId'. This is strong when/when-not guidance with named alternatives.

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 read-only nature is known. The description adds that children are returned recursively and that geometry, rotation, opacity, cornerRadius, and fills are enriched, which is useful. However, it does not disclose potential limitations (e.g., handling of very large trees, what happens if no page is active) or output structure details.

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, front-loaded sentence that efficiently communicates the tool's action, scope, and output details. No unnecessary words or repetition.

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 no output schema, the description lists the enriched fields (base geometry, rotation, opacity, cornerRadius, fills), giving a good sense of the output. It is reasonably complete for a read-only tree retrieval tool, though it could mention error conditions or the exact shape of the returned tree.

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

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

There are zero parameters, so the baseline is 4. The description clarifies that the tool operates on the 'active Figma page', which provides meaningful implicit context about what is being returned without needing schema 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 description clearly states the tool returns the full recursive node tree of the active Figma page, with specific enrichment fields. This distinguishes it from siblings like get_node (single node) and get_nodes_info (specific nodes) by explicitly targeting the entire 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?

The description implies when to use this tool: when you need the complete page tree rather than specific nodes. It gives clear context but does not explicitly name alternatives or include when-not-to-use instructions, so it falls short of full guidance.

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

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

The annotation readOnlyHint=true already indicates a safe read operation. The description adds meaningful behavioral details: sorting by frequency descending, the exact output shape, and how mixed-font text is counted (one count per styled segment). This goes beyond the minimal safety info and enriches the agent's understanding of the tool's 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 a single sentence that front-loads the primary purpose, then provides essential output details and edge-case behavior. Every word earns its place: no filler, no repetition, and the structure is optimal for quick parsing by an agent.

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 tool is simple with no parameters and no output schema, but the description fully specifies the return shape, sorting order, and counting rule for mixed fonts. This covers all necessary contextual information for an agent to select and invoke the tool without ambiguity. The description is complete for the tool's complexity level.

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

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

With zero parameters and 100% schema coverage (vacuously), the description carries no parameter burden. The baseline for no parameters is 4, and the description appropriately focuses on output semantics rather than parameter documentation. It fully satisfies the need for parameter clarity given there are none.

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

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

The description clearly states the tool's function: return every font on the current page with counts, sorted by frequency. It uses a specific verb ('Return') and resource ('every font used on the current page'), and the output format is explicitly defined. This distinguishes it from sibling tools like get_styles and get_variable_defs, which serve different resources.

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: when you need a list of fonts with usage counts on the current page. It provides clear context but does not explicitly mention alternatives or when not to use it. Since the purpose is self-evident and distinct from siblings, this is clear context without exclusions, matching a score of 4.

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 adds meaningful behavioral details: it returns a structured object, recursively scans a subtree, and only includes local components/sets. It also discloses what data each result type carries (variantProperties, variantGroupProperties, variant component ids), which helps the agent understand the operation's side-effect-free, read-only nature and output shape.

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 three dense sentences, each earning its place: the first states the purpose and return shape, the second explains scope and usage, and the third details the data carried by components and component sets. There is no filler or repetition of schema content.

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 specifies the return structure ({ components, componentSets }) and the attributes of each component type. It also explains the nodeId selection fallback, making the tool's behavior complete for a one-parameter read-only operation.

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 schema already covers the single parameter nodeId with a clear description ('Root node id to scan within; omit to use the current selection'), giving 100% schema coverage. The description reinforces the 'pass nodeId or select frames' behavior but adds no new meaning beyond the schema, so a baseline score 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 uses a specific verb ('Return') and names a precise resource ('components and component sets within a node subtree or the current selection'). It clearly distinguishes itself from document-wide scanning tools by emphasizing 'Scans a subtree, not the whole document', which differentiates it from siblings like scan_components or component_map.

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

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

The description provides clear usage context: it scans a subtree rather than the whole document, with two ways to scope the operation ('pass nodeId, or select the frames to scan'). It stops short of explicitly naming alternative tools for whole-document scans, but the 'not the whole document' note effectively communicates 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?

The annotation readOnlyHint=true already signals a safe read operation. The description adds value by explaining the meaning of editorType modes ('dev' is read-only, 'figjam' lacks components/variables/styles), which is behavioral context beyond the annotation. No contradiction exists.

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, well-structured sentence that front-loads the verb and resource, uses a colon to list contents, and appends a clarifying parenthetical. Every clause earns its place with no redundancy.

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

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

For a zero-parameter tool with no output schema, the description adequately enumerates all return fields (fileName, current page, references, editor type/mode) and adds necessary context about editor modes. Minor ambiguity around 'all page references' prevents a perfect score.

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, so the description correctly omits parameter syntax. Per the rubric, a 0-parameter tool receives a baseline of 4, and no additional parameter details are needed.

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 'Return file metadata' and enumerates specific fields: fileName, current page, all page references, and editor type/mode. This clearly distinguishes it from sibling tools like get_document or get_node, which focus on document structure rather than file-level metadata.

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 the tool—when you need file metadata or editor context—but does not explicitly name alternatives or exclusions. The note about 'dev' and 'figjam' provides some interpretive context but stops short of guiding tool selection among siblings.

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

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

The readOnlyHint annotation covers safety, but the description adds meaningful context: the return structure, the significance of styleId, and the beta/editor limitation. This goes beyond the annotation and helps the agent understand the tool's behavior and constraints.

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 focused sentences: the first defines the tool's purpose, the second covers return format and caveats. Every word earns its place; no fluff or repetition.

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

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

No output schema exists, so the description fully compensates by describing the return object (styles array with styleId, name, description?, props?) and connects it to apply_animation_style. It also notes beta status and editor availability. For a simple no-parameter read-only tool, this is 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?

With zero parameters, the schema provides full coverage. Per the rubric, baseline is 4 for 0 params. The description adds value by explaining the output structure, although parameter guidance is unnecessary here.

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 verb 'List' and the resource 'Figma Motion animation-style presets', and differentiates from sibling tools like apply_animation_style by noting it returns the styleId used by that tool. This is specific and unambiguous.

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

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

It implies a clear workflow by stating these are 'the templates you apply with apply_animation_style' and adds a constraint ('only available in the Figma Design editor'). However, it does not explicitly list exclusions or alternative tools, so it's one step below fully explicit.

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?

Despite readOnlyHint being present, the description adds substantial behavioral detail: full recursive subtree, maximum fidelity, every serialized field listed, no depth limit, no deduplication, and the exact return shape ({ node }, null when not found). This goes well beyond the simple read-only annotation.

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, front-loaded with the primary action, followed by use cases, a distinctly named alternative, and return behavior. Every sentence earns its place with zero redundancy.

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 tool's high complexity (recursive subtree, fidelity, field types) and provides essential context for large trees, return format, and null behavior. No output schema exists, but the description sufficiently covers what the agent will receive.

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

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

Schema coverage is 100% (nodeId is fully described with type and URL fallback). The description adds no extra parameter-level semantics beyond stating 'by id', which is already implicit in the parameter name and schema. Baseline 3 applies.

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

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

The description uses a specific verb ('Return') with a clear resource ('one node by id') and explicitly distinguishes itself from get_design_context and other siblings by emphasizing 'full recursive subtree' with 'no depth limit' and 'no deduplication.'

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 states when to use this tool ('Best for inspecting a single component or a node you are about to modify') and provides a clear alternative for large trees ('prefer get_design_context'), including why (depth-limited, deduped, tokens resolved to names).

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 readOnlyHint annotation already signals safety, and the description adds useful edge-case context: returns motion: null for nodes without Motion, and playheadPosition only in the Design editor with an active timeline. This goes beyond the annotation without contradicting it.

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 densely pack purpose, timing, return shape, and edge cases without filler. The structure is logical: what it reads, when to call, what it returns, and when special fields appear. 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?

Despite no output schema, the description provides a concrete return structure and covers the two main edge cases (motion: null, conditional playheadPosition). For a single-parameter read tool, this is complete enough for an agent to invoke correctly 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?

The input schema already documents nodeId with 100% coverage, so the description adds little about the parameter itself. It repeats the return object shape including nodeId, but this is output semantics, not added input meaning. 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 reads a node's Figma Motion state and enumerates specific data components (animationStyles, animations, manualKeyframeTracks, timelines). It distinguishes itself from sibling mutation tools by framing this as the discovery/read operation, and its 'Call it before editing' guidance reinforces its role.

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 to call it before editing to discover styleIds, timelineIds, and existing keyframes. It also explains when the playheadPosition return is meaningful (when the user means 'here'). It doesn't name alternative tools, but the situational guidance 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond annotations by specifying that output preserves input order and missing ids yield null, which is not present in the schema or 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?

The description is concise at two sentences, with the primary action front-loaded. Every word adds value, and there is no redundant filler or repetition of schema 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 the tool's simplicity (one parameter, clear annotations), the description is complete. It covers input behavior (multiple ids), output behavior (order preservation, null slots), and the read-only nature is already annotated, making this a fully self-contained 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?

The input schema provides 100% coverage for the sole parameter nodeIds, with a clear description 'Figma node ids to fetch'. The tool description adds no additional semantic detail about parameter formatting, but the schema fully documents it, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns multiple Figma nodes by id, distinguishing it from the singular get_node tool. It also specifies behavioral details about output ordering and null handling, which further clarifies its purpose.

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 for batch node retrieval via 'multiple nodes by id', but it does not explicitly contrast with alternatives like get_node or mention when not to use this tool. Sibling tool names are given but not referenced in the description itself, so usage guidance is only implied.

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 adds context beyond the readOnlyHint annotation by scoping to the active Figma file and specifying the return fields (id and name). It doesn't mention handling of empty files or edge cases, but the read-only nature is already covered by 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, direct sentence that front-loads the verb and resource, with no filler. It is optimally concise and 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?

For a zero-parameter read-only listing tool, the description is nearly complete: it specifies the exact output fields (id and name). It lacks an explicit return format (e.g., array structure), but given the simplicity and annotation support, this is a minor gap.

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

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

The tool has zero parameters, so the input schema fully covers all inputs. The description reinforces that no arguments are needed, which is consistent with the empty schema.

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

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

The description clearly states the action (Return), the resource (every page in the active Figma file), and the exact data shape (id+name). This distinguishes it from sibling page tools like add_page, delete_page, or rename_page.

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: it returns all pages, so the use case is obvious. It does not explicitly name alternatives or exclusions, but the simplicity of the tool makes usage evident.

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 read-only nature is covered. The description adds the return structure but does not disclose additional behavioral traits such as error handling, permissions, or rate limits. While it provides value by explaining the output format, it does not go beyond the annotation's safety profile.

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, front-loaded with the core purpose and return format, and every sentence adds value. It avoids unnecessary detail and is well-structured for quick comprehension.

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

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

For a simple read-only tool with one parameter and no output schema, the description fully explains the return value structure and the concepts involved. It covers all necessary context without being verbose, making it complete for this tool's complexity.

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% for the single nodeId parameter, which already defines it as a Figma node id. The description mentions 'on a node' but does not add meaningful semantics beyond what the schema provides, so it meets the baseline for high coverage.

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 returns prototype reactions on a node, with a specific verb ('Return') and resource ('prototype reactions on a node'). It provides the return shape, which distinguishes it from sibling mutation tools like set_reactions and remove_reactions.

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 for reading reactions, but it does not explicitly state when to use it versus alternatives or mention exclusions. The read-only intent is clear from the verb, but there is no direct guidance on when to prefer this over other reaction-related 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 only declare readOnlyHint=true, but the description discloses extensive behavioral traits: auto-fit scaling behavior, scale caps at 2576px, batch size limits (20 nodes), total size caps (~2.4MB per frame), and handling of missing/recovered/empty nodes. This far exceeds what annotations provide and does not contradict them.

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?

Although lengthy, every sentence carries unique information about scaling, batching, edge cases, or alternatives. The description is front-loaded with the core purpose and output structure, then logically progresses through scale behavior, capacity limits, and recovery semantics without redundancy.

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 is remarkably complete: it specifies return format, scaling constraints, batch limitations, fallback behavior, and explicitly names alternatives. No output schema exists, so the description fully compensates by detailing the output shape and special flags, making the tool's behavior predictable in all mentioned scenarios.

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?

Despite 100% schema description coverage, the description adds significant nuance: 'scale applies to raster formats; when omitted, each node is auto-fitted', 'explicit scale is capped so the long edge stays within 2576px', and format defaults. It also explains the meaning of output fields like base64, recovered, and empty, enriching understanding 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 clearly states the tool's function: 'Export nodes as images the model can see' with a specific verb and resource. It also distinguishes itself from siblings by explicitly recommending 'save_screenshots' for full-res or batch needs, making the purpose 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 explicit usage guidance: 'use save_screenshots when you need a full-res file on disk' and 'or use save_screenshots for many nodes at once.' It also gives conditions like 'ask for fewer nodes when you need the detail' and explains when batch limits apply, offering clear when-to-use vs. alternatives.

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 readOnlyHint annotation already signals safety, but the description adds valuable behavioral context: the return structure, that nodes are full flat serializations without children, and the meaning of an empty array. This goes beyond what the annotation alone provides, though it does not describe potential error conditions or pagination, which are less relevant for a selection getter.

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 well-structured and concise: it opens with the core action, then explains the return format and node content, and closes with usage guidance and edge-case semantics. Every sentence contributes meaningful information without redundancy.

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

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

For a simple, parameterless, read-only tool with no output schema, the description is complete: it explains the output shape, the level of detail in nodes, the workflow relationship to other tools, and the empty-selection case. There is no missing information that would prevent an agent from using 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?

The tool has zero parameters, so the baseline is 4. The description reinforces this by calling it 'zero-argument' and provides no parameter details, which is appropriate since there are no parameters to document. The schema already fully covers the empty parameter set.

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

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

The description clearly states the tool's function: 'Return the current selection on the active Figma page' and specifies the exact output shape ({ pageId, pageName, nodes }). It distinguishes itself from siblings by noting it is the zero-argument 'what is the user looking at' call and explicitly points to get_design_context/get_node for deeper traversal.

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 provides explicit usage guidance: 'use it to identify the selected node ids (and page), then walk deeper with get_design_context or get_node.' This explains when to use this tool versus alternatives, and also clarifies the empty nodes array case, giving clear context for invocation.

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 readOnlyHint annotation already declares this as safe, and the description adds meaningful behavioral detail by specifying the structure of the returned data (grouping and per-style properties). It covers the primary behavior without contradicting the annotation.

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, front-loaded with the core purpose, and includes just enough detail to be useful. Every clause adds value without repetition or filler.

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

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

The tool is simple (no params, no output schema), and the description fully explains what is returned and how it is structured. There are no obvious gaps; the details provided are sufficient for an agent to understand the tool's 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?

This tool has zero parameters, so there is nothing to explain. The baseline for 0-parameter tools is 4, and the description appropriately focuses on the return structure rather than parameter usage.

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 ('Return') and a specific resource ('the document's local styles'), then enumerates the exact grouping ('paints, texts, effects, grids') and what each group carries. This clearly distinguishes it from sibling tools like get_motion_styles or style-mutation 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?

The description makes the context clear: if you need the document's local styles, this is the tool. It doesn't explicitly name alternatives or exclusions, but the scope is so specific that a user wouldn't confuse it with other style-related tools. No when-not guidance is given.

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, and the description adds context about the output format, including collections, modes, variables, resolvedType, and valuesByMode, which goes beyond the annotation.

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, efficient, and front-loads the main purpose while providing necessary detail about return types and special cases.

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?

Despite no output schema, the description fully specifies the return value structure, including aliases, RGBA colors, and easing curves, making it complete for a read-only tool with no parameters.

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

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

There are no parameters, so the description doesn't need to explain parameter semantics. The baseline of 4 applies.

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

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

The description clearly states the action ('Return') and the resource ('the document's local variables'), and details the output structure, distinguishing it from sibling tools that handle other resources or mutations.

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 the tool is for retrieving local variable definitions, but it does not explicitly state when to use it over alternatives or provide exclusions, like naming a sibling tool for different contexts.

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 readOnlyHint annotation already indicates a safe read operation. The description adds valuable behavioral context by specifying the return structure (center, zoom, bounds) and the meaning of zoom (1.0 = 100%). No contradiction exists, and the added detail goes beyond the annotation.

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, well-structured sentence. It front-loads the main action and return type, then provides clarifying details. No unnecessary words or repeated information from the schema or annotations.

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

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

For a simple tool with no parameters and no output schema, the description covers the essential behavior: what is returned and what each field signifies. The only minor gap is not specifying the coordinate system or reference frame for 'bounds', but this is a reasonable omission for a viewport getter.

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

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

The input schema has zero parameters, so there is nothing to document. The baseline for no-parameter tools is 4, and the description compensates by explaining the output semantics in detail, which is especially useful given that no output schema exists.

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 with a specific verb ('Return') and resource ('current page viewport'), and enumerates the exact return fields. This makes it easy to distinguish from sibling getters like get_selection or get_document, which target different aspects of the document state.

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

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

The description does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions. However, the purpose is self-evident as a read-only viewport query, so usage is implied. Absence of explicit sibling differentiation keeps this at a mid-range score.

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

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

Annotations already indicate this is a write operation (readOnlyHint=false) and not destructive. The description adds the return format and the non-empty list requirement, but does not disclose potential side effects such as reparenting or repositioning existing nodes. It provides some behavioral context beyond annotations but not extensive.

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 the purpose stated first and the requirement/return value second. There is no redundant phrasing, and it is well-structured for quick reading.

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

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

For a simple mutation tool with full schema coverage and annotations, the description covers purpose, a usage constraint, and the return value. It lacks details about error conditions or the effect on the original nodes, but these are not critical for basic understanding. Overall, it provides sufficient context for an agent to select and invoke the 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 descriptions cover both name and nodeIds, giving a baseline of 3. The tool description adds the constraint that nodeIds must be a non-empty list, which is not present in the schema. It does not further explain the name parameter beyond the schema, so the added value is moderate.

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 uses the verb 'Group' with the resource 'nodes under their shared parent', clearly indicating the action and scope. It also mentions the return value for the new group, which distinguishes it from sibling tools like ungroup_nodes and move_nodes.

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 from its purpose and the requirement that nodeIds be non-empty, but it does not explicitly state when to use this tool versus alternatives like reparent_nodes or move_nodes. No exclusionary guidance is provided, so the usage context is only implied.

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

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

The description discloses extensive behavioral details beyond the readOnlyHint annotation: gitignore-aware scanning, name-based and near-exact matching, fallthrough on uncertainty, color contract extraction (currentColor/fixed/multi-color), recolor guidance, importHint variants, and the fact that it does not fabricate import lines. This far exceeds the annotation's minimal information.

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