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

Annotations declare readOnlyHint and openWorldHint, but the description adds meaningful behavioral details: 'Page loading is bounded; a page-scoped failure returns its structured error directly and successful reads include `coverage`.' This goes beyond the annotation and informs the agent about edge cases and return characteristics.

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

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

Three sentences, each serving a distinct purpose: scope, parameter constraints, and behavioral edge cases. The description is front-loaded with the core action and is free of 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 simplicity (3 params, output schema exists), the description covers all essential aspects: the resource being read, the parameter exclusivity, optional categories, and potential partial failure behavior. No important gaps remain.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description reinforces the mutual exclusivity and default for includeCategories but adds no new semantic details beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description opens with 'Read the native annotations on a page or node (and subtree)', which is a specific verb and resource. It clearly distinguishes this read tool from the sibling write tool annotation_set and other list-style tools like style_list or variable_list.

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 the core usage rule ('exactly one of pageId or nodeId is required') and mentions the includeCategories toggle. While it doesn't explicitly say when not to use it, the read-only intent and sibling set (annotation_set for writing) imply appropriate usage clearly.

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 richly discloses non-idempotency, partial mutation semantics, possible false failures, and validation steps, going far beyond the openWorldHint annotation. This is exemplary behavioral transparency.

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 convey the core purpose and critical operational warnings without filler. Every clause adds value, and the warning about non-idempotency is essential to safe use.

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 batch, non-idempotent nature and the presence of an output schema, the description covers operational pitfalls, error handling, and verification workflow. It is complete enough without explaining return values.

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

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

Schema coverage is 100% with detailed descriptions for the annotations array, including the properties enum and nodeName requirement. The description itself adds no additional parameter-level 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 states 'Append native annotations to one or more nodes in a batched call' – a specific verb and resource. It clearly distinguishes from sibling annotation_list and other node-related tools.

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

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

It provides actionable guidance on handling partial_success and explicitly instructs to call annotation_list before retrying non-success items to avoid duplicates. However, it does not broadly state when to use this tool vs alternatives beyond this retry scenario.

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 that joining a channel establishes a live connection, which is a behavioral trait beyond the idempotent and open-world hints already provided in annotations. It adds useful context about the connection side effect without contradicting 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?

The description is a single, focused sentence that places the action first and states the purpose without any wasteful words or redundant information.

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

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

For a low-complexity tool with a single parameter, an output schema, and informative annotations, the description provides sufficient context about the tool's purpose and effect. It lacks explicit preconditions or examples, but the combination of schema and annotations fills that gap.

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

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

The input schema already fully describes the single 'channel' parameter with a clear description, and schema coverage is 100%. The tool description adds no extra semantic detail beyond what the schema provides, so a 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 uses the specific verb 'Join' and identifies the resource 'plugin channel', with a clear outcome of establishing a live connection to the Figma document. This clearly distinguishes it from sibling tools focused on node operations and 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 a clear context for use: when a live connection to the Figma document via a plugin channel is needed. It does not explicitly state exclusions or alternatives, but since no sibling tool handles channels, the usage context 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 already declare destructiveHint, idempotentHint, and openWorldHint; the description adds meaningful context by stating that the removal propagates to every instance and that it applies to main components or variant sets. It does not contradict the annotations and provides extra side-effect awareness beyond the structured annotations.

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

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

The description is a single, well-structured sentence that front-loads the action, target, and consequence. It contains no filler or redundancy, earning its place entirely.

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 captures the core purpose, the allowed node types, and the propagation effect. Given that the schema covers parameters and an output schema exists, the description is sufficiently complete for correct tool selection and invocation. It does not mention error cases or prerequisites, but openWorldHint and the existing schema make those less critical.

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 all three parameters, so the schema already explains nodeId, nodeName, and propertyName with adequate detail. The tool description does not add parameter-specific guidance, but it does not need to since the schema covers the semantics.

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 ('Remove a component-property definition'), a clear target ('from a main component or variant set'), and a notable effect ('propagates to every instance'). This clearly distinguishes it from sibling tools like component_manage_property, which focuses on property management, and from delete tools for 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 when to use the tool (when removing a property definition) and notes the propagation consequence, but it does not explicitly name alternatives or when-not-to-use conditions. The sibling list suggests component_manage_property as the related management tool, but the description does not reference 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?

Annotations already establish read-only and open-world behavior, but the description adds valuable context: document scans report failures via a 'coverage' field, while page-scoped scans return structured errors directly. This explains edge-case behavior beyond what the 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 only two sentences long. The first sentence states the core purpose and capabilities; the second provides a concise behavioral nuance about error handling. Every phrase earns its place with 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?

The tool is straightforward with optional parameters, and an output schema exists so return values are documented there. The description explains the key difference between document and page scope error behavior, which is essential for correct usage. It lacks nothing critical for an AI agent to invoke it properly.

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 parameter descriptions, so the description is not required to repeat them. It does reference 'filtering and scope options' generically, which aligns with the schema but adds no new detail. Given the schema coverage, a 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 opens with a clear verb and resource: 'List components in the document.' It explicitly mentions filtering and scope options, and the additional detail about failure reporting distinguishes it from generic list tools. This leaves no ambiguity about what the tool does.

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

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

The description states the primary use case (listing components) and even distinguishes between document and page scope behaviors. It does not explicitly name alternative tools or say when not to use it, but the resource is so specific that confusion with sibling list tools (style_list, variable_list) is unlikely.

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 clarifies the mutating scope ('main component or variant set') and the property types supported, and directs deletion elsewhere. With openWorldHint as the only annotation, this adds useful safety and scope context, though it does not detail side effects on instances or permission requirements.

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-loaded with the action and resource, followed by a single purposeful pointer to the deletion sibling. No filler or redundant 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?

Given the rich input schema and output schema, the description provides the essential scope (main component/variant set) and deletion alternative. It doesn't explain return value or prereqs, but those are covered by structured fields, making this adequate for a complex tool.

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

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

Schema description coverage is 100%, so the schema fully documents all 9 parameters. The description repeats type names (BOOLEAN/TEXT/INSTANCE_SWAP) and target concept already in nodeId/nodeName descriptions, adding no extra semantic value 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 uses a specific verb phrase 'Add or edit' and clearly identifies the resource as 'component-property definition' on 'main component or variant set', with allowed types enumerated. It distinguishes itself from the deletion counterpart by naming component_delete_property, and from sibling tools like instance_set_property by specifying the target 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 that deleting is handled by component_delete_property, giving a clear exclusion. It does not discuss when to choose ADD vs EDIT, but the schema and parameter descriptions cover that. Overall it provides clear context without naming all sibling 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 description discloses that the tool transforms a frame into a main component, but it does not detail side effects or prerequisites (e.g., that the frame is modified in place, or that nodeName must match exactly). The annotation openWorldHint is present, but the description adds minimal context beyond that; 'convert' implies a state change, yet the potential destructive nature is not clarified.

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 with no filler. It efficiently conveys the tool's purpose and earns its place 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 tool is simple, and the schema covers parameter details while an output schema exists (likely describing the created component). The description is sufficient for the core action, though it could mention the need to fetch nodeName via node_info, but that is already captured in the schema, so the description remains complete enough.

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 parameters (nodeId and nodeName) are fully described in the input schema, including the requirement that nodeName be passed verbatim from node_info. The description itself adds no parameter information, which is acceptable given the schema's completeness.

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 'Convert an existing frame into a main component' clearly states the action (convert), the resource (existing frame), and the result (main component). It distinguishes this tool from siblings like create_instance (which creates an instance) and create_component_set (which creates a set).

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 there is an existing frame to convert, but it does not explicitly mention when not to use it or provide alternatives. Sibling tool names suggest related tools, but no direct comparison is made, so 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?

Annotations include only openWorldHint: true, which does not capture safety or side effects. The description states 'Combine components into a component set' but does not disclose that the operation may mutate the source components, alter their parent container, or require specific permissions. This leaves the agent without critical behavioral context for a create/mutation operation.

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

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

The description is a single concise sentence of 11 words that captures the core action and key distinguishing detail. No unnecessary words; structurally ideal.

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 complete parameter schema, existing output schema, and an annotation, the description is adequate but not fully complete. It omits clarifying how propertyValues map positionally to properties (though schema hints at this) and does not explain the practical effect on the component set's parent hierarchy. However, the overall context from schema is strong.

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 each parameter having a descriptive comment (e.g., parentId explains it is an appendable container and references node_info). The description itself adds no additional parameter semantics, so the baseline score 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 uses the active verb 'Combine' and specifically names the resource 'component set (variants) with property definitions,' making it clear what the tool accomplishes. It differentiates from sibling tools like create_component and create_instance by its focus on combining multiple components into a set.

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 mention when to use this tool versus alternatives such as create_component or component_manage_property. It implies that it is used when existing components need to be combined into a set, but provides no explicit exclusions or alternative suggestions.

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 only states that it creates a frame, but does not disclose behavioral traits beyond the act of creation. With only openWorldHint annotation and no readOnly/destructive hints, the description fails to mention side effects (e.g., modifying the parent, potential error conditions, irreversibility). No contradiction with annotations.

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

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

A single, front-loaded sentence that is concise and free of redundancy. It conveys the core purpose without 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?

Given the tool's complexity (21 params, nested objects, output schema), the description is minimal but adequate because the schema covers parameters and an output schema exists. However, it omits useful context such as the requirement for parentNodeName to match exactly and that auto-layout settings are only relevant when layoutMode is set, which would aid correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal grouping ('optional fill/stroke and full auto-layout configuration') which maps to params like fillColor, strokeColor, and layoutMode, but does not add significant 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 uses a specific verb ('Create') and resource ('frame') and adds clarifying details ('container with optional fill/stroke and full auto-layout configuration'). This clearly distinguishes it from sibling tools like create_shape, create_text, and create_component_set.

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

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

The description clarifies the tool's purpose as creating a frame/container with auto-layout, implying use for layout containers rather than shapes or text. It does not explicitly mention alternatives or when-not-to-use, but the context is clear enough for 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 description adds no behavioral context beyond the openWorldHint annotation. It doesn't mention side effects, prerequisites (e.g., existing component), or the outcome on the parent node. The annotation already signals open-world behavior, but the description fails to enrich that signal.

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

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

The description is a single, clear sentence with no wasted words. It front-loads the core action and is appropriately sized for a simple tool.

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 complete schema coverage and an output schema, the description is too thin to fully contextualize the tool's role. It doesn't explain the effect on the node tree, the difference between componentKey and componentId, or how it relates to sibling creation tools. This is sparse for a 6-parameter 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, so a baseline of 3 is appropriate. The description only names componentKey and componentId without adding meaning beyond the schema, leaving the schema to carry the full semantic load.

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 action ('Instantiate'), the resource ('a component'), and the method ('by componentKey or componentId') along with a position. This distinguishes it from sibling tools like create_component, which create new component definitions rather than placing instances.

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 place a component instance—but it does not explicitly state when to use this tool over alternatives or mention any exclusions. The distinction from create_component is implied by the word 'instantiate' but not spelled out.

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

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

With only openWorldHint=true in annotations, the description takes on substantial behavioral disclosure. It explains that shape-specific params are validated by `type`, clarifies pointCount semantics (sides vs points), and explicitly notes the 'no even-parity rule'—useful nuance not present in structured metadata.

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

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

The description is two sentences with no filler, front-loads the primary action, and uses inline code for parameter names. The second sentence adds critical nuance about shape-specific validation and pointCount semantics without bloat.

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 14-parameter creation tool with a rich schema and output schema, the description covers the central type-dispatch behavior and key parameter constraints. It does not repeat every parameter (schema covers those) but provides the high-level overview and crucial pointCount clarification needed 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 already describes all 14 parameters (100% coverage), so the baseline is 3. The description adds value beyond the schema by grouping arcData, pointCount, and innerRadius as shape-specific and validated by `type`, and by clarifying pointCount's native-count meaning and the absence of an even-parity rule.

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 ('Create') and explicitly enumerates the four shape types ('rectangle, ellipse, polygon, or star') via `type`, which clearly distinguishes it from sibling creation tools. It also specifies position/size and optional colors, giving a precise 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 provides clear context for when to use this tool by naming the exact shape types it supports. However, it does not explicitly mention alternatives or exclusion criteria, though the type enumeration makes the intended use fairly 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?

The description is minimal and adds no behavioral context beyond the action itself. It doesn't disclose side effects, such as whether the SVG is parsed, whether existing nodes are affected, or any validation rules. The only annotation is openWorldHint, which is not enriched by the description. For a create operation, the mutation is obvious, but other behavioral traits remain opaque.

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, clear sentence with no wasted words. It directly states the core action and object. This is appropriately concise for a tool with rich schema coverage, earning full marks for structure.

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 six parameters and no nested objects, the description is insufficiently complete. It lacks context on when to use this tool, the significance of the required parentId and parentNodeName, and any potential side effects. While the schema and output schema cover technical details, the description fails to provide essential usage context, making the overall description incomplete.

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 provides full descriptions for all six parameters, including parentNodeName's 'passed back verbatim from node_info.' With 100% schema coverage, the description adds no additional parameter meaning. Baseline of 3 is appropriate because the schema carries the semantic weight, and the description offers no extra clarification.

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: 'Create a node from an SVG markup string.' This uses a specific verb ('Create') and resource ('node from SVG'), and distinguishes it from sibling tools like create_shape, create_text, and create_component, which create different node types. The title reinforces this, making the action 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 offers no guidance on when to use this tool versus alternatives. It doesn't mention that this is for SVG-based nodes or provide any context about prerequisites (e.g., needing an SVG string). Common usage can be inferred from the name and schema, but no explicit or implied usage scenarios or exclusions are 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?

With only an openWorldHint annotation and no readOnly or destructive hints, the description carries the transparency burden. It simply states the action and styling options, without disclosing side effects, required parent context, or behavior on invalid input. The openWorldHint is not elaborated.

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, focused sentence that front-loads the verb and object. No wasted words, perfectly sized for the 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?

Given the tool's 9 parameters, nested fontColor object, and openWorldHint, the one-sentence description is fairly sparse. It omits mention of the parent requirement (though present in schema) and potential side effects. However, the rich schema and presence of an output schema reduce the burden, so a mid-range score is appropriate.

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 100% coverage with descriptions for all 9 parameters. The description adds minimal value by grouping 'font size/weight/color' but doesn't introduce any parameter meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Create') and resource ('a text node') and names the key styling options (font size/weight/color). This clearly distinguishes it from sibling creation tools like create_shape or create_frame.

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 no guidance on when to use this tool versus alternatives such as text_set_content or text_set_style. It also omits prerequisites like obtaining parentNodeName from node_info, which is only mentioned in the schema, not in the description.

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

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

The readOnlyHint annotation already covers safety, and the description adds scoping ('from a source instance') and purpose ('to later apply them'), which is useful but not rich. It does not disclose additional behaviors like return format or side effects, but the output schema and readOnlyHint mitigate the need.

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 clear sentence, front-loaded with the action verb 'Read'. No wasted words; every element 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?

For a simple read tool with one parameter, full schema coverage, readOnly and openWorld hints, and an output schema, the description provides enough context. It explains the tool's purpose and the source instance, while the structured fields handle return values and parameter details.

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 a full description for nodeId ('The ID of the component instance to get overrides from'), so the baseline is 3. The tool description's 'source instance' echoes the schema without adding significant new meaning.

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

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

The description uses a specific verb ('Read') and resource ('override properties from a source instance'), clearly distinguishing it from generic read tools like node_info and its counterpart instance_set_overrides. The stated purpose ('to later apply them to other instances') adds context that reinforces the tool's role in copying overrides.

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

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

The description clearly conveys when to use the tool: when you need to read override properties from a source instance to apply elsewhere. It does not explicitly mention alternatives or exclusions, but the context is unambiguous and the sibling tool instance_set_overrides is implicitly contrasted.

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 provides critical behavioral details beyond the annotations (openWorldHint, idempotentHint) by defining how to handle 'partial_success' status: report failed/skipped items and retry all non-success items. This is valuable operational transparency that the agent would otherwise not know.

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 action and followed by a crucial conditional instruction. Every word earns its place, with no redundancy or unnecessary elaboration.

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 full schema coverage, an output schema, and the presence of annotations, the description is complete. It explains the core operation, the swapping behavior, and the critical partial-failure handling, leaving no significant gaps for the 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 input schema provides complete descriptions for both parameters (sourceInstanceId and targetNodes, including nodeId and nodeName with their expected values). The description does not add new parameter-level details, but it reinforces the workflow by mentioning 'targets' and 'source component', which aligns with 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 states a specific action ('Apply previously-read overrides') and identifies the target resource ('target instances') plus the mechanism ('targets are swapped to the source component and all overrides applied'). It clearly distinguishes from sibling tools like instance_set_property, which applies a single property override, by emphasizing the batch application of overrides.

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

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

The phrase 'previously-read overrides' implies the tool is used after reading overrides, providing clear context. The description also specifies what happens during the operation (swap and apply), but it doesn't explicitly state when not to use it or name alternatives. However, the context is sufficiently clear for an agent.

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 idempotentHint=true, so the safety profile is covered. The description adds the four property-value categories but does not disclose that setting replaces existing values or that INSTANCE_SWAP requires a stable component key (the latter appears in schema). No 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?

Single sentence, front-loaded with verb and object, and each clause adds meaning. No filler or redundant restatement.

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 full schema descriptions, an output schema, and idempotence annotation, the concise description suffices for a single-property mutation. It lacks explicit cross-reference to `instance_set_overrides`, but that is a usage-guideline gap, not a completeness failure.

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 descriptions for all four parameters, including the exact `nodeName` requirement and `value` constraint for INSTANCE_SWAP. The description's category list (boolean toggle, text override, etc.) adds semantic grouping but no additional parameter-level syntax. 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 ('Set') and resource ('instance'), plus scope ('one property'), and enumerates property categories. It distinguishes from sibling `instance_set_overrides` by emphasizing single-property scope. Clear and actionable.

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 single-property usage but never states when to prefer this over `instance_set_overrides` or how to discover valid property names. No exclusions or alternative tools are mentioned. This is minimal 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 include idempotentHint and openWorldHint but no destructive/read-only flags. The description clarifies the action as 'link' but doesn't disclose side effects such as whether existing styles are replaced or what happens if the styleId is invalid. It adds some context beyond annotations but lacks deeper behavioral detail.

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 verb and action, and the second sentence offers direct, useful alternative guidance. There is no wasted wording.

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

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

With a fully described schema, an output schema, and annotations, the description covers purpose and usage well. The only minor issue is a slight mismatch between the description's 'paint' and the enum splitting FILL/STROKE, but overall an agent has enough to select and invoke this 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 already describes all 4 parameters with 100% coverage, so the baseline is 3. The description adds minimal extra meaning, mainly emphasizing styleId and the distinction from node_set_* setters, but does not introduce details absent 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?

The description clearly states the tool links a node to a shared library style by styleId, listing the style types in parentheses. It explicitly distinguishes from the node_set_* setters by noting those are for ad-hoc values, so it effectively separates itself from sibling tools.

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

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

The description provides explicit guidance: use this tool for shared library styles, and use node_set_* setters for ad-hoc values not backed by a style. This covers primary use case and an alternative, satisfying the 'when and when-not' criterion.

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 supply idempotentHint and openWorldHint, but the description adds behavioral nuance beyond those: the design-token tracking semantic and the ordering constraints that affect outcomes. It does not contradict annotations. A slight gap is that it doesn't mention potential side effects of setting explicit variable modes, but the value added is solid.

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

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

Three sentences, each earning its place: functionality, usage guidance, and ordering rules. No redundancy or fluff; front-loaded with the core 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?

Given the tool's complexity (nested objects, 4 params, output schema present), the description covers purpose, usage distinction, and ordering constraints. The schema handles parameter details, and annotations handle idempotency/open-world semantics, leaving 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?

Schema description coverage is 100%, with each parameter already described in detail. The description adds a high-level reason for binding ('track a design token') but doesn't provide additional parameter-level semantics beyond what the schema already covers. 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 binds a variable to a node property or sets an explicit variable mode, with a specific verb and resource. It distinguishes itself from sibling tools like node_set_fill by noting it should be used 'instead of a literal `node_set_*`' when tracking design tokens.

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

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

Provides explicit guidance on when to use this tool versus alternatives: 'Use instead of a literal `node_set_*` when the value should track a design token.' It also gives ordering rules (set auto-layout before binding padding/spacing, set solid fill before binding colour token), which contextualizes 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?

The description discloses the key behavioral trait: it duplicates a node and produces a new id, with optional repositioning. It does not contradict the openWorldHint annotation and adds context about the result. However, it does not elaborate on side effects or preconditions, but the core behavior is transparent.

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

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

The description is two concise sentences, front-loads the action, and contains no extraneous information. Every word 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 relatively simple clone operation, the description covers the essential behavior. The presence of an output schema and full parameter schema reduces the burden. It lacks explicit prerequisites, but the schema's mention of node_info hints at the workflow, making it 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?

The input schema covers all 4 parameters with descriptions, including the notable detail that nodeName must be passed back verbatim from node_info. The description adds no additional parameter semantics beyond the schema, 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 uses a specific verb 'Duplicate' and identifies the resource 'existing node', clearly distinguishing it from sibling tools like node_rename or node_delete. It also states the outcome (produces a new node id), 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 clearly implies when to use this tool—when an existing node needs to be duplicated—and differentiates from creation tools by specifying 'existing node'. However, it does not explicitly exclude alternatives or mention when not to use it, but the context is clear enough.

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 beyond annotations by disclosing 'No API undo,' per-item validation (which implies possible partial success), and specific retry semantics. These details complement the destructiveHint and idempotentHint annotations without contradiction, adding significant 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, each purposeful: core function, warning about undo, and failure-handling instructions. It is front-loaded and extremely concise with 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 annotations covering idempotency and destructiveness, and an output schema presumably explaining return values, the description thoroughly covers batching, validation, and partial-success handling. It is complete for a delete operation with 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?

Schema coverage is 100% (nodeId and nodeName are well-described), so the baseline is 3. The description does not add parameter-specific syntax or format details, but the 'per-item-validated' phrasing hints at how the nodes array is processed, which is marginal added value over 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 'Delete one or more nodes in a single batched, per-item-validated call,' which specifies the verb (delete), resource (nodes), and distinguishes the tool by its batched and per-item-validated nature. This is precise and leaves no ambiguity about what the tool does.

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

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

It provides clear usage context: a batched deletion with no API undo, and explicitly instructs how to handle partial_success responses (report failed/skipped items and retry them). However, it does not name alternative tools or exclusion cases, though no direct sibling alternative for node deletion exists in the list.

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 output behavior in detail: SVG returns raw XML in 'svg', while PNG/JPG/PDF return base64 in 'imageData', and PDF is noted as a delivery artifact. This adds significant value and no contradictions with annotations.

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

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

The description is two sentences with no redundant wording. It front-loads the core purpose and then adds essential output format details, earning a perfect score.

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 (3 params, output schema present), the description covers all necessary context: read-only nature, use case, return format, and caveats like PDF. It 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?

Schema description coverage is 100%, so the schema already documents all parameters. The description mentions 'scale' and formats but does not add new parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb 'Render' with a clear resource 'a node to an image' and lists the supported formats. It distinguishes itself from sibling tools by being the visual export/capture tool, especially with 'canonical way to visually verify edits.'

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 the tool ('canonical way to visually verify edits') and provides format selection guidance ('prefer PNG/SVG for inspection'). It does not explicitly name alternative tools or say when not to use it, but the context is clear enough.

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 and openWorldHint, but the description expands on this with 'Lossy — original structure is not recoverable', explicitly informing the irreversibility of the operation. This adds meaningful behavioral context beyond the structured hints.

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 short sentences with no unnecessary wording. It front-loads the action and follows with a key caveat, achieving maximum clarity in minimal space.

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 2-parameter tool with an output schema and declarative annotations, the description covers the essential purpose and caution. It does not mention prerequisites like the nodeName must match node_info, but the schema covers that. Overall, it is sufficient given the available structured information.

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 provides 100% description coverage for both parameters, so the tool description does not need to explain them. The description adds no additional parameter semantics beyond what is already 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 clearly states the specific verb 'Flatten' and the resource 'a node and its children', with the result 'a single vector'. This directly conveys the tool's function and distinguishes it from sibling tools like node_ungroup or node_transform.

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 no guidance on when to use this tool versus alternatives. It only warns that the operation is lossy, but does not mention scenarios where flattening is appropriate or when another tool should be chosen instead.

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 only says 'wrap' with no detail about side effects such as nodes being reparented, the group insertion order, or failure modes if the provided nodeName does not match. The openWorldHint annotation warns of unknown effects but does not compensate for the lack of disclosed known behaviors.

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 with no filler, directly stating the operation. It is appropriately concise for a simple tool.

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 omits critical operational context for a mutation tool: the requirement that nodeName must exactly match the current node name, the reparenting behavior, and any constraints on nodes. The schema covers parameter semantics but not the overall behavioral contract, leaving the agent under-informed.

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 parameters already well-documented (e.g., name rejects empty strings, nodeName must be passed verbatim). The tool description adds no parameter-specific information, so the baseline score 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 uses a specific verb ('wrap') and clear resource ('multiple nodes' into a 'new group node'). It clearly distinguishes the tool from siblings like node_ungroup and node_clone by stating exactly the grouping 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 no explicit guidance on when to use grouping versus alternatives, no prerequisites (e.g., nodes sharing the same parent, exact node names), and no exclusions. The action is implied by the tool name but the description itself does not give contextual direction.

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

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

Annotations already declare readOnlyHint and openWorldHint, but the description adds significant behavioral detail beyond that: it discloses recursive subtree traversal, that only requested properties are returned, that resolved boundVariables/explicitVariableModes are included, and precisely how failed pages are reported (pageFailedNodes and coverage.pageErrors). This enriches the agent's understanding of the tool's edge cases and return structure.

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 tightly written, leading with the core action and then delivering essential details in a logical order. Each sentence adds value: the first defines scope, the second explains the return format, the third covers error handling, and the final sentence provides usage guidance. No filler or redundant 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?

Given the tool's complexity (5 optional parameters, no required ones, output schema present), the description covers the essential contextual aspects: what it operates on, how parameters influence traversal, how partial failures are surfaced, and when to use it. The output schema already handles return value details, so the description's focus on behaviors and edge cases makes it 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?

The input schema already provides 100% description coverage for all five parameters, so the baseline is 3. The description mentions `properties`, `filter`, and `maxDepth` but does not add syntax or format details beyond the schema. The reference to 'resolved boundVariables/explicitVariableModes' relates to output rather than parameter semantics, so the description does not meaningfully elevate parameter 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 uses a specific verb ('Read') and resource ('one or more nodes'), and clearly distinguishes this from sibling tools by calling it 'The workhorse read; start here before any write.' It also outlines key features (properties selection, filter, maxDepth) and return behavior, leaving no ambiguity about what the tool does.

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

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

The description provides clear usage context: 'start here before any write' indicates this is the primary read tool, separating it from write operations. It does not explicitly name alternative tools (e.g., page_info) or state when not to use it, but the 'workhorse' framing strongly implies it as the default read choice.

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 behavioral details about index validation and default append behavior. The annotations (openWorldHint, idempotentHint) already hint at side effects, but the description does not elaborate on what happens to the old parent or other consequences. No contradiction with annotations.

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

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

The description is concise, consisting of three short sentences. It is front-loaded with the primary action and provides necessary index guidance without any redundant phrasing.

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 rich schema (100% coverage), output schema, and annotations, the description is adequate for a straightforward reparent operation. It could mention edge-case restrictions (e.g., cannot reparent to itself or a descendant), but such details are not essential for typical use and are not indicated by the structured data.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description only reiterates the index behavior already present in the schema, providing no additional parameter semantics beyond what is structured.

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 'Reparent a node' with a specific resource (node) and optional index. This distinguishes it from sibling node tools like rename, delete, clone, and group by focusing on the parent-child relationship.

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 the tool (reparenting) and how to use the index parameter (valid range, omit to append). However, it does not explicitly mention alternatives or conditions when not to use this tool, so it falls short of fully explicit usage guidelines.

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 convey idempotency and open-world context. The description adds that the tool sets the name to an exact value, implying an overwrite behavior, but does not disclose potential side effects or failure modes. The schema's note on empty names adds context, but it is outside the description.

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: 'Rename a node (sets `name` to an exact value).' It is front-loaded with the action, contains zero filler, and effectively communicates the core function.

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 three clearly documented parameters and an output schema present. The description covers the essential action and the schema covers parameter details, so the description is sufficiently complete for this low-complexity operation. Missing explicit usage guidance is the only minor gap.

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

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

The input schema provides 100% coverage with descriptions for all parameters, including a detailed note about the `name` parameter rejecting empty strings. The tool description itself does not add parameter semantics beyond what the schema and the exact-value phrase already provide, so the schema carries the burden.

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 'Rename a node' with the specific verb 'rename' and resource 'node', and clarifies it sets `name` to an exact value. This unambiguously identifies the tool's function and differentiates it from sibling tools that manipulate other node properties (e.g., node_set_fill, node_set_stroke).

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 renaming nodes but does not explicitly state when to use it over alternatives or mention any exclusions. The purpose is clear enough that an agent can infer when to use it, but there is no explicit guidance on alternatives or 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 already declare idempotentHint=true, covering replay safety, and openWorldHint=true, allowing for undiscovered fields. The description adds no behavioral context beyond saying it's a setter. It doesn't disclose side effects like whether unspecified properties are reset, but the schema's conditional notes (e.g., itemSpacing ignored with SPACE_BETWEEN) are present in structured fields, so the bar is lower. No contradiction found.

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 exactly one sentence, front-loaded with the verb and resource, and every word adds value. 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?

Given high complexity (14 parameters, 6 enums) and the presence of an output schema, the description need not enumerate return details. The schema's property descriptions fully cover parameter semantics, so the minimal description is adequate. However, it could have mentioned that unspecified properties are left unchanged, but the schema's additionalProperties false and idempotent hint partially cover this. Overall complete enough.

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 each parameter having detailed descriptions, including enum values and conditional behavior (e.g., counterAxisSpacing only with WRAP). The tool description itself only lists high-level categories (padding, spacing, etc.) without adding syntax or parameter-specific meaning. Baseline 3 is appropriate as the schema carries the full burden.

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 'configure' and resource 'a frame's auto-layout', listing specific aspects (mode, padding, spacing, alignment, sizing). This distinguishes it from sibling tools that handle fills, strokes, effects, etc. The phrase 'in one unified setter' further differentiates it as a single combined operation.

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 scopes usage to frames and auto-layout configuration, making it clear when to apply. It does not explicitly list exclusions or alternatives, but the context is unambiguous enough that an agent can infer it is the dedicated auto-layout setter, especially given the sibling set includes no competing auto-layout 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 provide idempotentHint and openWorldHint, covering the safety profile. The description adds minimal behavioral context beyond 'uniform or per-corner', which is more about parameter semantics than behavior. It does not disclose side effects, edge cases, or why openWorldHint is set.

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, front-loaded with verb and resource. It conveys the essential capability without 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 the rich schema, output schema, and annotations, the description is largely complete. It explains the tool's purpose and modes, but omits potential constraints like supported node types or why nodeName is required, though those are partially covered in schema descriptions.

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 baseline is 3. The description adds value by framing the operation as uniform or per-corner, helping the agent understand the optional corners parameter and its purpose. This conceptual distinction enhances the schema descriptions.

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

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

The description uses specific verb 'Set' and resource 'node's corner radius', clearly distinguishing from sibling node_* property setters. It also specifies the two modes (uniform or per-corner), which uniquely identifies the tool'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?

The description implies usage for modifying corner radius but does not explicitly state when to use it vs alternatives like node_set_fill or node_set_stroke. No exclusions, supported node types, or alternative tool references are provided, leaving usage to be inferred from the name and sibling context.

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 provide idempotentHint and openWorldHint, and the description adds scope ('shadows, blurs'). However, it does not explicitly state that the effect array is replaced wholesale, nor does it mention preconditions or failure modes. The 'set' verb implies replacement, but the description remains minimal on behavioral detail.

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 succinct, front-loaded sentences with zero filler. The first sentence states the tool's action and scope; the second gives an explicit alternative. Every word earns its place.

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

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

Given the very rich input schema and the presence of an output schema, the description covers core purpose and usage guidance without redundant details. The only minor gap is not explicitly noting that existing effects are overwritten, though this is strongly implied by the verb 'set'.

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 exhaustive descriptions for all three parameters, including nested effect variants, defaults, and constraints (100% coverage). The description adds no extra parameter-level information, so the baseline score 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 uses a specific verb ('Set') and clearly identifies the target resource ('a node's effect array') and scope ('shadows, blurs'). It also distinguishes this tool from siblings by explicitly naming node_apply_style as the alternative for shared 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 provides explicit when-to-use guidance: use this tool for direct effect arrays, and points to node_apply_style as the alternative for shared styles. This clear exclusion and alternative naming makes tool selection straightforward.

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 clarifies that this sets a literal fill rather than a style reference or token binding, which is behavioral context beyond the idempotentHint and openWorldHint annotations. It does not disclose overwriting semantics or error conditions, so not a 5.

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, directly states the purpose and alternatives, with no redundancy. The description is front-loaded and every word 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 complex tool with nested image object and multiple modes, the description-plus-schema provides a complete picture. The description supplies the key decision point (literal vs style vs token), while the schema covers technical details and constraints. Minor gap: no mention of node type restrictions or potential errors, but these aren't essential given the schema.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters. The description adds a high-level summary of the three modes (color/image/clear) but no additional parameter-specific details beyond what the schema already 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 the tool sets a node's fill to a literal RGBA color, an image, or clears it. It explicitly distinguishes from alternatives (node_apply_style, node_bind_variable), making the purpose 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?

The description provides explicit guidance: use this for literal fills, and directs the agent to node_apply_style for shared styles and node_bind_variable for color tokens. This covers when to use and when-not-to-use scenarios.

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 a useful behavioral nuance ('supports uniform or per-side weights') beyond what annotations provide. However, it does not disclose details like replacing existing strokes, the nodeName verification requirement, or how parameters interact (e.g., whether side weights override uniform weight). Annotations indicate idempotentHint, so safety is partially covered, but the description remains thin on other behavioral aspects.

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 with no wasted words. It conveys the core action, target, and key mode distinction in 13 words, achieving maximum efficiency and readability.

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 full schema coverage, output schema, and annotations, the description is adequately complete for a setter tool. It tells the agent what the tool does and the primary decision (uniform vs per-side weights). It doesn't explicitly note that weight is optional or that nodeName serves as a consistency check, but those are covered by the schema and output schema, so the description fills its intended role.

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 baseline is 3. The description adds meaningful semantic grouping by distinguishing 'uniform' (the `weight` parameter) from 'per-side' (the stroke*Weight parameters), clarifying how to choose between them. This goes beyond the individual schema descriptions and helps the agent select the right parameters for the desired outcome.

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 ('Set') and the resource ('a node's stroke color and weight'), which is specific and distinguishes it from sibling tools like node_set_fill or node_set_corner_radius. The mention of 'uniform or per-side weights' adds further specificity, making it unambiguous.

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

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

The description provides clear context: it is the tool for setting stroke properties on a node. Although it doesn't explicitly name alternatives, the scope is well-defined ('a node's stroke'), making it obvious when to use this tool versus other node_set_* siblings. No exclusions or alternatives are stated, but the specificity makes the usage 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 reveals behavioral traits beyond annotations: it clarifies that values are absolute (not relative) and that any subset of dimensions can be provided, leaving others unchanged. Annotations (openWorldHint, idempotentHint) do not cover these specifics, so this adds valuable context 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 a single sentence of 15 words, front-loaded with the action and resource. It provides essential details without unnecessary filler, making it highly 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?

Given the tool's simplicity and the presence of a full input schema (100% coverage) and an output schema, the description adequately covers the core functionality. It does not mention prerequisites or edge cases, but these are not critical for such a straightforward transform tool. A minor gap is the lack of explicit node selection details, but these are covered in the schema.

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 meaning by explaining that x/y/width/height are absolute and that any subset can be set, which the individual schema descriptions do not explicitly convey. This enriches 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 uses a specific verb 'Move and/or resize' and identifies the resource 'a node' with the exact properties (x/y/width/height). It clearly distinguishes from sibling tools like node_set_fill or node_rename by focusing on geometry transformation.

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

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

The description implies usage by specifying the task ('Move and/or resize') and method ('by setting absolute...') but does not explicitly state when to use this tool versus alternatives or provide exclusions. The sibling context hints at differentiation, but the description itself lacks explicit guidance.

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

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

With annotations already indicating destructive behavior (destructiveHint: true), the description adds valuable context by explicitly stating that children are promoted to the parent and the group container is removed. This explains the differential impact on children versus the container, which is not evident from annotations alone.

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 extremely concise, using two short sentences to convey the operation and outcome. Every word earns its place, with no redundant or vague language.

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 low complexity, full schema documentation, and the presence of an output schema, the description sufficiently covers the essential behavior. It explains the operation's effect on children and the group container without needing further detail about return values or prerequisites.

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 comprehensive descriptions for both parameters, including the exact requirement for nodeName to be passed verbatim from node_info. The tool description adds no additional parameter semantics beyond what the schema already covers.

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 (dissolve a group) and its specific outcome (promoting children to the parent and removing the group container). This distinctly separates it from sibling tools like node_delete, which removes a node entirely, and node_group, which creates a group.

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 correct usage (ungrouping a group) and highlights the key behavioral effect of preserving children, but it does not explicitly provide when-to-use versus alternative tools or mention any exclusions. There is no direct comparison to node_delete or other 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?

Annotations already indicate a safe read, but the description adds rich behavioral detail: all-pages mode returns no children, pageIds mode includes top-level children, batch size is capped, and partial failures are handled with a structured pageErrors row while other pages still return. This goes well beyond the annotation's coverage.

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

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

Two tightly packed sentences that front-load the purpose, then explain conditional behavior and error handling. Every word earns its place, with no filler 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?

With an output schema present, return value details are handled elsewhere. The description covers the two main usage modes, batch limitation, and failure semantics, making it fully complete for a listing tool with one optional parameter.

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 describes pageIds with 100% coverage, so the baseline is 3. The description adds extra meaning by detailing the mode contrast (with vs without pageIds) and the batching constraint, giving deeper insight into how the parameter affects 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 uses a specific verb and resource ('List the document's pages'), clearly distinguishing it from sibling node operations. It also differentiates two invocation modes (all pages vs specific pages with children), leaving no ambiguity about what the tool does.

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

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

The description explains when to use each mode (no args for all pages, pageIds for specific pages) and includes the batch limit of 25 ids/call. It doesn't explicitly name alternatives like node_info for non-page nodes, but the intended usage context 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 provide readOnlyHint and openWorldHint, so the safety profile is established. The description adds meaningful behavioral context by specifying that reactions are retrieved from the specified nodes and their descendants, which is not inferable from the 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 a single, front-loaded sentence with no redundant wording. It efficiently conveys the action, resource, and scope in one breath.

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 list operation with one parameter and an output schema, the description covers all necessary context: it names the resource, the traversal behavior, and the input nodes. No further details are needed given the schema and 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 describes nodeIds as 'Array of node IDs to get reactions from,' but the description enriches this by explaining that descendants are included. This clarifies the traversal scope beyond the schema's bare parameter description.

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

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

The description uses the specific verb 'Read' with the resource 'prototype reactions' and the scope 'from one or more nodes and their descendants.' This clearly distinguishes it from sibling tools like reaction_update (write) and other list tools for 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 clearly conveys the intended use case (reading reactions from nodes and descendants) without explicitly naming alternatives or exclusions. The context is unambiguous for a read-only listing tool, though it lacks explicit '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 provide idempotentHint and openWorldHint, but the description adds the critical semantic of full replacement ('Replace ... with a full new reactions array'), clarifying that this is an overwrite, not an incremental edit. This goes beyond what annotations already convey, offering useful behavioral context 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?

The description is a single, well-structured sentence that front-loads the core action ('Replace...') and immediately follows with the crucial usage caveat ('read first via reaction_list'). Every word 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?

Given the tool's complexity and rich schema (extensive reactions definition) plus presence of an output schema, the description effectively covers the key operational requirements: the full-replacement behavior and the read-first prerequisite. It could mention error cases or node existence, but for an agent with access to schema and annotations, 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?

Schema description coverage is 100% and all parameters (nodeId, nodeName, reactions) are fully described in the input schema. The description doesn't add parameter-specific guidance beyond what the schema already provides, 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 uses a specific verb ('Replace') and resource ('node's prototype reactions'), clearly stating the tool's action. It also distinguishes itself from the sibling 'reaction_list' read tool by implying that this is the write counterpart, 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 a clear prerequisite: 'read first via reaction_list,' which guides the agent to fetch existing data before writing. It also emphasizes that the operation expects a 'full new reactions array,' implying a read-modify-write workflow. However, it does not explicitly exclude alternatives or explain when not to use this tool, falling short of a perfect 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?

While annotations already declare destructiveHint=true and idempotentHint=true, the description adds meaningful behavioral context: 'Detaches consumers — they keep their resolved values and lose only the style link.' This explains the non-destructive impact on consumers, which is not present in the annotations. It also clarifies that only local styles are affected.

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 concise sentences. The first sentence front-loads the core purpose, and the second sentence adds a valuable behavioral detail. 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?

For a simple delete operation with two well-documented parameters, an output schema, and safety annotations, the description covers the essential context: the action, the target, and the key side effect on consumers. It does not discuss error cases or prerequisites, but those are not critical for this straightforward 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?

The input schema provides full descriptions for both parameters (styleId and styleName) with 100% coverage. The description only mentions deletion by id and does not elaborate on the styleName parameter, which the schema already explains as the verbatim name from style_list. Thus, the description adds no additional parameter 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 starts with 'Delete a local style by id,' which clearly states the action (delete), the resource (local style), and the method (by id). It distinguishes this tool from siblings like style_list and style_manage by focusing specifically on deletion.

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. It implies deletion but lacks guidance on when to prefer style_delete over style_manage or other style-related tools. The 'local style' qualifier hints at scope but does not clarify alternative selection.

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

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

Annotations already indicate readOnlyHint=true, and the description adds the specific scope (local styles) and style categories, which clarifies what the read operation returns. No other behavioral traits are disclosed, but none are needed for a simple list operation.

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

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

The description is a single concise sentence, front-loading the action and object, with no filler 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 parameters, an output schema present, and annotations covering safety, the description fully covers the tool's purpose and scope. There is nothing missing 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?

The input schema has zero parameters, so the description isn't required to explain parameter semantics. The baseline score 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 uses a specific verb 'List' with a clear resource 'local styles' and specifies the style types (paint/text/effect/grid) and scope ('in the document'), distinguishing it from sibling tools like style_manage or style_delete.

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?

No explicit usage guidance is provided; the description doesn't mention alternatives or when to avoid this tool. Usage is implied by its simple listing nature, but the lack of exclusions or alternative references means the agent must infer when 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?

Annotations only include openWorldHint, so the description carries the burden of behavioral disclosure. It mentions the currentStyleName requirement but omits side effects on existing nodes, whether update overwrites properties, what happens if the style doesn't exist, or permission requirements.

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 short sentences, front-loaded with the core purpose, and contains no redundant words 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 complex nested schema and output schema cover field-level details, but the description lacks complete contextual guidance on mutation behavior, side effects, or failure modes. It's minimally sufficient for a well-schema'd tool.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal value beyond restating that styleId switches to update mode and currentStyleName is required, which is also present 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 clearly states the tool creates or updates named styles (paint/text/effect/grid), and distinguishes between create (no styleId) and update (with styleId) modes. This differentiates it from siblings like style_delete and style_list.

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 explicit usage conditions: use create when no styleId is provided, and update with styleId plus currentStyleName. It doesn't explicitly say when NOT to use it versus alternatives like node_apply_style, but the create/update branching provides clear context.

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 provide idempotentHint and openWorldHint, but the description adds crucial behavioral context about per-item validation and partial_success handling. This goes beyond annotations by telling the agent exactly how to react to partial success, which is essential for correct invocation. No contradictions with annotations.

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

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

The description is two sentences: the first states the operation, the second provides critical success-handling guidance. Every sentence earns its place, with no redundancy or fluff, and the most important information is front-loaded.

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