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

With annotations only declaring a general mutation profile (readOnly=false, destructive=false, idempotent=false), the description adds real behavioral texture: stroke construction from pressure-carrying points, the flatten/angle calligraphy nib, jitter wobble, low-hardness spray, and the preview parameter's image-reply behavior. It also reassures that layers/filters/undo apply uniformly, implying recoverability. It does not cover failure modes or the effect of large point counts.

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 paragraphs, front-loaded with the core mental model ('Mouse-drag feel') before parameter effects and targeting. Every sentence carries information, though the interleaving of parameter tips is slightly scattered rather than structured.

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

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

For a 15-parameter mutating draw tool with no output schema, the description covers targeting, coordinate/pressure format, stylistic parameter effects, preview return behavior, and shared layer/filter/undo semantics. Only minor gaps remain, such as seed/opacity/spacing/blend usage, which the schema itself documents.

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 67% across 15 parameters, so the schema handles much of the load, but the description adds interpretation the schema lacks: the third point value as pressure 0..1, and the combined semantics of flatten+angle (nib), jitter (wobble), and hardness (spray). This is meaningful value beyond field-level descriptions.

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

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

The description names a specific verb+resource ('soft stamps along a polyline', 'Mouse-drag feel') and titles the tool as a freehand brush stroke, which an agent can distinguish from vector siblings like paint_line or paint_path. It also anchors the tool by naming paint_canvas as the source of the canvas. It stops short of explicitly contrasting when to pick this over paint_stamp or paint_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 states the prerequisite that the canvas is 'created with paint_canvas' and that a layer index is optional, and notes that layers/filters/undo behave the same across drawing tools. There is no explicit when-to-use vs when-not guidance or direct alternative comparison among the many paint_* siblings.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=true, so the safety profile is partly covered. The description adds real behavioral context beyond that: close only drops the canvas from memory while 'files stay on disk', save writes the layered .paint document, open reads from the paint root, and create's layer initialization is described. It stops short of error/failure behavior or permission requirements.

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

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

The opening sentence states the scope, then a compact action table carries all detail with no filler. The most important constraint (canvas must exist first) is placed last as a deliberate caveat, and every line 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 7-parameter, 8-action tool with no output schema and 86% schema coverage, the description covers all actions, prerequisites, and persistence semantics. Minor gaps remain around return contents for info/history and error conditions, but nothing critical to correct invocation is missing.

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

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

Schema coverage is 86%, so the baseline is 3, but the description adds genuine value by mapping which parameters apply to which action (create {name, width, height, background}, open {path}, save {name, path?}) and clarifying semantics such as background=null for transparent and the initial layer stack. This goes beyond the per-field schema text.

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 the exact resource (canvas) and enumerates eight concrete lifecycle verbs (create, info, list, open, save, close, files, history), making it immediately distinguishable from the drawing siblings like paint_line or paint_fill. An agent can tell this is the lifecycle/administration 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?

Each action is annotated with its purpose and required parameters, and the closing sentence gives the key prerequisite: 'A canvas must be created (or opened) before any drawing tool can be used.' That is strong routing guidance, but there are no explicit exclusions or pointers to which sibling handles subsequent operations (e.g. use paint_export instead of save for raster output).

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, so the safety profile is covered; the description adds that a null color erases to transparency and that `shape:'ellipse'` with `radius` rounds the mask. It also reassures that undo and layers behave consistently across drawing tools, which is useful non-obvious context, though it doesn't state reversibility or side effects of the wipe explicitly.

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 clauses front-load the core wipe/erase behavior before the secondary shape and canvas targeting details. No redundant filler, though the last sentence about layers/filters/undo is slightly generic.

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 9-parameter mutation tool with no output schema and no annotations on required auth, the description covers the essential behavioral contract: what gets wiped, what null color does, and how targeting works. Missing only minor details like opacity interactions and preview semantics, which the schema already handles.

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?

At 67% schema coverage it goes beyond the schema by explaining the omitted-`area` fallback, the null-color erase behavior, and how `shape` and `radius` interact to round the mask. It does not explain `opacity` or the preview options, but the schema already documents those.

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 ("Wipes a rectangle ... to `color`") and the erase-to-transparency semantics, which distinguishes it from a plain fill. However, it never names sibling tools like paint_fill, paint_rect or paint_pixel_grid, so an agent must infer the boundary itself.

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 useful conditional behavior (whole layer when `area` omitted, transparency when `color:null`) and the canvas prerequisite ("created with paint_canvas"), but offers no explicit when-to-use-this-instead-of-X guidance against the many overlapping paint_* siblings.

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

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

Annotations already declare this is a non-readonly, non-idempotent, non-destructive mutation. The description adds useful context beyond that - the canvas must have been created with paint_canvas, a layer index is optional, and undo applies - but it never states what happens on an unknown canvas or that the operation commits to the canvas surface.

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 geometry semantics that matter most, no filler. The second sentence is slightly generic (it explains shared cross-tool behaviour) but still earns its place as a routing hint.

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 18 params, no output schema, and existing annotations, the description covers the key ambiguities: shape mode selection, arc/pie/rotation semantics, and canvas/layer targeting. It is nearly complete, missing only error/precondition behaviour and a note on the preview return image.

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

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

With only 44% schema coverage, the description carries real weight and does so for the ambiguous geometry params: it maps radius to circle, rx/ry to ellipse, explains start_angle/end_angle are degrees forming an arc, pie closes to centre, and rotation tilts. This compensates well for the low coverage, though cx/cy and stroke_width remain 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 pins down the resource (circle vs ellipse vs arc) and the exact parameters that select each mode (radius, rx/ry, start_angle/end_angle, pie, rotation), so an agent immediately knows what this draws. It stops short of an explicit verb or drawing attention to how it differs from siblings like paint_path or paint_brush, which handle other geometry.

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 context on how to target the operation: name the canvas (created via paint_canvas) and optionally a layer index, and notes that layers/filters/undo behave like every other drawing tool. There is no explicit guidance on when to choose this over alternative shape tools or what preconditions must hold (e.g., canvas must already exist).

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 non-read-only, idempotent, non-destructive, closed-world. The description adds genuinely new behavior: the return shape (path under paint root plus preview of what was written), the lossy nature of svg for raster-only steps, and the reported unvectorised operations. It omits overwrite/error behavior for existing target paths, 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?

Front-loaded with the core action and format list in the first clause, then return value, then the svg caveat. Dense but every sentence carries actionable content; the svg/embed explanation is slightly long but justified for a lossy-conversion caveat.

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

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

No output schema exists, yet the description explicitly states what is returned (path plus a preview of exactly what was written), and it covers the format-specific edge cases that an agent must know before calling. Nothing essential is missing for an 8-parameter export tool.

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

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

Schema description coverage is 100%, so every parameter including format, flatten, preview, quality and embed_raster_fallback is already documented in-schema; baseline is 3. The description reinforces format and svg-fallback semantics but mostly restates what the schema states, adding only marginal 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?

States a concrete verb (write out) and resource (the canvas file), enumerates the exact output formats, and implicitly distinguishes itself from paint_import. An agent knows immediately this is the persistence/export step of the paint family.

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 conditional guidance: which formats are available, what svg preserves vs drops, and the embed_raster_fallback workaround for raster-only steps. It stops short of naming sibling alternatives (e.g. paint_import or paint_preview) or stating when to prefer export over them, so it is context-rich but not fully 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 annotations only declaring the safety flags, the description adds real behavioral context beyond them: the meaning of tolerance as summed channel distance, that contiguous:false affects every matching pixel of the layer, and that mode:'replace' swaps rather than overpaints. It stops short of discussing return/preview behavior or cost on large canvases.

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-loads the core identity ('Paint bucket.'), then devotes each sentence to a distinct parameter behavior with no filler. The closing line about layers/filters/undo is slightly generic but still useful orientation.

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 no output schema, the description foregrounds the confusing semantics and relocates return-format detail to the preview parameter. What an agent needs to invoke a bucket fill correctly is essentially present.

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

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

Schema covers ~50% of params by description, and the prose compensates by explaining the three undocumented non-obvious ones (tolerance, contiguous, mode) with concrete examples ('60 ≈ shades of the same hue'). x/y/color are self-evident and blend/opacity/preview already carry schema descriptions.

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

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

Opens with a specific verb+resource, 'Paint bucket', which unmistakably identifies a flood-fill/recolour operation and implicitly separates it from the line/rect/brush/path siblings. It does not explicitly name a contrasting sibling, keeping 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?

Usage is implied rather than stated: it notes the canvas is 'created with paint_canvas' and that layers/filters/undo behave uniformly, but gives no explicit when-to-use-this vs paint_pixels/paint_rect guidance or prerequisites. Adequate but with clear gaps.

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 the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds real value beyond that by noting that 'undo works the same for every drawing tool', implying the operation is reversible, which is exactly the behavioral context an agent needs 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?

Front-loads the filter list then moves to per-parameter semantics and targeting context. The long enum enumeration is necessary but makes it dense; otherwise little waste.

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 9-parameter, nested-schema mutation tool with no output schema, the description covers the important semantics (filter list, amount units, area, level) and the canvas/layer targeting model. The unexplained `seed` parameter is the one notable 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 coverage is only 56%, so the description must compensate. It does so for the undocumented `amount` (units vary per filter) and `level` (posterize/dither levels) parameters, but leaves `seed` unexplained 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?

States a specific verb (filters) and resource (a layer) and enumerates all 18 filter modes by name, making it unmistakably the image-filter tool rather than a sibling like paint_transform or paint_pixels. The mention of paint_canvas as the canvas source anchors it in the family.

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 tells the agent how to target the canvas and layer, and notes that layers/filters/undo behave the same across drawing tools, but gives no explicit when-to-use-vs-alternative or when-not guidance. Usage is implied rather than 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?

Annotations already declare it is a non-destructive, non-idempotent mutation, so the safety profile is covered. The description adds useful context that undo applies ('undo work the same for every drawing tool'), but says nothing about what happens to existing pixels under the gradient or any auth/permission requirements.

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

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

Two compact sentences, front-loaded with what the tool does, then the targeting rule and cross-tool behavior. 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 14-parameter, nested-schema, no-output-schema tool this is thin. It omits the stops-vs-colors semantics, preview behavior, and blend-mode intent, leaving the agent to reconstruct a meaningful call primarily from the schema.

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

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

Schema coverage is 79%, so the schema does most of the work for the 14 parameters. The description clarifies canvas targeting and the `area` option, but never explains the important distinction between `stops` (positioned) and `colors` (evenly spaced) or when to use `radius`/`to`/`from` — a real gap for a parameter-heavy 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?

States a specific verb (paint) and resource (linear or radial gradient) with scope (canvas or an `area`) and use-case examples (skies, glows, metal, shadows). This clearly distinguishes it from sibling tools like paint_fill or paint_rect.

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 states the prerequisite that the canvas is created with paint_canvas and that a layer index is optional, and notes cross-tool consistency of layers/filters/undo. However, it never says when to prefer a gradient over paint_fill or other paint_* alternatives, so the routing guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description's 'in-server documentation, no round trip to GitHub' usefully reinforces the offline/local nature, but it says nothing about output shape or size of the returned reference. With annotations carrying the behavioral load, a 3 is appropriate.

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

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

One framing sentence then a compact topic list; the purpose is front-loaded and no sentence is wasted. The parenthetical glosses double as both topic definitions and parameter documentation, which is efficient rather than 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 single-optional-parameter help tool with no output schema, the description supplies what an agent needs to decide whether to call it and which topic to request. It could be slightly stronger by hinting at the depth/format of the returned documentation, but nothing essential is missing.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it does: each enum value is annotated with what it contains (ops = every operation and its fields, colors = formats and named palette, workflow = how to plan a drawing, examples = copy-paste batches). Only blend, filters, svg, and limits are named without elaboration, which is a minor gap at one optional, defaulted 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?

States plainly that this is in-server documentation and enumerates the exact topics available, so an agent immediately knows this is the reference/help surface rather than a drawing op. It is cleanly distinguishable from all 24 paint_* siblings (paint_line, paint_fill, etc.) that mutate the canvas.

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 topic list implicitly tells the agent which call to make for which need (e.g. 'workflow (how to plan a drawing)', 'examples (copy-paste batches)'), and 'no round trip to GitHub' signals when to prefer this over external lookup. There is no explicit when-not or preconditions statement, but for a help tool the routing is clear.

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

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

Annotations already declare the mutation/creation profile (readOnlyHint=false, idempotentHint=false), and the description usefully adds that the format is sniffed from raw bytes (png/jpg/bmp regardless of extension) and that the call either creates a canvas or appends a layer to an existing one. Missing is any note on overwrite/error behavior when the named canvas already exists, or how the `preview` reply interacts with the result, though the schema covers the latter.

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 with zero filler. The primary intake decision is front-loaded, and the state-changing consequence (creates canvas vs adds layer) lands last as the closing clause.

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 5-parameter, 100%-documented, no-output-schema tool whose annotations cover the mutation profile, the description supplies exactly the missing runtime context: input mode selection, format sniffing, and create-vs-append outcome. Nothing an agent needs to invoke it correctly is absent.

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

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

Schema description coverage is 100%, so baseline is 3, but the description genuinely adds semantic value: it explains the path-vs-data decision criterion and that declared extensions are not trusted (format sniffed from bytes), and it maps `canvas` to create-vs-append semantics. It leaves `preview` and `as_layer` entirely to the schema.

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

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

States a specific verb and resource (importing a picture into the paint workspace) and is immediately distinguishable from reverse operations like paint_export by naming the two intake modes (`path` for files, `data` for held bytes). It stops short of drawing the boundary with closer siblings such as paint_layer or paint_canvas, which handle the same canvas/layer structure this tool also touches.

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 for choosing between the two input modes: `path` for a file under the paint root, `data` with base64 when the agent already holds the bytes. It does not, however, name any alternative tool or state when not to use import (e.g. routing to paint_layer for in-memory composition), so it is clear context without 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?

Annotations already declare the safe/idempotent read profile, so the description's job is reduced; it adds a cost-efficiency trait ('cheaper than a thumbnail') that the annotations do not convey. It does not describe the shape of the returned numbers, but the cost context is a meaningful addition.

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 no filler; the query modes are front-loaded and the cost trade-off is placed last as a tie-breaker. 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 read tool with full annotation coverage and a rich 5-parameter schema, the description supplies enough: it names what can be asked and the cost rationale. The absence of any note on result shape (e.g. histogram ordering tied to 'top') is the only minor gap, acceptable given no output schema.

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

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

Schema description coverage is 100%, so the schema already documents canvas, points, region, top and layer. The description loosely maps its query modes (points, region, histogram) to those parameters but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific read operation ('read pixels') and enumerates the exact queries it answers: colour at points, statistics and bounding box, colour histogram of a region. This clearly separates it from the mutating siblings and from the visual-preview sibling paint_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?

Explicitly frames when to choose it over the thumbnail alternative ('Cheaper than a thumbnail when you only need numbers'), giving a clear selection criterion. It does not, however, address the other read-oriented siblings like paint_pixels or paint_pixel_grid, so guidance is strong but not exhaustive.

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

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

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=false), so the description only needs to add context. It usefully discloses the stack ordering (index 0 is the bottom layer) and that layers, filters and undo behave uniformly across drawing tools, which is genuine behavioral information. It does not mention what 'remove' or 'merge' destroy or any permission/reversibility caveats for mutations.

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 action list is front-loaded and the remaining sentences are dense and information-bearing (ordering, canvas targeting, uniform behavior across tools). It is efficient overall, though the final sentence about filters and undo working the same everywhere is slightly tangential to a layer-management 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?

For an 11-parameter multi-action tool with no output schema, the description covers the action vocabulary and indexing but does not state per-action requirements (e.g., that move needs 'to', remove needs an 'index') or what 'list' returns. It is adequate but leaves the agent to infer which parameters pair with which action.

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

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

Schema description coverage is only 45% (uncovered: name, blend, index, action, opacity, visible), so the description must compensate. It does so by mapping the 'set' action to its sub-parameters (rename, opacity, blend, visible) and by defining index semantics and layer ordering, adding real meaning beyond the bare schema types.

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 the specific resource (layers) and enumerates the exact action verbs the tool supports: list, add, remove, select, move, merge, set. It separates itself from siblings like paint_canvas (which creates the canvas) and paint_filter/paint_undo while clarifying that layer state is the shared substrate. An agent can identify the tool's role 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?

It tells the agent to target the canvas by name (created with paint_canvas) and optionally a layer index, and the action list effectively tells the agent which verb to pick. However, it never states when to prefer this tool over alternatives such as paint_ops or how layer actions interact with drawing tools, so it stops short of explicit when/when-not guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the write/safety profile is covered. The description adds that layers, filters and undo behave identically across drawing tools, which is useful context, but it omits behavioral detail beyond that (e.g. whether re-issuing the same call stacks strokes, what preview 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?

Three short sentences, front-loaded with what the tool draws and the key optional behaviors, then a shared-context note. No wasted filler, though the opening 'One segment' fragment relies on the title to be understood.

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 18 parameters, no output schema and low schema description coverage, the description should carry more weight. It covers the core stroke concept and canvas/layer targeting but leaves the preview/return behavior and half the styling parameters unexplained, which is a meaningful gap for a tool this wide.

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

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

Schema coverage is only 39% across 18 parameters, so the description must compensate. It clarifies dashes ([8,6] example), arrow head, hardness=0 airbrush edge, canvas-by-name and layer index, but leaves many parameters (preview, opacity, blend, cap, dash_offset, arrow_size, width) undocumented in the description as well.

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 conveys a single straight-line segment with optional dashes and arrow head, and the title reinforces it as 'Paint: Straight line'. It does not explicitly say 'draws a line', which is slightly elliptical, and it does not name the sibling it differs from (e.g. paint_path for multi-segment strokes).

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

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

'For rules, grids and outlines' implies intended use cases, and 'Target the canvas by name (created with paint_canvas)' gives a precondition. However, there is no explicit when-not guidance nor any routing against near siblings like paint_path or paint_brush, so usage is only implied.

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

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

With annotations covering the mutation/safety profile (readOnlyHint=false, destructiveHint=false), the description adds real context beyond them: the return shape (summary line per op plus one preview) and undo semantics ('rolls back the whole batch step by step'). It also flags the layer-before-use ordering constraint, which the annotations do not.

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 purpose, then the ops structure, layer note, example, and return/undo behavior in a logical order. Longer than a minimal sentence but each block (op list, example, return note) earns its place for a complex batch 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?

For a complex nested-op tool with no output schema, the description covers purpose, item structure, layer handling, and return format adequately. Minor gaps remain (no mention of the 400-item cap or how op-level errors surface beyond stop_on_error), but the essential call-shaping context is present.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds substantial meaning: it enumerates the available op names, defines the {op, ...params} item shape, shows a concrete multi-op example, and explains the per-item 'layer' field. Op-specific parameters are deferred to the individual tools, which is a reasonable scope boundary.

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 ('Run many drawing operations in ONE call') and frames the benefit ('cheapest way to build a whole scene'). It explicitly distinguishes itself from the 16 sibling paint_* tools by noting every op also exists as its own tool, so an agent can route correctly 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?

Clearly frames when to reach for this tool (multi-op scene in one call) versus the single-op siblings, and explains the layer prerequisite. It stops short of explicit when-not-use guidance (e.g., cost limits, maxItems of 400), but the batch-vs-single tradeoff is well conveyed.

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 the mutation/safety profile (readOnly=false, destructive=false, idempotent=false), and 'Draw' is consistent with a write op. The description adds genuine context that 'layers, filters and undo work the same for every drawing tool,' disclosing recoverability. It does not explain whether it appends a new shape vs modifies existing art or what the call returns, so it's useful but not 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?

Two short paragraphs, front-loaded with the core purpose and SVG command reference, then operational context. Little waste; every sentence is relevant, though the second paragraph's generalities apply to all drawing tools.

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 15-parameter tool with no output schema, the description covers the canvas prerequisite, layer targeting, and undo/filter behavior, but omits any mention of return/preview behavior (the preview param exists in schema) and coordinate/scale semantics. Adequate but with clear gaps for a tool this complex.

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 73%, so the schema already carries most parameter meaning (fill/stroke gradient shapes, preview modes, etc.). The description adds the SVG command set (M L H V C S Q T A Z, lowercase=relative) and field names (fill, stroke, dashes, even-odd, layer), but largely restates what the schema documents. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Draw SVG path d data') and characterizes the tool's niche as 'the compact way for an agent to place curved or complex art,' which loosely distinguishes it from sibling primitives like paint_line/paint_rect/paint_ellipse. Differentiation is implied through the 'curved or complex' framing rather than an explicit sibling callout, 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?

It notes the canvas must be 'created with paint_canvas' and that a layer index is optional, which is useful context. However, it never states when to choose paint_path over paint_polygon/paint_line/brush for a given shape, leaving alternatives 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?

Annotations already declare this is a non-read-only, non-destructive, non-idempotent mutation, so the safety profile is covered. The description adds a cross-cutting behavior note ('Layers, filters and undo work the same for every drawing tool') but says nothing about what a re-draw overwrites or the preview/opacity effects.

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

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

Front-loaded with the core mechanism in the first sentence, then a short second paragraph on targeting and shared behavior. Tight and purposeful, with only the 'Perfect for...' clause bordering on 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 10-param tool with nested palette objects and no output schema, the description explains the drawing model and cross-cutting layer/filter/undo behavior well. Minor gaps remain around preview/opacity/blend, though those are largely documented in the schema.

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

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

Schema coverage is 70% and the description meaningfully extends it: the character→colour lookup rule, the skip set ('space and `.`'), the cell block sizing, and the origin start point, which frames how rows/palette/cell/origin interact. It adds real semantics beyond the schema for the core params.

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?

State a specific verb and resource ('Draws a sprite') and explains the exact mechanism: each character of `rows` maps through `palette`, skipped chars, and a `cell`x`cell` block at `origin`. This is specific enough to distinguish it from siblings like paint_pixels, paint_stamp, and paint_rect 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?

Gives clear context — 'Perfect for sprites, tiles, icons and logos' — and states the canvas prerequisite ('created with paint_canvas') plus the optional layer index. It stops short of naming when to prefer this over the close sibling paint_pixels or when not to use it.

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

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

Annotations already establish the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower. The description adds real behavior beyond them: writes are exact with no blending (existing pixels are overwritten, alpha does not composite), and undo applies uniformly across drawing tools, which reassures the agent about 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?

Two short paragraphs, front-loaded with the exact-write/no-blend semantics before the targeting details. The pixel-format examples are mildly redundant with the schema, keeping it out of 5 territory.

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 5-parameter mutation tool with no output schema, the description covers canvas targeting, layer selection, pixel payload semantics and undo, which is most of what an agent needs. It is silent on the preview/preview_size reply behavior, though the schema describes those fields.

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 80%, so the schema already documents canvas, layer, pixels, preview and preview_size. The description's restatement of the three pixel payload shapes mirrors the anyOf union in the schema and adds no format detail beyond it; baseline 3 is appropriate.

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

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

States a specific verb and resource ('Exact pixel writes') and immediately qualifies it with 'no blending', which tells the agent it is a raw overwrite rather than a blend-capable brush. It implicitly separates itself from blending siblings like paint_brush/paint_fill, but never names an alternative tool, 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?

'Use for pixel art and small fixes' gives clear usage context, and it notes the canvas must be created with paint_canvas. However, it never states when to prefer a sibling primitive (paint_rect, paint_fill, paint_line) instead, so the when-not guidance is only implied.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the mutation/safety profile is covered. The description adds the useful semantic that closed:false strokes the outline only, but omits behavioral traits the annotations don't cover, such as the cost/limits of up to 20,000 points, or how preview replies affect the response.

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 paragraphs with the core capability front-loaded and zero filler; the second paragraph neatly packages prerequisites and cross-tool consistency. Slightly compressed at the expense of routing guidance, but nothing 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 mutation tool with no output schema, the description covers the essentials (canvas targeting, closed behavior, undo consistency) and the schema carries most parameter detail at 83% coverage. It still leaves gaps around point-count limits and how the preview parameter changes the returned result, which an agent would want before calling 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 83%, so the baseline is 3. The description does add meaning beyond the schema for closed (which has no schema description at all: 'closed:false strokes the outline only') and restates the points format, but it says nothing about the gradient, blend, opacity, or preview parameters that the schema documents.

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 line gives a specific verb+resource ('Any many-sided shape from [x,y] points') and concrete examples (stars, arrows, speech bubbles) that separate it from the fixed-shape siblings like paint_rect and paint_ellipse. It never names an alternative tool by name, so the differentiation is inferential rather than explicit.

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 states a prerequisite ('Target the canvas by name (created with paint_canvas)') and a cross-tool invariant (layers, filters and undo work the same for every drawing tool), which is genuinely useful context. However it never says when to prefer this over paint_path, paint_line, or paint_rect, so an agent choosing between free-form drawing tools gets no routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, and 'without changing anything' is consistent with them. The description adds the layer-only viewing tip but says nothing about what the return payload looks like (image data vs URL, size limits, cost of full previews), which is the main behavioral unknown for a preview 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 short sentences, front-loaded with the read-only guarantee, then the usage scenarios, then the one option worth calling out. 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 5-parameter tool with a nested region object and no output schema, the description is minimal: it never explains what the returned 'picture' actually is, and the auto/thumb/full preview enum is left undocumented in both description and schema. Annotations cover the safety profile, but the return-shape gap keeps this at minimum-viable.

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 80%, so the schema already documents layer, canvas, region and preview_size. The description's 'Set layer:true' restates the schema's own layer description and adds no new syntax or format detail for preview/region.

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 ('Return the current picture') plus the key invariant ('without changing anything'), which clearly separates it from mutating siblings like paint_line or paint_clear. It does not, however, contrast with the potentially overlapping paint_inspect or paint_export, so sibling routing is only partly resolved.

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 concrete use cases — checking work, comparing against a reference, re-reading after a long session — so an agent knows when to reach for it. There is no explicit when-not guidance or named alternative (e.g. for reads that should not return an image), so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the write-safety profile is covered. The description adds useful behavior—corner rounding semantics and that fill/stroke accept a colour or gradient object—but omits what happens to existing canvas content and how the image preview reply is produced.

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 paragraphs that front-load what the tool draws, followed by targeting details. Sentences are efficient, though the trailing layers/filters/undo sentence is somewhat generic boilerplate.

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 14-parameter drawing tool with no output schema, the description covers canvas targeting, layer selection, rounding, and fill/stroke types. It is adequate but leaves assorted parameters (blend, opacity, preview output behavior) to the schema.

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

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

Schema coverage is 64%, so the schema documents many parameters itself. The description meaningfully clarifies the radius array ordering and that fill/stroke accept colour or gradient, adding value, but several params (blend, opacity, preview, stroke_width, layer) get no treatment in the 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 verb+resource ('Filled and/or outlined rectangle') and details how it is shaped (radius, fill/stroke), which lets an agent distinguish it from shape siblings like paint_ellipse or paint_polygon. It does not explicitly name an alternative for the same task, 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?

It gives context for targeting ('Target the canvas by name (created with paint_canvas)') and notes layers/filters/undo behave uniformly across drawing tools, which implies shared usage. However, there is no explicit when-to-use-this-vs-another-shape guidance or exclusion conditions.

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 the safety profile (non-destructive, idempotent, open-world), so the description only needs to add context — and it does: it discloses that only 127.0.0.1 is bound (a real security-relevant constraint), that repaint cadence is once per second, and that status returns the URL. It does not say what happens on a port collision or on stopping an already-stopped server, so it falls 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?

Three short sentences, zero filler, and the core purpose is front-loaded ahead of the binding and status details. Every clause carries information an agent or human caller needs.

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

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

For a two-parameter, non-destructive tool with no output schema, the description covers purpose, network scope, behavior cadence, and the status return adequately. Missing pieces (port-conflict behavior, whether a canvas must be open) are minor rather than blocking.

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 50%: the port parameter carries its own default documentation ('Default 4173, or --serve at startup') while the action enum has no schema description. The description partially compensates by explaining what 'status' returns, but says nothing about start/stop semantics or the interaction between action and port, so it adds only marginal value over the schema.

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

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

The description states a concrete verb pair and resource: it starts/stops a localhost page that renders every open canvas at ~1 fps. That is far more specific than the name alone. It does not, however, differentiate itself from the sibling paint_preview, which an agent could easily confuse with a live-serving tool.

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

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

Usage is only implied: the mention that action:'status' reports the URL hints at the monitoring use case, and 'so a human can watch the drawing happen' implies the when. There is no explicit statement of when to pick this over paint_preview or paint_inspect, and no stated prerequisite that a canvas must already exist.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the mutation/repeatability profile is covered structurally. The description adds that layers, filters, and undo behave uniformly across drawing tools, hinting the operation is reversible, but says nothing about how existing pixels at the target location are treated (replace vs. composite) — useful for a non-idempotent draw op.

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 paragraphs with the core action front-loaded and the source-type constraint immediately after. The final sentence about layers/filters/undo is slightly tangential but earns its place by clarifying cross-tool consistency.

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 13-parameter mutation tool with no output schema, the description covers the operation, source semantics, key transform options, and cross-tool layer/undo behavior. It leaves return/preview behavior to the schema, which documents it, so only minor gaps remain.

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

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

With 13 parameters and only 62% schema description coverage, the description compensates by naming the meaning of source (canvas name or paint-root path, png/jpg/bmp), scale, rotate, opacity, blend, region crop, and tile. The unaddressed remainder (x, y, layer, preview, preview_size) is largely covered by schema descriptions.

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

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

States a specific verb and resource ('Places another canvas or an image file onto this layer') and enumerates the supported source formats and transform options. An agent can distinguish it from paint_rect, paint_brush, or paint_transform 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?

It gives setup context ('Target the canvas by name (created with paint_canvas) and optionally a layer index') but never states when to choose stamping over a sibling like paint_import or paint_transform, nor any when-not condition. Usage is implied rather than prescribed.

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 the safety profile (readOnly=false, destructive=false, idempotent=false), so the bar is lower, and the description adds real behavior: a fixed 5x7 ASCII font, transliteration (or error) for non-ASCII, no font files required, and undo interoperability. It does not mention permissions or error semantics, but the added context is substantive.

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 paragraphs, front-loaded with purpose and then behavior; each sentence carries weight. The second paragraph's 'layers, filters and undo work the same for every drawing tool' is slightly generic boilerplate, but it is brief and useful.

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 19-parameter mutation tool with no output schema, the description covers purpose, font behavior and a few key params, but leaves most parameter semantics and error/permission behavior unexplained. It is adequate but incomplete given the tool's complexity.

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

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

Schema coverage is low (42%), so the description must compensate, and it does explain scale (pixel multiplier), align/valign (anchoring around x,y), max_width (wrapping) and unicode behavior. However many of the 19 parameters (color, opacity, outline, outline_color, blend, line_spacing, letter_spacing, preview/preview_size) get no meaning in the description, so the coverage gap is only partly closed.

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 ('Writes text with the built-in 5x7 pixel font') and immediately identifies the distinguishing trait versus the other paint_* drawing tools, which draw shapes/pixels rather than text. An agent can pick this out from paint_brush or paint_rect 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?

It gives context -- target a canvas created with paint_canvas and optionally a layer index, and notes layers/filters/undo behave uniformly across tools -- but never states when to use paint_text instead of a sibling or any exclusion conditions. Usage is implied rather than explicit.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuine behavioural context beyond that: bilinear resampling quality and the fact that 'trim' shrinks to painted content. It stops short of explaining in-place mutation vs. copy or undo implications for transforms specifically.

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 paragraphs, front-loaded with the layer/canvas mode split, with no filler sentences. The closing line about layers/filters/undo is slightly tangential but still earns its place as shared-behaviour context.

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 14-parameter destructive tool with no output schema and only 43% schema description coverage, the description covers mode semantics and a couple of behavioural traits but omits geometry parameters (anchor, x/y, width/height, factor, degrees) and the preview/background output controls. Adequate but visibly 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 only 43%, so the description must carry more weight. It usefully maps the mode values to layer vs. canvas scopes and clarifies the layer index/active-layer concept, but parameters such as x, y, anchor, factor, degrees, width/height, preview and background receive no meaning from the description. Baseline 3 given partial compensation.

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 and then splits the operations into two scopes: 'scale | rotate | flip | translate on one layer' versus 'crop | resize | trim on the whole canvas.' This lets an agent distinguish it from siblings like paint_rect or paint_filter 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?

It gives a prerequisite ('Target the canvas by name (created with paint_canvas)') and notes that layers/filters/undo behave consistently across drawing tools, which implies usage context. However it never states when to choose paint_transform over alternatives (e.g. paint_ops or paint_canvas) or any when-not conditions, leaving routing 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?

Annotations already flag destructiveHint=true and non-idempotent, so safety is covered. The description adds real value beyond them by disclosing the step granularity model ('each drawing operation is one step', 'a paint_ops batch rolls back one step per op') and by noting that the 'steps' action is non-mutating, which nuances the blanket destructive hint.

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 with the purpose front-loaded, then granularity, then the non-mutating tip — every clause earns its place. Minor awkwardness in the trailing 'action:'steps'' phrasing keeps it from being exemplary.

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 4 params (1 required), no output schema, and annotations already carrying the safety profile, the description covers what an agent needs: what it mutates, step granularity, and the non-mutating inspection action. Only the behavior at stack boundaries is left unstated, a minor omission.

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 75% and it already documents steps, canvas, and preview. The description adds meaning the schema lacks: how steps are counted for paint_ops batches and the read-only semantics of the 'steps' action. No per-parameter syntax is added, but the semantic gap around step counting is filled.

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 ('Roll a canvas back or forward') that maps cleanly to undo/redo, and the title confirms the scope. It does not explicitly contrast itself with any sibling, but no sibling duplicates this function, so ambiguity is low.

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 one concrete usage rule for the 'steps' action ('see the stack without changing anything'), which is genuinely helpful. However, it never explains when to choose undo vs redo vs steps, nor what happens when the stack is exhausted — usage is implied rather than stated.

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