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

With no annotations, the description carries the full burden and does so well: it discloses that ids are returned, that overlap warnings are emitted for the touched elements, how clip and place bindings persist and are freed with null, how fit_to re-fits on edits, and how defaults are merged. It still omits permission/auth needs, whether the operation is undoable, and what the preview flag actually does.

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 purpose and return contract are front-loaded, and given the complexity of the element spec almost every clause documents a real key or behavior that exists nowhere else. It is dense and delivered as one long block rather than grouped by type, which slightly hurts scanability, but little of it is filler.

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

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

For a mutation tool with no annotations, no output schema, and five undocumented parameters, the description covers element content thoroughly. It nonetheless leaves gaps an agent needs: the meaning/optionality of doc_id, what preview does, and any statement about reversibility or error behavior.

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 the elements array is only additionalProperties:true, so this description is the sole documentation of the per-type geometry keys, defaults merging, and elements_path file format — a large amount of meaning added. However doc_id and preview are never explained in the text, leaving two of five parameters undocumented in both places.

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 opening sentence gives a specific verb and resource ('Add one or more elements in a single call') plus the return value ('Returns the new ids'), which cleanly separates it from update_elements and delete_elements in the sibling list. The subsequent text never drifts from that scope, so an agent can identify the tool without opening the schema.

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 extensive spec-key documentation rather than stated: there is no explicit 'use this when creating new elements vs. editing existing ones' guidance, and no prerequisites or when-not conditions. It does give one useful routing hint inside the tool ('elements_path ... for generated geometry, so it never passes through the conversation'), but only for a sub-choice, not for tool selection.

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

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

With no annotations provided, the description carries the full burden. It usefully discloses ordering semantics ('operations run in order, each seeing the previous moves') and the return shape (moves [dx, dy] plus new bboxes), but never states that this is a mutating operation, whether it is reversible, or what permissions/doc_id it requires.

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?

Front-loaded purpose statement followed by one compressed, high-value example and a return-value clause. No filler sentences; every element contributes.

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 nested, multi-operation mutating tool with no annotations and no output schema, the description covers sequencing and returns but omits the mutation semantics, doc_id/preview meaning, and grouping behavior. Adequate but with real gaps.

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

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

Schema coverage is reported at 0%, so the description must compensate, and it does partially: the example demonstrates the nested operations structure and the ids/to/horizontal/vertical keys, which is not obvious from the top-level schema. It still leaves margin, as_group, text_metrics, doc_id, and preview 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?

States a specific verb and resource ('Align elements to the page, to each other, or inside another element') and immediately anchors it with a worked example. This is clearly distinguishable from siblings like layout, z_order, or move_to_layer.

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 three reference modes (page, other elements, inside another element) imply when the tool applies, and the label-in-a-box example grounds it. However, it names no alternative tool or explicit when-not condition, so the agent must infer the boundary with siblings such as layout or update_elements.

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

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

With no annotations, the description carries the load well: it discloses the default implementation (native Inkscape connectors clipped to the real shape, still live in the GUI), the behavioral difference when from_side/to_side/via or gaps are supplied (inksmcp-computed routing, attachment at the middle of a side), and even what is returned (ids, layers, label ids, warnings). Missing only permissions/failure behavior.

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

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

Front-loaded with the core behavior before the routing detail, and every sentence carries information. It is dense with parentheticals and runs as one long block, which costs a little readability but little is 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?

For a complex tool with a nested per-connection schema and no output schema, the description covers default behavior, the routing/gap modes, the example use case, and the return payload. An agent has enough to call it correctly.

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

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

Top-level schema coverage is 0%, but the description compensates by explaining the routing parameters concretely — from_side/to_side/via with an inline JSON example, and the side effect that start_gap/end_gap also cause mid-side attachment. doc_id and preview are still unexplained, keeping it below 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?

States a specific verb (draw) and resource (arrows/lines between elements) with a distinctive property — they stay attached when things move. Names adjacent siblings (align/layout/update_elements/page_fit) to delineate a different task, so an agent can distinguish it from those tools without opening schemas.

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?

Gives clear context: it is for persistent connectors that follow elements, and the parenthetical of related tools implies the workflow it fits into. However, it never states explicit exclusions or 'use X instead when Y', so the routing decision is left partly to inference.

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

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

With no annotations, the description carries the full burden and does well: it discloses that children, attached connectors, labels, and now-orphaned defs are destroyed as a side effect, and that removed ids plus a defs_removed count come back. It stops short of stating permission/auth requirements, whether the deletion is undoable, or how doc_id selects the target document.

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

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

Three dense sentences with the core action front-loaded, followed by consequences and return values. Nearly every clause earns its place, though the parentheses and the mid-sentence 'go too' phrasing make it slightly less scannable than it could be.

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

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

For a destructive two-parameter tool with no annotations and no output schema, the description covers the destruction semantics and return payload reasonably, but leaves doc_id behavior and any auth/undo information unexplained, so an agent still lacks the full picture needed to call it confidently.

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 0%, so the description must compensate. It explains the semantics of ids (element identifiers whose children and dependents cascade), which is genuinely useful, but doc_id is entirely unaddressed, including what its null default means or whether it falls back to the active document.

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 precise verb+resource ('Delete elements ... by id') and immediately scopes the action with its cascade boundary (children, attached connectors, labels, orphaned defs). An agent can distinguish this from update_elements or z_order without opening any schema.

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 never says when to reach for this tool versus siblings such as update_elements, run_actions, or import_file, nor any precondition beyond needing ids. Usage is only implied by the phrase 'by id'; there is no when/when-not guidance and no named 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?

With no annotations provided, the description carries the full burden and does meaningful work: it discloses the side effect of making the document current, the coordinate-system contract ('viewBox matches width/height, so coordinates are in unit'), and the exact artifact the background option creates (a full-page rect with id 'background'). It omits lifecycle concerns such as whether an existing unsaved document 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?

Three short sentences, front-loaded with the primary action and followed by the two non-obvious behavioral facts. No filler, though the backtick-heavy phrasing is slightly dense.

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?

Covers the creation action and coordinate/background semantics, but with no annotations and no output schema it leaves gaps around persistence (a save appears to be required via the document_save sibling) and the fate of any currently open document.

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 0%, so the description must compensate, and it does for all four parameters: it ties width/height to the viewBox, explains unit governs coordinates, and gives a concrete background example plus the resulting element id.

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 ('Create a new blank document') and adds the state effect ('make it current'). The word 'blank' implicitly distinguishes it from document_open, but 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 statement of when to use this versus document_open, import_file, or split, and no mention of prerequisites or what happens to an already-open document. Usage must be inferred entirely from the tool name.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the return values ('outline' and conditional 'notes') and a normalization behavior that does not change rendering, but omits error behavior, permission requirements, and whether the normalization alters the file on disk.

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

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

The description is front-loaded with the core action, then uses a compact colon list to explain return values and normalization cases. Every sentence earns its place and no information is repeated.

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 open tool with no output schema or annotations, the description supplies the essential purpose and return details. Minor gaps remain around error handling and the precise meaning of 'current' for downstream tools, but the core is complete.

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

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

Schema description coverage is 0%, so the description must compensate for the single 'path' parameter. It adds that the file must exist and can be .svg or .svgz, but does not clarify path format (absolute vs. relative) or other constraints.

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 ('Open'), resource ('existing SVG'), and scope ('.svg or .svgz') with the effect of making it current. The word 'existing' implicitly distinguishes it from document_create, and the return behavior is clearly bounded.

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 says what the tool does but does not specify when to use it versus alternatives such as document_create, inspect, or import_file. No prerequisites or exclusions are mentioned, leaving usage context entirely to inference.

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

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

No annotations are provided, so the description carries full burden. It usefully discloses the format written and the fallback target path when none is given, but is silent on overwrite behavior, permissions, and whether an existing file is replaced.

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; the format and target-path rule are stated immediately without redundancy.

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

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

For a mutation tool with no annotations and no output schema, the description covers the format and default path but omits the role of doc_id and any side effects on existing files, leaving gaps 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%, so the description must compensate. It clarifies the `path` parameter and its default fallback, adding real meaning, but `doc_id` is never mentioned, leaving one of two parameters 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?

States a specific verb (Save) plus resource (document) and the output format (Inkscape SVG), which distinguishes it from sibling document_open/document_create. It is clear what the tool does, though it draws no explicit contrast with siblings like export for other formats.

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 parenthetical implies when path is omitted (save in place to where it was opened/last saved), giving implied usage. It does not state when to prefer this over export, or any preconditions for saving.

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

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

With no annotations, the description must carry the full behavioral burden. It does disclose useful defaults (transparent background, only_ids=true, format inferred from extension, what 'region' covers), but says nothing about overwrite behavior, required document state, or output side effects, so key traits remain undisclosed.

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?

It is compact and information-dense, with the core action front-loaded and the option semantics following. The parenthetical shorthand is slightly cryptic in places, but no sentence is 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?

For a 12-parameter tool with zero schema descriptions, no annotations, and no output schema, the description covers the important export modes but leaves doc_id and text_to_path unexplained and gives no hint about the return value or file-overwrite behavior. Adequate but with clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does: it explains region [x,y,w,h] units, ids semantics, only_ids, area values, dpi vs width/height for PNG, and background hex format. It omits doc_id and text_to_path, but covers most of the 12 parameters with real meaning.

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

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

The first sentence names a specific verb and tool ('Export via Inkscape'), which clearly separates it from siblings like render_preview and document_save. The remainder enumerates export modes, reinforcing the purpose, though it never states outright that it writes a file to a 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?

It implies the usage context by explaining the region/ids/area alternatives and the only_ids default, which guides mode selection. However, it gives no explicit when-to-use or when-not-to-use guidance relative to siblings such as render_preview or document_save, leaving the agent to infer the distinction.

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

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

No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: output as one path per weight class in named layers, label placement outside the grid, reverse/lines switches, and default stroke widths and border behavior. It does not cover preview or document-target behavior (doc_id), but overall it is strong.

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?

Long but dense and front-loaded with purpose before detailed specs. Every section explains parameter behavior for a complex 11-param tool with no schema descriptions, so the length is justified.

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

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

Given no annotations and no output schema, the description is largely complete: it explains most parameters, result layers, and integration with plot. Minor gaps remain around preview, doc_id, and color, but an agent can invoke it correctly.

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

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

Schema coverage is 0% across 11 parameters, so the description must compensate. It thoroughly explains axis spec formats (linear/log), reverse, lines, weights, border, and label options, and names layer prefixes/result layers; however color, doc_id, and preview are left 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?

States a specific verb 'Draw' and resource 'grid / graph paper', plus scope 'inside rect [x,y,w,h]' and per-axis scale options. It distinguishes from sibling plot by noting plot should be used with grid=<id_prefix> to draw data on top.

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

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

Provides clear context: use to create graph paper background without computing line positions, and describes integration with plot for data overlay. It does not explicitly state when not to use it versus add_elements or other drawing tools, but examples like vertical-only lines for a bar chart give usage context.

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

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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly: it describes scaling, default position, how SVG layers/defs/clashing ids are handled, image linking/embedding, dpi defaults, object_fit options, and relative path resolution. This gives the agent a clear picture of side effects and defaults beyond structured data.

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

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

The description is a single dense paragraph but front-loads the core purpose and then details file-type-specific behavior efficiently. Every sentence appears to earn its place, though the density could be improved with some structure for easier scanning.

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

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

For a tool with 11 parameters, no annotations, and no output schema, the description omits explanation for several key parameters (id, layer, doc_id, parent, preview). It thoroughly covers file-handling behavior but is incomplete for an agent that needs to understand all inputs to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It explains 'at' (default 0,0), 'width'/'height' scaling behavior, 'embed' (true stores pixels), and 'object_fit' values, but it leaves 'id', 'layer', 'doc_id', 'parent', and 'preview' completely undefined. The description adds meaning for some parameters but misses many.

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

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

The description states a specific verb ('Place a file') and resource ('into the current document'), and explicitly distinguishes itself from sibling tools like document_open for whole documents and 'repeat rows_path' for data rows. An agent can immediately tell what this tool does and when it is not the right choice.

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

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

It gives explicit alternatives: 'For whole documents use document_open; for data rows see repeat rows_path.' This directly tells the agent when to use this tool versus its siblings, leaving no ambiguity.

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?

No annotations are provided, so the description bears the full behavioral burden. It discloses the returned information, which implies a read-only operation, but it does not explicitly state side effects, permissions, rate limits, or response format.

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

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

The description is a single, front-loaded sentence with no filler. It efficiently lists exactly what the tool provides.

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

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

For a simple, parameterless info tool with no output schema, the description covers the key return categories: Inkscape version/location, server version, and open documents. It is nearly complete, though it could mention the response shape or confirm it is a safe read operation.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain. The baseline for a parameterless tool is 4, and the description does not need to add parameter detail.

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

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

The description clearly enumerates the specific information the tool returns: Inkscape version and location, server version, and open documents. It is more specific than the name alone, but it does not explicitly distinguish this environment-info tool from siblings like inspect or render_preview.

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 content implies when the tool is useful (when version, location, or open document information is needed), but there is no explicit when-to-use guidance, no exclusions, and no alternatives named among the many sibling tools.

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

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: style is 'as rendered' with inheritance, bboxes are measured by Inkscape, and large layers/groups are summarised with counts and first/last ids (a truncation/summarisation trait the agent must know to expand results). It still omits read-only guarantees, error behavior, and which document is targeted by default, leaving gaps for a 5-param tool.

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

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

The main outline behavior is front-loaded, and the second paragraph cleanly enumerates the find filter modes with compact examples. It is information-dense with little waste, though the run-on first sentence is somewhat heavy.

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

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

With no output schema and no annotations, the description does the needed work of describing what the return contains (tree structure, per-element style, text, hrefs, bboxes) and how summarisation appears. The main remaining gap is the unspecified doc_id — the agent cannot tell from the description which document is inspected by default.

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 compensate for all five parameters. It explains max_children (summarisation threshold), layer (name or group id), and find with worked examples including colour-notation tolerance. But bbox and doc_id are never mentioned, leaving two parameters 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?

The description concretely defines the tool as producing a rendered document outline (layers, groups, elements with ids, style, text, use hrefs, and Inkscape-measured bboxes), which is far more specific than the bare name 'inspect'. It is clearly the structural/rendered read tool rather than a mutation or preview tool. However, it never explicitly contrasts itself with siblings like render_preview or document_open, so it stops 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?

It gives clear conditional guidance for its own two modes: the default tree, and 'find: a flat list of matching elements instead of the tree', plus 'To list one of them, pass layer ... and a larger max_children' when a layer/group is summarised. This tells the agent when to switch modes. It does not, however, state when to choose inspect over the other 22 sibling tools.

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

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

With no annotations, the description carries the full behavioral burden. It discloses placement behavior—the block stays where the first item is, or moves to `at`/`to`, and connectors follow—but does not explain the `preview` flag, document mutation semantics, permissions, or reversibility.

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

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

The description is front-loaded with the core purpose and then layers in item, gap, alignment, and placement semantics. It is dense but avoids filler, though its length is substantial given the compact parameter list.

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 12-parameter mutation-style tool with no annotations and no output schema, the description provides a useful mental model of item grouping and placement. However, it leaves several parameters and behavioral details (preview, doc_id, columns, return/error behavior) 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% for 12 parameters, so the description must compensate. It explains `items`, `gap`, `align`, `at`, `to`, `horizontal`, `vertical`, and `margin` meaningfully, but omits `columns`, `preview`, and `doc_id`, leaving important parameters 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?

The description states a specific action and resource: arranging items in a row, column, or grid with gaps, and clarifies that coordinate math is not needed. It does not explicitly distinguish itself from siblings like align, grid, or plot, but the core operation 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?

Usage is implied through the explanation of how items move and how placement is controlled, but there is no explicit guidance on when to use this tool instead of alternatives such as align or grid. The phrase 'no coordinate maths needed' hints at a use case but does not state exclusions or 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?

With no annotations, the description carries the full burden and does a good job: it discloses that a missing layer is created on top, that elements can be placed at top or bottom, and that relative order and visual position are preserved. It omits permissions, reversibility, and error handling, but covers the key behavioral traits for a move operation.

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

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

Two sentences with the core action front-loaded. Parenthetical details are efficient and add useful nuance without excessive length. Slightly dense but 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 no output schema, no annotations, and 0% schema description coverage, the description covers the core behavior but omits several parameters (ids, doc_id, preview) and error semantics. An agent can infer most of what to do but lacks full clarity on optional 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%, so the description must compensate. It clarifies that the layer parameter accepts a name (creating if missing) or a group/layer id, and that position is top or bottom. However, it does not explain the required ids array, the optional doc_id, or the preview parameter, leaving significant gaps.

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 (move) and resource (elements into a layer or group), with position control. It distinguishes from siblings like add_elements or z_order by focusing on moving existing elements into a container. Could be more explicit about what distinguishes it from update_elements, but the core purpose 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?

No explicit guidance on when to use this tool versus alternatives like z_order, align, or update_elements. Usage is implied from the description, but there are no stated conditions or exclusions.

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

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

With no annotations, the description carries the whole burden, and it does disclose real side effects: all content moves together, the page keeps its 0,0 top-left, background rects are resized and connectors follow. However it never explains what the `preview` flag does (whether it mutates or merely reports), which is the most important behavioral question for a mutating 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?

Two dense sentences, front-loaded with the core action and immediately followed by the margin format. No filler, though the second sentence's list of internals is slightly packed.

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 4-parameter mutation tool with no annotations and no output schema, the description covers the resize behavior and margin syntax but leaves doc_id and preview undocumented and gives no guidance on selection versus page_resize.

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 4 parameters, so the description must compensate. It handles `margin` well (one number, [vertical, horizontal], or [top, right, bottom, left], in user units) and clarifies `ids`, but says nothing about `doc_id` or `preview`.

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+resource ('Resize the page to fit the drawing') plus the scoping variant ('or only ids'). It is clear what the tool does, though it never names or contrasts with the sibling page_resize, which is the tool an agent must distinguish it from.

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 explicit when-to-use guidance and no mention of when to prefer page_resize over this fit operation, nor when to pass ids versus resizing the whole page. Usage must be inferred entirely from the wording.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that anchor='center' keeps the drawing centered, that top-left/none leave content in place, and that backgrounds are resized. But it omits critical mutation details: whether the operation is destructive, what happens to content falling outside the new page, how preview behaves, and any permission requirements.

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

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

The description is compact and front-loaded: it begins with the core action, then covers anchor behavior and background resizing. Every clause adds useful information, and there is 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?

For a five-parameter mutation tool with no annotations, no output schema, and 0% schema coverage, the description covers the core operation and anchor semantics well. It remains incomplete because doc_id and preview are undocumented, and broader side effects or safety behavior are not described.

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 compensate. It adds meaning for width, height, and anchor, including units and mode semantics, but leaves doc_id and preview unexplained. Partial compensation for three of five parameters justifies a middle score.

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

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

The description states a specific verb and resource: setting the page size in user units. It includes a concrete A4/mm example, making the operation unambiguous. However, it does not explicitly distinguish this from the sibling page_fit tool, so it falls short of a full 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 description explains the anchor options but gives no guidance on when to use this tool versus alternatives such as page_fit or layout. There are no prerequisites, exclusions, or workflow context to help an agent choose correctly.

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

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

With no annotations, the description carries the full burden and does disclose useful behavior: which object's id/style/layer survives per operation and that `result` lists the output ids. However it omits preview semantics (dry-run?), required permissions, and failure behavior across the 12 operations.

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?

Purpose is front-loaded, but the body is a dense run-on mixing per-operation outcome rules, a stray '(E22)' reference, and a return-value note mid-stream. Every sentence is relevant, yet the ordering is scattered.

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 mutating, multi-operation tool with no annotations and no output schema, the description covers outcome semantics better than most, but the unexplained preview flag and absent error/permission behavior leave real gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It explains a few operation values (difference, to_path, combine) but leaves ids, doc_id, and preview entirely unexplained, and the enum's other operations (division, cut, break_apart, simplify, flatten) unaddressed.

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+resource: Inkscape geometry operations applied to object ids, and names concrete operations (difference, union, to_path) that make the tool distinguishable from element-manipulation siblings like add_elements or z_order. It does not explicitly contrast itself with siblings, but the domain is 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 explains what certain operations do but never says when to choose this tool versus alternatives (e.g. split, run_actions) or when a given operation is appropriate. No prerequisites or exclusions are given.

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

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

With no annotations, the description carries the full burden and does so well: it documents default behaviors (label anchored right of the point unless label_offset given, marker_fill default white, halo default white), side effects ('recolouring a label later does not remove its halo'), generated id conventions, and a warning about points outside the grid. It misses whether the document is mutated, and says nothing about doc_id/preview behavior.

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

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

The purpose is front-loaded in the first clause, and the dense series/label/id detail is largely necessary given the 0%-coverage schema. It's a wall of text with heavy parenthetical nesting, but little is redundant.

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

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

For a complex plotting tool with no output schema and no annotations, the description covers series structure, label geometry and return ids/warnings well. It still leaves the grid/doc_id/preview parameters and the document-mutation semantics of the call unaddressed.

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 0%, so the description must compensate. It thoroughly documents `grid` ('that grid's id_prefix') and gives an exhaustive spec for each `series` entry, including keys, enums and defaults. However, `doc_id` and `preview` are entirely undocumented, leaving half the parameters 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?

States a specific verb+resource ('Plot data on a grid') and ties itself to a named sibling ('a grid made with the `grid` tool'), with the value proposition 'in DATA values — no coordinate maths' making the scope concrete. It's clear what the tool does, though it doesn't contrast against broader sibling drawing tools like add_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 implies usage via the prerequisite ('a grid made with the `grid` tool') and the value claim about avoiding coordinate maths, which tells the agent when this is preferable. However, there is no explicit when-not guidance or named alternative for non-grid-based plotting.

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

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

With no annotations, the description carries the full burden, and it does disclose real behavioral traits: white background, longest side scaled to max_size px, and that `ids`/`only_ids` change what is drawn. It omits any statement about permissions, rendering cost, failure modes, or how `area` affects output, leaving meaningful gaps for a mutation-free but resource-producing 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?

Two tight sentences with the output format and default background front-loaded, then the zoom controls. Dense but every clause carries information; the only cost is that the branching between `region`, `ids`, and `only_ids` is compressed into one run-on sentence.

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

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

No output schema, but the description compensates by describing the returned artifact (PNG, white background, max_size scaling). The main remaining gap is the undocumented `doc_id` and `area` parameters, which matter for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate, and it explains four of six parameters well: `region` as [x, y, w, h] in user units, `ids` as zooming to the area around them with everything still visible, `only_ids` as drawing only those objects, and `max_size` as the longest-side pixel cap. It says nothing about `area` (page vs drawing) or `doc_id`, leaving two parameters undocumented 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?

States a specific verb+resource ('Render to a PNG image'), and the phrase 'you can look at' signals this is a preview artifact rather than a deliverable export, which implicitly separates it from the `export` sibling. It stops short of explicitly contrasting itself with `export` or `inspect`, so an agent must infer the distinction.

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 explicit when-to-use guidance or named alternative; the closest signal is the implicit framing 'you can look at', which suggests a visual-check use case. Nothing states when to prefer this over `inspect`, `export`, or `inkscape_info`, so 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?

With no annotations, the description carries the full burden and thoroughly discloses behavior: templating and replacement rules, id generation, parent/fit_to/clip references, row grouping, step/grid/cell placement, mirror semantics, rows_path file input, and returned values. It does not cover permissions or rate limits, but for a non-annotated tool it is unusually rich.

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 long and dense, but it front-loads the core purpose and each sentence adds technical detail needed for a complex 13-parameter tool. Some parameter explanations could be more scannable, but there is little pure repetition or filler.

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

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

Given high complexity, no annotations, and no output schema, the description explains return values and many mechanics in useful detail. It is still incomplete for several parameters, so an agent may need to infer layer, doc_id, preview, and defaults behavior.

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 compensate, and it explains template, step, columns, order, cell, mirror, rows_path, and id_prefix in depth. It leaves rows, layer, doc_id, preview, and defaults unexplained, so the compensation is strong but incomplete.

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 ('Stamp') and resource ('block of elements once per data row') and gives concrete use cases such as timelines, card grids, tables, legends, and map symbols. It distinguishes itself from sibling add_elements by referencing its template specs while emphasizing one-call row repetition.

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

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

Provides clear context through use-case examples and the 'in one call' framing, implying when to use it over repeated add_elements calls. However, it does not explicitly state when not to use it or name direct alternatives beyond referencing add_elements for template specs.

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

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

With no annotations, the description carries the full burden and does add real behavioral value: it discloses that file/export/window/quit actions are blocked and that org.inkscape.* extensions act on the whole document. However, it says nothing about the `preview` flag's effect, error behavior, or what a run returns, which is a notable gap for a mutation 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?

Three dense sentences, front-loaded with the defining "Escape hatch" label, then prerequisite, restrictions, and a caveat. Almost every clause earns its place; only the trailing extension caveat is arguably a second-order detail.

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

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

For a 4-param, no-annotation, no-output-schema tool, the description covers purpose, prerequisites, and action restrictions well, but omits the meaning/effect of `preview` and `doc_id` and offers no sense of the result. Adequate but with clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It gives meaningful semantics for two of four params: `actions` (raw Inkscape action syntax, with examples) and `select` (ids must be selected before actions run). It leaves `doc_id` and `preview` completely unexplained, so the compensation is only partial.

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+resource ("run raw Inkscape actions") and frames it distinctively as an escape hatch with two concrete examples ("object-align:left last", "transform-rotate:30"). The example action names overlap with siblings like align/path_operation, but the "raw actions" framing makes the distinction clear without opening a schema.

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 "escape hatch" framing tells the agent this is the fallback when dedicated tools don't cover a need, and it specifies the prerequisite "after selecting `select` ids". It also states when NOT to combine actions with select for extensions. It stops short of naming which sibling tool to prefer, so no explicit routing like the top-tier example.

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

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

With no annotations, the description carries the burden and does well: it discloses that one rect is created per cell with sequential ids row by row, that they are placed in `layer`, that they are 'invisible unless style' supplies a fill/stroke, and that an element region is its measured box (stroke included). It omits permission/undo/error behavior, so not a 5.

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

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

Purpose and the 'no positions' value proposition are front-loaded, and the rest is dense with concrete examples rather than filler. The multi-idea sentences (spec parsing plus workflow plus return values) run long, but nearly every clause earns its place.

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

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

For a 10-parameter mutation tool with no annotations and no output schema, the description covers the essential semantics, explains the return value ('returns the cells [x, y, w, h] and their ids per row'), and supplies a worked table recipe. doc_id and preview remain unexplained, leaving a modest gap.

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

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

Schema description coverage is 0%, so the description must compensate — and it does, explaining region forms, margin/gutter accept scalar or tuple, rows as counts or ratio lists, heights as row ratios, style fields, and id_prefix via the '-1, -2' example. Two parameters, doc_id and preview, are undocumented 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?

States a specific verb and effect — 'Divide a region into named cells — without computing any positions' — then anchors it with concrete use cases (comic panels, dashboard tiles, poster columns, table grids). An agent can distinguish this from the sibling 'grid' and 'layout' tools from the opening clause alone.

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?

Gives strong usage context: the 'without computing any positions' framing, the guidance to consume the returned ids as targets for clip/align/place/fit/connect, and a concrete table workflow ('split the header strip... then repeat the data rows'). It stops short of an explicit 'use this instead of grid when...' exclusion, so it is clear context rather than full routing.

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

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

With no annotations, the description carries the full burden. It does disclose genuinely useful mutation semantics: partial updates (only given keys change), style shorthand merging, and the empty-string idiom to clear a transform. It does not cover whether updates are reversible, error behavior on a missing id, or what the operation returns.

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

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

Four short sentences, front-loaded with the core purpose, and each adds a distinct piece of information (payload shape, partial-update rule, style merge, transform clearing) with no padding.

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

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

For a no-annotation mutation tool with no output schema, the description covers the update payload but omits the target scoping (`doc_id`) and the dry-run flag (`preview`) — the latter being materially important since a preview mode suggests a non-committal path the agent should know about.

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 compensate, and it explains the structure and merge semantics of the `updates` payload ('id' plus any element-spec keys, partial change). However, `doc_id` and `preview` receive no mention at all, leaving a third of the parameters undocumented 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?

States a specific verb+resource ('Change existing elements') that cleanly separates it from add_elements and delete_elements in the sibling list. The distinction is inferable from the sibling names rather than stated explicitly, which keeps it just 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?

No when-to-use guidance and no alternatives named. It never says to use update_elements instead of add_elements/delete_elements, nor what preconditions apply (does the element have to exist?). Usage must be inferred entirely from the name.

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

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

With no annotations, the description carries the full burden and does disclose non-obvious side effects: above/below may silently move the element into the target's layer/group while preserving visual position, and multiple ids retain their relative order. It also states it returns each id's position. However, it says nothing about the `preview` flag's effect on mutability, error behavior, or reversibility.

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?

Dense and front-loaded: the core purpose leads, then a compact per-operation glossary, then the return note. The telegraphic style ('forward/backward: one step past the next object it overlaps') is effective rather than wasteful. Slightly clipped for a reader unfamiliar with the drawing model, but no sentence is filler.

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

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

For a six-operation mutation tool with no annotations and no output schema, the description covers the operation semantics thoroughly and handles the return value ('each id's position'). The obvious gap is the undocumented `preview` parameter, which matters for a mutation tool, and the unmentioned `doc_id` scoping.

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 compensate and it partially does: it defines three of the six enum values in detail, clarifies that `ids` is an ordered set preserving relative order, and explains `target`'s role for above/below. It never mentions `doc_id` or `preview`, leaving two of five parameters entirely undocumented in both schema and prose.

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+resource ('Change stacking order') and immediately clarifies it as 'what is drawn on top', which disambiguates from siblings like align or move_to_layer that also reposition elements. It does not explicitly name a sibling to route against, so it falls just short of the top mark.

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?

Goes well beyond generic guidance by explaining WHEN each operation variant applies: front/back operate within the element's own layer/group, forward/backward move one step past the overlapping object, and above/below are relative to `target`. This is genuinely decision-relevant. It stops short of 5 because there is no 'when not to use this tool' or explicit alternative (e.g. move_to_layer).

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