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

Beyond the annotations (which are all false and give no safety hints), the description richly discloses behavior: 'Omit x/y and the layout engine places it', 'the geometry is computed for you', and 'This does not display anything. Call render_scene once your edits are done.' It also explains that parentId nests the element inside a group. These are meaningful behavioral traits not present in annotations or schema descriptions.

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

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

The description is well-structured and front-loaded: a one-sentence summary, a bold 'USE THIS' callout, then prerequisites, special cases, and rendering note. Every sentence adds unique value—no fluff or repetition of schema content. It is compact despite covering multiple scenarios (first-time adds, connections, layout, grouping, rendering).

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

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

The description is remarkably complete for a tool with nested objects and 3 parameters. It covers prerequisites (get_scene), the exact workflow for linking elements (connection type), layout behavior (omit x/y), grouping (parentId), and the follow-up step (render_scene). Since an output schema exists, the lack of return-value explanation is acceptable. The tool feels self-contained for an agent to invoke successfully.

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 parameters are well-documented in the schema. The tool description nevertheless adds significant value: it explains that the element object is 'exactly the same shape as the entries of elements in render_diagram', provides a concrete example, and clarifies behavior of x/y (omit for auto-layout). This goes beyond the schema, though the core parameter meanings are already covered, so a 4 is appropriate rather than 5.

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

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

The description opens with a clear, specific statement: 'Add one element to a scene that already exists.' This uses a strong verb ('Add'), defines the resource ('element'), and the target ('scene'). It distinguishes itself from sibling tools like update_element, remove_element, and group_elements by focusing solely on adding new elements. Concrete usage examples ('add a load balancer', 'draw an arrow from A to B') further clarify the purpose.

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

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

Explicit 'USE THIS' guidance tells the agent exactly when to apply the tool: 'when the user wants something new in a diagram you already drew.' It also provides alternative and prerequisite actions: 'Call get_scene first if you are not certain which ids exist' and 'Call render_scene once your edits are done.' The connection workflow is explained with 'make a second call with an element of type 'connection'', giving clear usage boundaries.

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 significant behavioral context beyond what annotations provide. Annotations already indicate destructiveHint=true, so the destructive nature is known. But the description clarifies exactly what is destroyed (every element) and what is preserved (id, canvas, theme, title). It also notes that this is idempotent (idempotentHint=true is already in annotations). The only missing detail is whether undo is possible or what the output schema returns, but the output schema exists to specify that.

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

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

The description is three sentences with zero wasted words. The first sentence defines purpose and scope concisely. The second and third sentences provide usage guidelines and sibling differentiation in a clear, front-loaded manner. The 'USE THIS when' and 'DO NOT use it' structure is exceptionally clear.

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 simple tool with only one parameter, clear annotations, and an output schema, the description is complete. It covers purpose, scope, preservation details, usage context, and exclusions. There is no missing critical information for an AI agent to correctly select and invoke this 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% for the single parameter, and the schema already documents that sceneId must match a specific pattern and length, and gives a helpful description. The description adds context by referring to 'as returned by render_diagram or create_scene', which helps in understanding how to obtain the correct ID. This surpasses the baseline of 3.

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

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

The description clearly states the tool removes every element from a scene while preserving its id, canvas, theme, and title. It specifies the verb 'Remove every element' and the resource 'scene', and distinguishes itself from siblings like update_element and remove_element by describing its unique behavior of clearing all elements.

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 tells when to use the tool ('when the user wants to restart the drawing but keep talking about the same diagram') and provides a concrete user utterance ('scrap that, let's do it differently'). It also explicitly tells when NOT to use it ('DO NOT use it for corrections') and names the appropriate alternatives (update_element and remove_element).

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false. The description adds that the scene is empty and that user sees nothing until render_scene is called. This context about the multi-step workflow goes beyond the annotations without contradicting them.

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

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

The description is extremely concise: three short paragraphs. The first sentence states purpose, the second gives usage direction, the third provides an important behavioral note. Every sentence earns its place with zero padding.

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

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

Given the tool has 14 parameters (fully documented in the schema) and an output schema, the description does not need to cover those. It provides the essential workflow context—that this is part of a multi-step process culminating in render_scene—and explains the trade-off with render_diagram, which is sufficient for an agent to decide when to invoke.

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%—every parameter has a detailed description in the schema. The tool description does not add new parameter-level information but also does not repeat 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 'Create a new, empty scene and get back its id,' which is a specific verb+resource statement. It clearly distinguishes from siblings like 'render_diagram' (alternative for known pictures) and 'add_element' (incremental step).

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

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

Explicit 'USE THIS' section describes when to use (incremental building) and 'DO NOT use this' section points to the sibling 'render_diagram' as the better choice for one-shot creation. Also clarifies that nothing is shown until 'render_scene' is called.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: the layout field includes computed boxes for elements never given coordinates, and it warns that the tool does not display anything. This goes beyond the safety profile provided by annotations.

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

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

The description is compact and front-loaded: it states the main function in the first sentence, then provides targeted usage guidance and a caveat. Every sentence earns its place, and the bolded 'USE THIS BEFORE EDITING' plus the final 'This does not display anything' are high-signal phrases with no 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?

With full annotations, a complete input schema (100% coverage), and an output schema, the description supplies all necessary operational context: when to use, what to expect, and a key caveat about non-display. No critical gaps remain for a read-only inspection 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%, with clear descriptions for all three parameters, giving a baseline of 3. The description adds extra meaning by explaining the layout field operationally—'the computed box (x, y, width, height) of every element, including ones you never gave coordinates to'—which clarifies how to use parameters for relative positioning.

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: 'Return the current structured description of a scene' and enumerates the exact contents (id, type, properties, position, size). It also clearly distinguishes itself from rendering siblings with the explicit note 'This does not display anything.'

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 it: 'USE THIS BEFORE EDITING whenever you are not sure of the current state.' It also implies exclusions (not for display) but does not explicitly name alternative tools like render_diagram, so it stops short of a full 5.

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

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

The description goes well beyond the annotations (which only mark non-read-only/non-destructive) by detailing behavioral traits: 'The members keep their ids, and every connection to or from them keeps working - including connections that cross the boundary.' It also explains how the layout parameter affects arrangement and the default behavior ('manual' keeps current positions). This provides rich behavioral context the agent needs for safe invocation.

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

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

The description is concise yet comprehensive, with only 9 sentences. It front-loads the core purpose, then provides usage examples, behavioral guarantees, parameter guidance, and a crucial limitation for nesting. Every sentence adds unique value 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?

Given the tool's complexity (7 parameters, 3 required, 100% schema coverage, output schema present), the description is complete. It explains the grouping behavior, parameter effects, constraints ('Only top-level elements can be grouped'), and nesting strategy. There are no gaps in understanding what the tool does or how to use 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?

With 100% schema description coverage, the schema already documents all parameters thoroughly. The description adds value by explaining the layout parameter options in natural language ('vertical stacks them, horizontal puts them in a row, grid wraps them') and clarifying the scope of elementIds ('top-level elements'). However, it doesn't add meaning to all 7 parameters (e.g., fill, stroke, sceneId are not elaborated beyond schema).

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

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

The description opens with a specific verb+resource ('Wrap existing top-level elements in a labelled container'), immediately clarifying what the tool does. It is easily distinguishable from siblings like 'add_element' (which adds individual elements, not grouping) and 'render_diagram' (which visualizes the whole scene). The examples concretely illustrate its scope and differentiate it from other 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 usage examples ('put all of this inside a box called AWS'), including when to use it ('group these services into a VPC') and a clear limitation ('Only top-level elements can be grouped') with guidance on how to handle nesting ('create the inner one first, then group it together with its siblings'). This effectively tells the agent when and how to use this tool over alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the behavioral insight that calling with 'name' returns a full renderable scene, which goes beyond the schema. However, it does not detail what the output looks like or that it should be passed to render_diagram, though the token 'render_diagram' hints at integration. With annotations covering safety, a score of 3 is appropriate.

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 with no wasted words. It front-loads the core purpose, immediately follows with usage guidance, and ends with a clear list of available examples. Every sentence contributes meaning.

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

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

Given the tool's low complexity (1 parameter, no required ones, enums documented, output schema exists), the description is largely complete. It explains the tool's role, how to invoke it, and the available options. A minor gap is not explicitly stating that the output scene is meant for render_diagram, but the sibling context and the phrase 'pass straight to render_diagram' cover this adequately.

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 schema already documents the single parameter 'name' with enum values. The description adds value by explaining the two usage modes (no args vs with name) and lists the available examples in the enum. However, it repeats what the enum provides, offering only incremental context. Baseline 3 is correct.

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 defines the tool's purpose with a specific verb-resource pair: 'Return complete, working example scenes.' It distinguishes the tool from siblings by stating these are examples to help when unsure about schema usage, unlike render_diagram or get_scene which serve different functions.

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

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

The description explicitly states when to use this tool ('when you are unsure how to express something'), advises against alternatives ('guessing at the schema'), and provides a behavioral tip ('Copy the closest example and adapt it - that is faster and more reliable'). It also clarifies the two calling modes: no arguments for catalogue, or with name for a full scene.

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

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

Beyond annotations (destructiveHint=true), the description details the cascade behavior, deletion of connections and labels, and implications for groups. It warns about dangling references and when to set cascade=false, providing rich behavioral insight.

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

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

The description is well-structured: opening purpose statement, usage examples, behavioral detail, and a specific note on groups. Every sentence adds value, no fluff, and it's appropriately compact for the complexity.

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 destructive nature and edge cases (dependencies, groups), the description covers all necessary aspects. It explains when to use, side effects, parameter nuances, and alternative actions. With an output schema present, no return-value explanation is needed.

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

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

Schema covers all parameters at 100%, so baseline is 3. The description adds value by explaining cascade semantics in depth (when to use false) and the group removal behavior, which goes beyond the schema's simple descriptions.

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

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

The description clearly states 'Delete one element from a scene' with a specific verb and resource. It distinguishes from siblings by giving usage examples like 'remove the cache' and contrasts with add_element/update_element. The purpose is unambiguous and well-scoped.

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

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

Explicitly tells the agent when to use it with 'USE THIS for...' and provides examples. It also gives guidance on when not to use cascade and advises updating the group instead to keep children. This is excellent context for selecting the tool over alternatives.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false. The description goes beyond these by disclosing specific behavioral traits: 'the layout engine positions them from the connections', 'Canvas size is optional: the drawing is auto-fitted', 'Order matters: later elements are drawn on top', and 'Returns a sceneId. Keep it: later edits go through update_element / add_element / remove_element on that id.' This is rich context beyond just the boolean 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 front-loaded with the essential purpose in the first sentence, then branches into use cases, usage rules, best practices, and exclusions. It is quite long but every section earns its place—the 'HOW TO USE IT WELL' section is especially valuable for correct tool invocation. One minor redundancy: 'DO NOT use this tool for: plain prose answers, code, tables of numbers, or when the user explicitly asked for text only' could be slightly tighter, but overall it's well-structured and efficient for the complexity.

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 high complexity (14 params, nested objects, 21 element types), the description is remarkably complete. It covers creation, layout guidance, element semantics, positioning philosophy, return value ('Returns a sceneId'), and lifecycle ('later edits go through update_element / add_element / remove_element'). An output schema exists, so return value details don't need to be in the description. The description fully equips an agent to invoke this tool correctly across a wide range of diagram types.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant meaning beyond the schema: it explains layout philosophy ('Describe WHAT exists, not WHERE it goes', 'omit x/y: the layout engine positions them'), provides best-practice usage for connections ('Link things with { type: 'connection', from: '<id>', to: '<id>' }'), lists semantic element types to prefer, and gives theme descriptions (''dark' (default) is a modern technical look'). This goes well above the baseline.

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

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

The description explicitly states 'Create and render a structured visual diagram as SVG, in a single call.' It lists specific use cases like architectures, network topologies, flows, plots, etc., and distinguishes this tool from alternatives like ASCII art, Mermaid, or manual SVG by asserting 'ALWAYS PREFER THIS OVER...'. The verb+resource combo is very specific, and the guidance on when to use it versus parents like add_element or create_scene is clear.

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 includes a 'USE THIS whenever the user asks...' block listing numerous contexts (visualize, map out, diagram, etc.) and a 'DO NOT use this tool for' block excluding plain prose, code, or pure-text requests. It also advises 'ALWAYS PREFER THIS OVER ASCII ART, box-drawing characters...' and mentions alternatives ('later edits go through update_element / add_element / remove_element'). This provides comprehensive when-to-use and when-not-to-use guidance.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining the tool 'never changes the scene - it only draws what is currently in it', which reinforces the behavioral contract beyond the annotations. A slight deduction is that it doesn't mention any potential rendering delays or failure modes.

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

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

The description is extremely concise with only three sentences, all front-loaded with the core purpose. Every sentence adds value: purpose, usage guidelines, and exclusion of alternatives. 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?

Given the tool has 1 parameter with full schema coverage, an output schema, and comprehensive annotations, the description is complete. It provides all necessary context for an agent to select and invoke this tool correctly: purpose, usage flow, behavioral safety, parameter source, and sibling differentiation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some value by mentioning the sceneId is 'as returned by render_diagram or create_scene', providing context on how to obtain valid IDs. However, it doesn't add new meaning about the parameter format beyond the schema's pattern.

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 this tool renders a stored scene and shows it to the user. It uses specific verbs ('render', 'show', 'display') and identifies the resource ('stored scene', 'updated diagram'), distinguishing it from siblings like render_diagram which builds a new diagram.

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 tells when to use this tool: after a batch of editing calls (add_element, update_element, etc.) as the last step of every edit. It also clearly states when NOT to use it: for brand new diagrams, use render_diagram instead. This provides excellent context for an AI agent to decide.

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

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

The annotations already mark destructiveHint=false and readOnlyHint=false, so mutation is expected. The description goes far beyond by explaining partial update semantics ('Only the fields you send are touched'), immutability of id and type, how to clear properties with null, and the critical fact that nothing is displayed until render_scene is called. 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 four paragraphs, each focused on a distinct aspect (what the tool does, use-cases, anti-patterns, edge cases/immutability/clearing, and rendering dependency). Every sentence serves a purpose; 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?

Given the tool's complexity (3 params, all required, one being a nested object), the description fully covers usage, limitations, behavioral nuances, and integration with sibling tools. An output schema exists, so return values are not needed in the description.

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

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

Schema coverage is 100%, but the description adds enormous value: it explains how to use the `changes` parameter with concrete examples, clarifies that null clears optional properties, and eliminates ambiguity around partial updates. The schema itself is well-described, but the description contextualizes the schema's static definitions into actionable guidance.

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 'Change properties' targeting 'one element', clearly distinguishing it from sibling tools like add_element or remove_element. It also explicitly calls out what it does and does not do, making its 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 provides excellent usage guidance: it tells when to use this tool ('USE THIS for every change that request'), provides examples of specific changes, and explicitly tells when NOT to use alternatives ('DO NOT call render_diagram again to change one thing'). It also gives a relative-move workaround using get_scene.

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