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

Annotations already state idempotentHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is partly covered. The description adds nothing further: it does not say whether the arrow is created on the current scene, whether an id is returned for later move/update_element calls, or how the bound label anchors if the arrow is later moved.

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 short sentences, front-loaded with the core action and with zero filler. It is arguably under-specified rather than verbose, which is the opposite failure mode of conciseness.

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

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

An output schema exists, so return values need not be explained, which lowers the burden. However, for a 13-parameter drawing mutation with no annotation coverage of effects and no schema descriptions, the definition leaves the agent guessing about styling parameters and the coordinate system used for the four required 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 description coverage is 0% across 13 parameters, so the description carries the full burden and largely fails. It hints that x/y/x2/y2 are the two endpoints and label is midpoint text, but elbowed, opacity, roughness, font_family, strokeColor, strokeStyle, strokeWidth, and font_size are given no meaning at all, and the coordinate space/units of the endpoints are never stated.

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

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

States a specific verb and resource ("Add an arrow between two points") plus the optional label behavior, so the agent knows exactly what gets created. It does not differentiate itself from the plausible alternatives in the sibling list such as connect or add_rectangle, so it stops short of a 5.

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

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

There is no guidance on when to choose this over connect (which likely draws a connective line between elements) or the other add_* shape tools. No prerequisites, no mention of needing an active scene or of what happens if coordinates fall outside the viewport.

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 tell the agent this is non-destructive and non-idempotent (each call adds a new element), but the description adds nothing beyond that: no statement of coordinate convention (center vs. corner), units, how elements are layered or selected, or what happens on repeated calls. With 14 parameters and rich style options, a single sentence leaves the mutation behavior largely 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 definition is a single front-loaded sentence with no filler, which is structurally clean. However, at this brevity it is under-specified rather than genuinely concise for a 14-parameter drawing 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?

An output schema exists, so return-value explanation is not required. Still, for a creation tool with 14 parameters and zero schema documentation, the definition omits essentials such as coordinate semantics, units, and how frame_id or styling interacts with the scene, leaving the agent to guess.

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 0% across 14 parameters, so the description carries the full burden and provides none of it. The meaning of x, y, size (radius or diameter?), frame_id, opacity, roughness, fillStyle, and font_* is entirely undocumented, and the text does not even hint at the required geometry inputs.

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

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

The description names a specific verb and resource: "Add a circle (ellipse) to the scene", and the ellipse parenthetical clarifies the shape geometry. It is clearly distinguishable in purpose, but it does not differentiate itself from the many adjacent add_* siblings (add_rectangle, add_diamond, add_arrow), which is what keeps it from a 5.

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

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

There is no guidance on when to choose add_circle over add_rectangle or add_diamond, no prerequisites, and no mention of whether the scene must be loaded/selected first. Usage is only implied by the verb.

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 this is a non-destructive, non-idempotent, closed-world mutation, so safety is partly covered. The description adds nothing beyond that: it does not say whether the diamond is appended to the current frame, how z-order is determined, what identifier comes back, or that repeated calls stack duplicates.

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 single sentence is front-loaded and contains no padding, so it satisfies conciseness. However, at this brevity it is under-specified rather than efficient; one extra clause about coordinates or the returned element would have been worth the 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?

An output schema exists, so return values need no explanation, but a 16-parameter creation tool with zero schema descriptions is under-documented. The geometry parameters (x/y/w/h required, bounded to ±100000) and the styling/typography parameters are left entirely to name inference.

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 0% across 16 parameters, and the description never mentions x, y, w, h, or any styling option. An agent must infer from the schema's property names and constraints alone that these are bounding-box coordinates and dimensions, with no units or origin semantics given anywhere.

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 sentence gives a specific verb (Add) and a specific resource (a diamond), and the shape name alone separates it from add_circle, add_rectangle, and add_text in the sibling set. It does not explain scope (which scene/layer) or what adding entails, but the core purpose is unambiguous.

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

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

There is no guidance on when to use this versus add_rectangle or add_circle, no mention of required prerequisites such as an active frame or scene, and no note about when a diamond annotation is preferable to a rotated rectangle.

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=false, idempotentHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine semantic context by framing the object as a container that can own elements, but it is silent on whether assigned elements move with the frame, whether their coordinates change, or what happens on overlap.

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 short sentences, front-loaded with the core action and followed by the one non-obvious parameter. No filler, though the parenthetical definition of frame could have been spent on behavioral detail instead.

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

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

An output schema exists, so return values need not be described, and annotations cover safety. However, with 13 parameters, five of them required geometry, and a containment relationship to explain, the definition is too thin to let an agent call this correctly without guessing about coordinates and child assignment semantics.

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 0% across 13 parameters, so the description must compensate and does not. Only element_ids is explained; x/y/w/h geometry, name, opacity, roughness, and the fillStyle/strokeStyle/strokeColor/backgroundColor styling parameters are left entirely to bare schema constraints, with no meaning added about coordinate origin or units.

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

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

States a specific verb and resource ("Add a frame") and glosses the concept as a "boundary container," which tells an agent what a frame is versus a generic shape. It does not distinguish itself from the closest sibling, add_rectangle, so it falls short of a 5.

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

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

The only usage hint is that element_ids can optionally assign existing elements to the frame. There is no guidance on when to choose a frame over add_rectangle, whether the frame must exist before or after its children, or any prerequisites. An agent must infer nearly everything about 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 cover safety (destructiveHint=false, openWorldHint=false, idempotentHint=false). The description adds one genuinely useful behavioral fact: omitted style parameters fall back to Excalidraw defaults rather than to some tool-specific value. It does not say whether the new element is selected, returned, or how it interacts with an active frame, so the addition is modest.

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 short sentences with the action front-loaded and the defaulting caveat immediately after. No filler, though the second sentence is vague enough ("style parameters") that it could name the relevant group more crisply.

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 16-parameter geometry-plus-styling tool with zero parameter documentation in the schema, the description is far too thin; an agent cannot confidently supply coordinates, labels, or frame attachments from it. The output schema does relieve it of describing return values, which is the only reason this is not a 1.

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 0% across 16 parameters, so the description carries the full burden and largely fails: it never mentions x/y coordinate space or units, w/h constraints, what label does, or what frame_id attaches to. The one contribution — that style parameters are optional and default — is real but covers only a fraction of the surface.

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?

"Add a rectangle to the scene" gives a specific verb (add) and resource (rectangle), and the sibling list makes it trivially distinguishable from add_circle, add_diamond, add_frame. It stops short of stating scope/side effects, but the purpose itself is unambiguous.

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

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

No guidance on when to choose this over add_frame, add_text, or update_element, and no preconditions (e.g. whether a scene must be loaded/opened first). The only conditional statement concerns omitting style parameters, which is a defaulting note rather than a usage rule.

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=false, idempotentHint=false and openWorldHint=false, and 'Add ... and return its element ID' is consistent with a non-destructive, non-idempotent mutation that hands back a handle. Beyond that it says nothing about undo behavior, whether the coordinate space is scene-relative, or how the element interacts with frames, so it adds only modest context over the structured fields.

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

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

Two sentences, front-loaded with the action and return value, then the parameter detail. The font enumeration is slightly redundant with the schema enum and inconsistently drops the 'handwriting' value, but the numeric mapping (1-4) genuinely adds information not present elsewhere.

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?

Placeholder.

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 0% across 8 parameters, so the description carries the full burden and covers only font_family. It omits all meaning for x, y, content length limits, opacity, font_size, frame_id and strokeColor, leaving the agent to infer units and coordinate systems from property names alone.

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

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

States a concrete verb and resource ('Add standalone text') plus a useful side effect ('return its element ID'). 'Standalone' implicitly separates it from container-attached or shape-creating siblings such as add_rectangle or add_frame, though no sibling is named explicitly.

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

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

There is no when-to-use or when-not-to-use guidance, no mention of prerequisites, and no routing to alternatives like update_element for changing existing text. The only implied usage cue is the word 'standalone', which the agent must interpret on its own.

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=false, openWorldHint=false, and idempotentHint=false, so the safety profile is partly covered; the description adds genuinely new information by stating that repairs are applied automatically and carry 'rollback safety'. However, it does not say what rollback concretely means (the sibling undo tool is never referenced), whether repairs are grouped for a single undo, or what state the scene is left in on partial failure. With annotations doing part of the work, this lands at adequate-but-incomplete.

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 with no filler; the verb sequence and defect enumeration are ordered informatively. It is efficient rather than padded, though the density means the rollback claim gets no 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?

This is a complex, non-idempotent scene-mutating tool with five undocumented parameters, and the description covers only the purpose and a vague rollback promise. Because an output schema exists, return values need not be explained, but the missing pieces — what dry_run yields, what min_gap controls, how aggressive repairs trade off, and how to undo — are the ones an agent needs before invoking it.

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 0% across five parameters, so the description carries the full burden and does not meet it. The defect list loosely maps to the repair_scope enum values (overlaps, text/connectors, containment, spacing), but dry_run, min_gap, aggressiveness, and especially name receive no explanation at all — min_gap's unit and aggressiveness's behavioral trade-off are exactly the kind of detail the schema lacks.

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

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

The description names concrete actions (diagnose, plan, repair) and an explicit resource (layout defects) with a parenthetical enumeration of defect classes: overlaps, text clipping, containment, routing, spacing. This clearly distinguishes it from siblings like move, resize, or update_element, which alter elements individually rather than auto-repairing layout. It stops short of 5 because it never states the operating scope (scene-wide vs. selected elements), which is the main ambiguity against those siblings.

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

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

There is no when-to-use guidance: nothing says whether this should be run instead of manual move/resize fixes, whether it must follow get_scene or describe_scene, or when to prefer preview or undo. The presence of a dry_run parameter is not acknowledged, so the natural safe-first workflow is left entirely implicit. An agent must infer the workflow from parameter names alone.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally. The description earns credit for disclosing the exact blast radius beyond the annotations: not just elements but also app state and files. It stops short of saying whether an 'undo' can restore the cleared scene.

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 with the destructive scope made explicit from the first word. No filler, no repetition of the tool name or annotations.

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

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

With zero params, an output schema present, and annotations covering safety, the description only needs to state scope — which it does fully. The one remaining gap is recoverability (whether 'undo' restores a cleared scene), which an agent calling a destructive tool would want to know.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly conveys that the operation is unscoped and unparameterized.

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

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

States a specific verb ("Remove") and a precise scope ("all elements, app state and files") on the scene resource. It implicitly separates itself from the sibling 'delete' by emphasizing 'all', but never names or explicitly contrasts with that sibling.

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?

Usage is only implied: 'all' signals a full reset rather than a targeted removal, which is enough to infer when to prefer it over 'delete'. There is no explicit when-to-use, no exclusions, and no mention of prerequisites such as saving or undo availability.

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=false, idempotentHint=false, and openWorldHint=false, so the safety profile is partly covered. The description adds real value with "bound," telling the agent the arrow stays attached to the shapes, but it omits what happens on an invalid ID, whether calling twice creates two arrows (relevant given idempotentHint=false), and any required preconditions.

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 with zero filler and no repetition. It is efficient, though the brevity is partly the cause of the documentation gaps captured in other dimensions rather than a virtue in itself.

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

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

An output schema exists, so return values need not be explained, but for an 11-parameter mutation tool the description is far too thin. An agent cannot tell what the styling parameters do, what units or defaults apply, or how the connector behaves relative to add_arrow.

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 0% across 11 parameters, so the description must carry the burden and it does not. Only source_id/target_id are implicitly explained; label, elbowed, opacity, font_size, font_family, roughness, strokeColor, strokeStyle, and strokeWidth are entirely undocumented in both schema and 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?

"Connect two existing shapes by ID with a bound arrow" names a specific verb (connect), the resource (two existing shapes), and the mechanism (by ID, bound arrow). This distinguishes it reasonably well from add_arrow, though it never explicitly names add_arrow as the alternative for a free-floating arrow.

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?

Usage is only implied: "existing shapes" signals the shapes must already exist, so an agent infers it should call add_rectangle/add_circle first. There is no explicit when-to-use vs when-not, and no mention of add_arrow or update_element as alternatives for other connector needs.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, so the safety profile is covered; the description adds genuinely non-obvious side effects — the owned label dies with the element and remaining connectors are detached rather than deleted. It omits whether the operation can be reversed (an `undo` sibling exists) and what happens when element_id does not resolve.

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

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

One sentence, zero filler, and the destructive scope is front-loaded before the secondary connector behavior. Nothing is restated from the name or annotations.

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

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

For a one-parameter destructive tool whose annotations and output schema already cover safety and return shape, the description supplies the critical cascade semantics. The remaining gap is reversibility and failure behavior on a missing element.

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 0% for the single `element_id` parameter, so the description carries the burden, and it only weakly does so: "an element" lets the agent infer the parameter names the target, but there is no statement of accepted id format, whether it may be a name, or what error an unresolvable id produces.

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

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

States a specific verb and resource ("Delete an element") and adds cascade scope: the owned label is removed and surviving connectors are detached. It does not distinguish this from the sibling `clear`, so an agent must infer that delete targets one element while clear presumably wipes more.

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?

Usage is only implied — remove one existing element. There is no explicit when-to-use, no exclusion against `clear` (bulk removal) or `update_element`, and no precondition such as the element existing or the deletion being undoable via the sibling `undo`.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral content by naming what the prose covers (spatial layout, clusters, connectivity), but says nothing about output size, cost/latency, or how verbosity is controlled by the detailed flag.

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

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

One compact sentence, front-loaded with the verb and the produced artifact. The framing 'human/agent-readable' and the trailing 'for cognitive verification' are slightly redundant but not wasted.

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

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

An output schema exists, so return values needn't be explained, and the annotations cover safety. What is missing relative to a crowded sibling set is any guidance on detail level (the detailed parameter) or when to choose prose description over the structured getters.

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 0% for the single parameter 'detailed', and the description never mentions it or explains what toggling it changes. With only one boolean at stake the impact is limited, but the description does nothing to compensate for the undocumented 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 and object: 'Generate a ... prose description of the diagram's spatial layout, clusters, and connectivity.' An agent can tell this produces natural-language prose rather than the structured data returned by get_scene, although the description never names that sibling or get_scene_summary explicitly.

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 'for cognitive verification' implies a context (an agent sanity-checking a layout it just built), but there is no explicit when-to-use rule and no routing away from the several overlapping siblings (get_scene, get_scene_summary, preview, export_scene). Usage is inferable but not stated.

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

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

The destructiveHint=true annotation is consistent with the description's explicit 'Replace the scene', and the description goes beyond the annotation by explaining the layout algorithm (components arranged horizontally with automatic connectors) and that styling applies globally to every element. It stops short of saying whether the prior scene is recoverable via undo or whether a save is needed first.

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 core action is front-loaded in the first sentence, and each following sentence adds distinct information (input syntax, layout behavior, styling scope). Size is appropriate for a tool with this much surface; only the heavy code-quoting makes it marginally longer than necessary.

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

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

An output schema exists, so return values needn't be described, and the description covers the essential input grammar and layout rule. For a destructive full-scene replacement with ten parameters, though, it omits recovery/prerequisite context (undo availability, guidance on selecting draw_mermaid vs this tool) that an agent would want before wiping a scene.

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 0% across 10 parameters, so the description must carry the load. It does well on the required 'prompt' parameter, documenting the shape-prefix syntax and accepted shape aliases, but it compresses the nine style parameters into one sentence about being optional and global—useful for scoping but not explaining any individual parameter's meaning or interaction.

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

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

The description gives a specific verb and effect ('Replace the scene with a diagram') plus the exact input grammar ('shape: label' with rectangle/box, circle/ellipse, diamond) and layout behavior. It is clear what the tool builds, though it never names a sibling such as draw_mermaid to disambiguate between the two diagram-generation paths.

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?

Usage is implied by the input format (a comma/newline-separated component list), which tells the agent this is the bulk-diagram path rather than incremental add_rectangle/add_circle calls. However, there is no explicit 'use this when X, use draw_mermaid instead when Y' guidance or precondition statement.

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 flag destructiveHint=true, yet the description never says whether rendering replaces the current scene or appends to it, what existing elements are lost, or what happens with malformed Mermaid or the 2000-character limit. With annotations covering the safety profile only at a flag level, the description should supply the 'what gets destroyed' context and does not. No annotation contradiction, since rendering to a scene is plausibly destructive.

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 tight sentence with the key action front-loaded and no filler. It is appropriately sized as a purpose statement, though brevity here comes at the cost of the missing parameter and behavior 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?

An output schema exists, so return values need not be explained, but the definition is still too thin for a tool with five parameters, 0% schema coverage, and destructive semantics. An agent cannot tell from this description how to choose layout/elbowed/roundness or whether its current scene survives the call.

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 0% across five parameters, so the description carries the full burden and only implies that mermaid_code is the input. layout, elbowed, direction, and roundness get no explanation of what 'layered' vs 'horizontal' vs 'vertical' means or how direction and layout interact. This is a significant gap for a 5-param tool.

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

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

The description gives a specific verb+resource: 'Parse Mermaid flowchart/graph code and render it directly to the Excalidraw scene.' That clearly separates it from element-level siblings like add_rectangle or draw_architecture. It stops short of explicitly naming those alternatives, so it does not fully distinguish itself in prose.

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

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

There is no when-to-use guidance and no mention of alternatives such as draw_architecture, preview, or auto_fix_layout. An agent must infer from the name alone that this tool is chosen when it already has Mermaid source text rather than a scene spec.

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 openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds destination-selection context ('project or configured directory'), but says nothing about the overwrite flag's effect on existing files or the scale/background rendering behavior, which matter for a file-writing tool.

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

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

A single well-formed sentence with the action and output format front-loaded and no filler. Its brevity is appropriate, though the space saved was not used to convey any parameter or usage 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?

An output schema exists so return values need not be explained, but for a six-parameter mutation-style file writer with zero schema description coverage, the description leaves too much unstated: defaults, overwrite semantics, and how the destination is resolved.

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 0% across six parameters, and the description only obliquely touches the 'directory' parameter. Nothing explains what 'scale', 'padding', 'background', or the required 'name' pattern mean in practice, so the agent gets no semantic help where the schema provides none.

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

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

States a specific verb (Export) and resource (the active scene) plus the output format (PNG image file), which distinguishes it from the sibling export_scene. It does not explicitly contrast with preview or save, but the format specificity is enough for an agent to identify it.

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

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

There is no guidance on when to choose this over export_scene, save, or preview, and no stated prerequisites. The destination phrase 'in a project or configured directory' hints at context but does not tell the agent how 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered structurally. The description's added value is 'No file is written', which usefully disambiguates the 'export' name so the agent knows nothing is persisted server-side, but it says nothing about the payload format or size.

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 short sentences with no filler, and the core fact (what is returned) is front-loaded before the clarifying caveat about no file being written.

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

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

For a zero-parameter, read-only tool with no output schema, the description carries the essential information: the return is an embedded .excalidraw document, not a file path. The only gap is that it doesn't say whether the document is raw JSON or encoded, which matters for a client that must save/import it.

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

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

The tool takes zero parameters, so there is no parameter meaning to convey and the baseline of 4 applies. The description correctly avoids inventing options and makes clear the call is argument-free in effect.

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

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

States a specific verb ('Return') and resource ('embedded .excalidraw document'), and adds the outcome ('for the client to save/import'), which is concrete enough to picture the result. It does not explicitly distinguish itself from near siblings like get_scene, save, or export_png, so an agent must infer the boundary.

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 'for the client to save/import' implies the use case (you want the serialized document rather than an in-server action), but there is no explicit when-to-use versus get_scene/save/export_png guidance or any stated precondition. Usage is implied rather than directed.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds only the notion of 'active' elements (implying inactive/deleted ones are excluded), but says nothing about result ordering, the 50-default/200-max cap, or how criteria interact — the schema carries those facts.

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 compact sentence with no waste, but it is under-specified rather than tight — the brevity comes at the cost of any usage or parameter detail an agent would need for a 7-parameter 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?

Seven optional parameters with zero schema descriptions and no output schema explanation in the description leaves real gaps; an agent cannot tell how to combine filters, what 'active' excludes, or what include_bound_labels does. The output schema's existence excuses explaining return values, but not the missing filter semantics.

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 0%, so the description must carry parameter meaning; it partially does, mapping to query, type, frame_id, and connected_to. However element_id, limit, and especially include_bound_labels (a non-obvious boolean affecting what is returned) get no explanation anywhere in the definition.

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

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

States a specific verb and resource ('Find active elements') plus the criteria dimensions it filters on (query string, type, frame, connection). This is clearly a filtered search over elements and distinguishable from the singular 'get_element' sibling, though the word 'active' is left undefined and no sibling is named explicitly.

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 when-to-use guidance is given: nothing says whether to prefer this over get_element, get_scene, or get_scene_summary, nor what happens when multiple criteria are combined or none are supplied. Usage can only be inferred from the list of criteria.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and locality are covered. The description adds the useful detail that only *active* elements are returned, implying soft-deleted ones are excluded, but it does not say what happens when the ID is missing or inactive.

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 with zero filler. It is efficient but bordered on under-specified, which is a content issue rather than a wording one.

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 shape needs no explanation, and a one-parameter lookup is simple. Still, the not-found and inactive-element behavior is left unstated, which is the one thing an agent would want to know before calling.

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?

One parameter with 0% schema description coverage, so the description must compensate; it only restates that the parameter is an ID. The name element_id and the non-blank string pattern make the intent largely self-evident, so the gap is mild.

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?

Specific verb and resource: 'Return one active element by ID.' This clearly separates it from get_scene (whole scene), find_elements (search), and get_resource, even though no sibling is named explicitly. The 'active' qualifier hints at scope beyond a bare fetch.

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?

Usage is only implied by 'by ID': you must already hold an element_id. There is no guidance on when to prefer this over find_elements or get_scene, and no mention of what to do when the ID is unknown.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds only that four resource families are reachable through one entry point and says nothing about what happens when all three optional parameters are omitted, or what lookup precedence applies.

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 with no filler. It is efficient, though the brevity is achieved by omitting substance rather than by compression.

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

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

An output schema exists so return values need no explanation, but for a three-parameter universal lookup tool with zero parameter documentation in either schema or description, the caller has no way to construct a valid request. This is materially 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?

Schema description coverage is 0% and all three parameters (uri, identifier, resource_type) are nullable with no defaults documented. The description adds no meaning to any of them — not what an identifier looks like, not the accepted resource_type values, not how uri and identifier interact.

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

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

States a verb (retrieve) and lists resource kinds (scene, library, theme, element), but the four kinds are not defined and two of them collide with dedicated siblings (get_scene, get_element), so an agent cannot tell whether this is a superset or an unrelated path.

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 indication of when to call this instead of get_scene, get_element, or describe_scene. The phrase 'unified interface' hints at generality but never says which call wins for a given resource type.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds that results are paginated and that the current revision accompanies them, which is useful context beyond the annotations, but it does not say how paging terminates, whether an empty list is possible, or whether revision changes between calls.

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 with no filler or redundant restatement of the name. It is efficient, though its brevity is partly the cause of the missing guidance rather than a virtue in itself.

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

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

An output schema exists, so return values need not be spelled out, and the read-only profile is covered by annotations. Still, for a listing tool with two undocumented parameters and several overlapping siblings, the definition does not say enough about scope and paging behavior for an agent to call it confidently without inspecting 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 0%, so the description carries the burden for limit and offset, yet it only says 'pagination' without explaining either parameter. It omits the meaningful constraints the schema encodes (limit default 50, maximum 200, offset default 0) and does not relate the returned revision to any parameter.

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

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

The description gives a specific verb ('List') and resource ('active elements') plus a secondary return ('current revision'), but the tool is named get_scene, so the object being read is only implicitly a scene. It also offers no differentiation from close siblings like get_scene_summary, describe_scene, find_elements, and get_element, leaving the agent to guess which of them returns elements versus a scene description.

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

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

There is no when-to-use guidance at all: nothing says when to prefer get_scene over get_scene_summary, describe_scene, or find_elements, nor any exclusion such as filtered or inactive elements. Only the phrase 'active elements' hints at scope, and even that is left unexplained.

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 establish that this is a read-only, closed-world operation, so the description does not need to repeat safety traits. It adds useful disclosure of the returned categories, such as counts, dimensions, layers, code blocks, and text contents, but it does not mention prerequisites such as whether a scene must already be loaded.

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

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

The definition is a single well-formed sentence with the purpose front-loaded. The parenthetical list is purposeful because it enumerates the kinds of summary data the agent can expect.

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 no-parameter, read-only summary tool with an output schema, the description provides enough context to understand what it returns. A brief note distinguishing it from the fuller scene and description tools would make 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 tool has zero parameters, so there are no parameter semantics for the description to clarify. The empty schema is consistent with the description, which frames the tool as taking no input and returning a summary.

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

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

The description gives a specific verb-resource pair: it returns structured numerical metrics and topological metadata for a scene. It clearly conveys that this is a summary-oriented read operation, though it does not explicitly differentiate itself from siblings such as get_scene or describe_scene.

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 'for layout planning' implies the usage context, which is helpful but not a full when-to-use rule. It does not state when to choose this tool over get_scene, get_element, or describe_scene, leaving the agent to infer the distinction from the names.

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

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

Annotations already declare destructiveHint and openWorldHint, but the description adds real value beyond them: it states the current scene is replaced (data loss) and that concurrent modifications cause a retry error, which the agent cannot learn from the annotations alone. It does not say whether the prior scene is recoverable or whether the operation can be undone.

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

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

One short sentence with the destructive action front-loaded and the concurrency caveat second; nothing is wasted. It is telegraphic, but that suits a single-parameter 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?

An output schema exists so return values need not be explained, and the tool is simple with one parameter. Still, the undefined 'name' semantics and the absence of guidance on recovering from the retry error leave meaningful gaps for a destructive, world-affecting operation.

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

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

Schema description coverage is 0% for the single required 'name' parameter, so the description carries the burden and does not compensate. 'A saved document' only hints that name identifies the document; it never explains the name format, the regex pattern, or whether it refers to a resource identifier rather than a file path.

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

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

The description gives a specific verb ('Replace') and resource ('the scene') plus the source ('a saved document'), which resolves the ambiguity of the bare name 'load'. It does not explicitly contrast with siblings like save, get_scene, or clear, so it falls short of full sibling differentiation.

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

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

Usage is only implied: the agent can infer this restores a previously saved document into the current scene. There is no explicit when-to-use versus alternatives (e.g., clear then load, or get_scene for inspection) and no stated 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?

Beyond the idempotentHint and openWorldHint=false annotations, the description discloses real side effects: connectors follow the moved shape and directly moved arrows detach. That is exactly the kind of consequence an agent needs before mutating a diagram. It does not explain the coordinate system or what happens to attached text offsets, keeping it short of 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 short sentences, front-loaded with the primary action and followed by the side-effect caveat. No filler or 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?

An output schema exists, so return values need not be described, and annotations cover idempotency. However, for a geometry mutation with three undocumented parameters, the missing coordinate semantics leave a real gap an agent must guess at.

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 0% for three required parameters, so the description must carry the burden and it does not. It never states whether x/y are absolute scene coordinates, whether units are pixels, or what element_id accepts (shape, text, arrow).

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

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

The description gives a specific verb and resource ("Move an element and its label") and clarifies that the label travels with the element, which distinguishes it from siblings like resize or update_element. It does not explicitly name those siblings, so differentiation is implied rather than stated.

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

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

There is no statement of when to choose this tool over update_element or resize, and no prerequisites or exclusions. The agent must infer that repositioning uses move while other property changes use update_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?

The annotations already establish that this is a read-only, non-open-world operation. The description adds that the output is an inline PNG of the active canvas, which is useful, but it does not explain rendering behavior such as scale, padding, or background effects beyond the schema defaults.

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 unnecessary wording. It is appropriately sized for a simple preview operation.

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 preview tool with no output schema, the description covers the core behavior: rendering an inline PNG of the active canvas. It remains incomplete because it does not explain the three optional parameters or how this differs from related export tools.

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

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

The input schema has three parameters with 0% description coverage, and the description provides no information about what scale, padding, or background mean or how they affect the preview. The description therefore does not compensate for the schema's lack of parameter documentation.

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

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

The description gives a specific verb and resource: render an inline PNG image preview of the active Excalidraw canvas. It is clear what the tool does, though it does not explicitly distinguish itself from sibling tools such as export_png or get_scene.

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 'inline PNG image preview' implies this is for quickly viewing the current canvas rather than exporting a file. However, the description gives no explicit when-to-use guidance, no exclusions, and no comparison with alternatives like export_png.

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 and openWorldHint=false, so the safety and repeatability profile is covered. The description contributes one genuinely new behavioral fact — that the label is recentered as a side effect — but says nothing about units, coordinate anchoring, whether aspect ratio is preserved, or behavior on elements without labels.

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 tight sentence with no filler, and the core action is front-loaded. It is efficient, though the brevity comes at the cost of the missing detail noted elsewhere rather than being a model of completeness.

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

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

An output schema exists, so return values need not be explained, and the annotations cover idempotency and world scope. Still, for a 3-parameter mutation with zero schema coverage, the description should say what the dimensions mean and which element types qualify; the one-sentence label note is not 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 0%: element_id, width, and height carry only types and bounds, with no textual explanation. The description does not compensate at all — it never mentions the parameters, so units (pixels? points?), whether width/height are absolute or relative, and what element_id must identify are all undocumented.

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

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

The description gives a specific verb ('Resize') plus the resource ('a shape') and adds a secondary effect ('recenter its label'), which lets an agent distinguish it from siblings like move or update_element. It is slightly vague about whether non-shape elements (text, frames) are accepted, since the input schema just takes a generic element_id.

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 when-to-use or when-not-to-use guidance is given. With siblings such as move and update_element present, the agent is left to infer that resize is for changing dimensions and update_element is for other property changes, but the description never states this or names an alternative.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, so the safety profile is known; the description adds real value by naming exactly what is destroyed — an existing file when overwrite=true. It also hints at atomicity via "consistent snapshot," but does not say where the file is written, whether the write is atomic on failure, or what happens if the name already exists with overwrite=false.

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

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

Two short sentences, the core action first and the risky parameter second, with no filler. Slightly tight to the point of under-specification — "consistent snapshot" is a phrase that does little work without a defined scope.

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

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

An output schema exists, so return values need not be explained, and annotations cover the destructive/open-world profile. What is missing is the context an agent needs to call this correctly in a crowded sibling set: what a snapshot contains, where it is stored, and how it relates to load/export_scene.

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 0%, so the description carries the burden. It fully explains overwrite's effect (replace an existing file) and, by implication, identifies name as the target file, which is more than the bare pattern/default in the schema. However, the required name parameter's format, uniqueness, and relationship to sibling resources are still unstated.

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?

"Save a consistent snapshot" gives a verb plus an object, but "snapshot" is left undefined — of a scene, a file, or the whole workspace is never stated. With siblings like export_scene, export_png, preview and load, the description does not make clear how this differs from exporting or previewing, so the agent must infer the scope.

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

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

The only conditional guidance is "Set overwrite=true to replace an existing file," which is about a parameter rather than about when to pick this tool. Nothing tells the agent when to save versus export_scene, export_png, preview, or load, and no preconditions (existing file, permissions) 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?

Annotations already declare destructiveHint=true and openWorldHint=false, so the agent knows this mutates scene state locally. The description adds useful nuance that only 'successful' mutations are reverted, implying failed operations do not consume the undo. It does not, however, state what happens when there is no prior mutation, whether the undo itself can be reverted (no redo), or that the current state is discarded.

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 tight sentence with the action front-loaded and no filler. Every clause ('before', 'most recent', 'successful') carries distinct meaning about scope.

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 and an output schema present, the description need not explain return values, and it covers the essential behavior. The remaining gap is edge-case behavior — what happens with an empty undo history, and whether multiple successive undos walk further back — which an agent might reasonably want to know.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline for a parameterless tool is 4. The schema is fully closed (additionalProperties: false), so nothing is left ambiguous on the input side.

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

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

The description gives a specific verb ('Restore'), an explicit resource ('the scene'), and a precise temporal scope ('before the most recent successful mutation'), which effectively defines undo. It does not explicitly distinguish itself from siblings like 'clear' or 'delete' (other state-changing operations), so it stops short of a 5.

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

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

Usage is only implied: an agent can infer it should call this after an unwanted change, but there is no explicit when-to-use/when-not guidance, no mention of what to do if nothing has been mutated, and no named alternatives. The phrase 'most recent successful mutation' does hint at single-step semantics, which is some 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 openWorldHint=false and idempotentHint=true, so safety and repeatability are partly covered, but there is no readOnlyHint/destructiveHint, leaving the mutation profile undisclosed in structured form. The description does add one genuinely valuable behavioral fact beyond annotations: an empty label removes the existing label, which is a destructive side effect an agent could not guess from the schema. It does not state that omitted fields are left unchanged, what happens for a nonexistent element_id, or whether updates are reversible.

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 tight sentences with zero filler, and the surprising deletion rule is stated up front rather than buried. The structure is efficient, though its brevity is partly the problem — the second sentence earns its place far more than the first, which undersells the tool's scope.

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

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

An output schema exists, so return values need not be described, but that is the only thing mitigating an otherwise thin definition. For a 14-parameter mutation tool with 0% schema description coverage and only partial annotation coverage, the description should explain which fields affect geometry vs text vs styling, and how omitted vs null values are treated. It does not, so an agent must guess for the majority of parameters.

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

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

Schema description coverage is 0% across 14 parameters, so the description carries the full burden and largely fails it. It explains only the label parameter's empty-string semantics; elbowed, opacity, frame_id (which likely reassigns an element to another frame), fillStyle, roughness, roundness, font_family's odd union of enum/string/integer, and the stroke/background color formats are all undocumented beyond raw JSON constraints. The one clarification given is valuable but leaves most of the surface unexplained.

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

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

The description names a specific verb ("Update") and lists some targets (label, font, styles), and it hints at the element scope implicitly. However, it only accounts for roughly 3 of the 14 parameters — the geometry/appearance fields (frame_id, elbowed, roundness, roughness, opacity, stroke/fill properties) are collapsed into the vague word "styles," and element_id is never mentioned. An agent can tell this mutates an existing element but not the full breadth of what it mutates, and nothing distinguishes it from siblings like move, resize, or add_text.

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

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

There is no when-to-use guidance at all — no statement of prerequisites (must the element already exist?), no routing to move/resize for geometry-only changes vs this tool, and no guidance on what happens to parameters that are omitted. The only usage-adjacent rule is the empty-label deletion behavior, which is useful but narrow. The agent is left to infer the tool's role relative to 27 siblings.

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