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

Annotations declare readOnlyHint=false and destructiveHint=false, correctly signaling a non-destructive mutation. The description adds genuinely useful context beyond that: the default of copying the previous frame's cels and the empty=true override. It omits save/backend behavior, but that is documented in the schema.

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

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

Two tight sentences, zero filler, with the primary action front-loaded and the key behavioral default immediately following.

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 annotations and no output schema, the description covers the core default behavior adequately but leaves the return value, batch-mode effects, and sibling routing unaddressed. It is minimally sufficient rather than 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 coverage is 63%, with 'empty', 'count', and 'durationMs' lacking descriptions. The description compensates for 'empty' (blank vs copied frames) and hints at copyFrom's default, but says nothing about count or durationMs, so it only partially bridges the gap.

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?

'Adds frames' states a specific verb and resource, clearly distinguishing it from delete_frames and move_frame. The added clause about cel-copying behavior further sharpens what the operation does, though it never explicitly names a sibling to route against.

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 'empty=true adds blank frames' distinction, which steers the agent toward the right option for blank vs cloned frames. However, it offers no explicit when-to-use guidance relative to copy_cel/link_cels or any prerequisites, 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 declare readOnlyHint=false and destructiveHint=false, establishing a non-destructive write. The description adds that properties are set at creation time, which is useful, but omits significant behavior such as the save default (writes back to the sprite file) and backend selection between live and batch modes.

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

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

A single, tightly packed sentence with the core action and its main modifiers front-loaded. No filler, though packing four clauses leaves some ambiguity about ordering semantics.

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 23-parameter creation tool with no output schema and nested objects, the one-sentence description is thin. The important file-write semantics of save/backend and the group-parenting behavior are left entirely 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 description coverage is 74% across 23 parameters, so the schema carries most documentation. The description adds only the layer-type and placement vocabulary already implied by the schema; it does not clarify ambiguous params like save, backend, or properties.

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 (adds) and resource (layer), enumerating the creatable layer types and placement options. This clearly separates it from siblings like update_layer, delete_layer, and duplicate_layer, though it never names them 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 guidance on when to use add_layer versus alternatives (convert_layer, duplicate_layer, add_slice), nor any prerequisites or exclusions. The placement options are described as capabilities, not as selection criteria.

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

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

Annotations already establish that this is a mutation (readOnlyHint=false) that is not destructive (destructiveHint=false), which matches an additive 'add' operation. The description adds the duplication path via copyFrom, but says nothing about persistence/save semantics, batch vs live backend implications, or what happens to existing slices - all relevant for an 11-parameter 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?

A single tight sentence with the primary action front-loaded and the alternate mode appended. No filler or restatement of the tool name beyond what is needed.

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?

Adequate but thin for an 11-parameter, nested-object, no-required-parameter mutation tool with no output schema. Important operational context - save/batch behavior and what a call with no arguments does - is left entirely to the schema rather than the description.

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

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

Schema description coverage is 73%, so the schema already documents most parameters (save, color, pivot, center, sprite, backend, copyFrom). The description only gestures at three of them (center, pivot, copyFrom) without adding format or constraint detail beyond the schema, so it lands at the baseline rather than compensating for the uncovered parameters.

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 ('Adds a slice') and names the two operating modes: normal add versus duplication via copyFrom. It does not explicitly differentiate itself from the sibling update_slice/delete_slice, though the verb makes the distinction largely inferable.

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

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

No guidance on when to choose this tool over update_slice or delete_slice, and no mention of prerequisites (e.g. that a slice generally needs bounds). The only routing hint is the copyFrom duplication mode, which is described as a capability rather than a when-to-use condition.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive write. The description adds the frame-range scope of a tag, which is useful, but it omits the live-vs-batch and save behaviors that the schema hints at. With annotations carrying the safety profile, 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?

A single front-loaded sentence with zero waste. It is appropriately sized for its content, though the brevity reflects under-specification rather than tight editing.

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 11 params, batch/live backends, a save toggle, and no output schema, one sentence is far too thin. Key behaviors like persistence and mode selection are left entirely 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?

11 parameters with only 55% schema description coverage, and the description mentions none of them. Undocumented params (from, to, name, data, aniDir) get no help from either source; only 'frame range' loosely implies from/to.

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 ('Adds an animation tag') plus scope ('over a frame range'). It clearly distinguishes from delete_tag and update_tag by virtue of 'adds', though it never names or contrasts those siblings explicitly.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the sibling tools (update_tag, delete_tag) that would help an agent choose. Usage is only implied by the verb.

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

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

Annotations only declare readOnlyHint=true, a low bar for a doc reader. The description adds genuinely useful behavior beyond that: the content is bundled from github.com/aseprite/api, and omitting the topic switches the tool into a listing mode. It does not describe the shape of the returned reference text, but for a safe read-only lookup this is a solid disclosure.

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, zero filler. The core action and the no-argument fallback are front-loaded, and the topic list is placed last where it is only needed after the agent has decided to call the 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?

There is no output schema, so the description carries the burden of explaining the return. It says it 'reads the API reference' but never states the return format (prose, markdown, structured sections) or whether results are chunked. For a single-parameter, read-only doc tool the missing pieces are minor, but not fully covered.

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%, setting the baseline at 3, but the description goes beyond the schema by enumerating the full set of valid topic names and showing the command/<CommandName> pattern. That materially helps the agent construct a valid topic value rather than guessing from the schema's three examples.

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

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

Specific verb+resource: 'Reads the Aseprite Lua API reference,' with the source repo named. The description also explains the no-argument behavior (lists topics), so an agent can distinguish this documentation-lookup tool from execution siblings like run_lua or run_command 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?

The description gives clear usage context: pass a topic to read a specific section, omit it to enumerate available topics. It enumerates the topic vocabulary (app, sprite, layer, cel, image, ...) so the agent knows what it can ask for, but it never states when to prefer this over alternatives such as list_commands or use_tool, nor any 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 readOnlyHint=false and destructiveHint=false, so the safety profile is largely covered and the description is consistent with it. The description adds the supported-filter enumeration, which is real behavioral content, but says nothing about live-vs-batch effects, the save-writeback behavior, or whether edits are undoable.

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

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

Two tightly packed sentences with the core action and filter list front-loaded and the parameter examples second. Dense but no filler; a small readability cost from cramming all examples into one 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?

For an 8-parameter, nested-object mutation tool with no output schema, the description covers only the filter/params axis; the frame, layer, sprite, backend, and save parameters are left entirely to the schema. It is adequate to invoke the tool, but the batch-vs-live behavior and write-back semantics an agent needs for correct use go unmentioned.

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 'params' property in the schema is an open object with no documented shape, so the description's concrete examples (Outline {color, place, matrix}; HueSaturation {hue, saturation, lightness, alpha}; BrightnessContrast {brightness, contrast}) carry information the schema cannot. It stops short of covering ColorCurve, ConvolutionMatrix, Despeckle, InvertColor, and ReplaceColor, so the gain is 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 ('Applies') and resource ('image filter command') plus the exact scope ('active cel(s) or selection'), and enumerates the eight supported filters, which makes the tool easy to identify. It does not, however, contrast itself with neighboring mutators like replace_color or draw_pixels, so sibling differentiation is left to the reader.

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: the agent infers this is the tool for the listed filters, and the pointer that 'Params follow list_commands' is a useful routing hint to a sibling. There is no explicit when-to-use/when-not guidance or description of prerequisites (active sprite, connected live session, etc.).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the reported data is current/live ('editor zoom (live)'), hinting at the live-vs-batch distinction, but never states whether the headless batch fallback returns stale or partial state.

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

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

A single front-loaded sentence that enumerates the return fields with no filler; the tool's purpose is knowable from the first four words.

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

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

With no output schema, the field enumeration usefully carries the return contract, and the one optional parameter is covered by the schema. It stops short of explaining behavior differences between the live and batch backends.

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

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

Schema description coverage is 100% and the single 'backend' enum is fully documented in the schema. The description's '(live)' mention gestures at the same live/batch choice but adds no syntax or default details beyond what the schema already gives.

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 ('Returns') and resource ('Aseprite's current state') and enumerates the exact fields returned, which effectively separates it from per-sprite readers like get_sprite_info. It does not name a sibling tool it is not, so it falls 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?

The description says what is returned but never states when to reach for this tool versus status, get_sprite_info, or recent_events, nor any exclusions. Usage is only faintly implied by the read-state framing.

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

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

With only readOnlyHint=false in annotations, the description carries most of the burden and delivers: it is blocking (waits for user), live-mode-only, and interactive. It does not explain the readOnlyHint=false side effect nor the timeout behavior, but the core behavioral traits are disclosed.

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 live-mode constraint, with no filler. Slightly list-like in the field-type enumeration but each clause carries information.

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

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

No output schema exists, and the description does explain the return ('returns the pressed button and field values'). For a 5-param interactive tool it covers the essentials, though it omits timeout semantics and nested field detail.

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 40%, below the 50% threshold, so the description must compensate. It lists the field types (entry, number, slider, check, combobox, color, label), mentions buttons, and states the return value, mapping meaning onto the fields/buttons params, though nested field attributes (min, max, value, decimals) remain 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 resource: it shows a dialog in Aseprite and waits for the user to answer. It also names the interaction surface (text, input fields, buttons) and the return. No sibling tool does anything similar, so it is inherently distinguishable.

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 leading 'Live mode:' clause implies a mode prerequisite, giving some usage context. However, it names no alternatives, no when-not conditions, and no guidance on when to prefer this over plain scripting.

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 mutation, and the description adds useful behavioral detail that negative margin values cut pixels. It does not cover persistence (save default true), backend auto/live/batch behavior, or reversibility — though save and backend are documented in the schema, so the gap is moderate rather than severe. No contradiction with destructiveHint=false.

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

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

A single dense sentence with zero filler, and the core behavior ('without scaling pixels') is front-loaded before the parameter modes. It could be marginally clearer about whether the two modes are mutually exclusive, but it earns its length.

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 tool at 27% schema coverage with no output schema and no descriptive annotations, the description covers the core spatial parameters adequately but is silent on trimOutside, anchor value effects, and the live-vs-batch save implications. Adequate but with clear gaps for a tool this size.

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 27%, so the description carries real weight and it does explain left/top/right/bottom direction semantics and that negatives cut, plus the width/height+anchor mode. It leaves anchor selection meaning, trimOutside, and whether the two modes can be combined 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 (grows/shrinks) and resource (canvas) plus the key differentiator 'without scaling pixels', which implicitly separates it from resize_sprite. It doesn't name the sibling explicitly, but an agent can distinguish it.

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

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

The 'either margins ... or width/height with an anchor' clause gives useful mode-selection context for the two ways to call it. However there is no explicit guidance on when to choose canvas_size over crop_sprite, resize_sprite, or trimOutside, 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?

Annotations declare readOnlyHint=false and destructiveHint=false, so the safety profile (a non-destructive write) is already conveyed and the description does not contradict it. The description adds the optional-dithering trait but says nothing about persistence, batch vs live execution, or what happens to the sprite 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?

A single front-loaded sentence with no filler, which is well-structured. It is arguably too terse for a 10-parameter tool, but as conciseness it works.

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 10 parameters, 40% schema coverage, and no output schema, the description leaves major gaps: how modes interact with dithering/rgbmap, whether changes are saved, and the batch-vs-live distinction. It is far from complete enough to guide 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 only 40%, so the description must compensate for the many undocumented parameters (mode, rgbmap, toGray, fitCriteria, ditheringFactor, ditheringMatrix), yet it only alludes to dithering. The mode enum values are restated but no format, defaults, or interactions are explained beyond the schema.

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

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

States a specific verb (converts) and resource (sprite) plus the three target color modes, so an agent can tell it apart from siblings like replace_color or palette_edit. It stops short of naming any sibling explicitly, so it earns a 4 rather than a 5.

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

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

There is no when-to-use, when-not-to-use, or alternative-tool guidance at all. The agent must infer that this is for changing a sprite's color mode rather than for palette or per-pixel color edits.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, and the description aligns with that by stating cels are cleared to transparent (or overwritten with a color), which is genuinely additive detail about what is lost. It does not disclose undo/reversibility, the live-vs-batch implications, or the default save-to-file behavior, so it only modestly exceeds what annotations provide.

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

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

A single dense sentence that front-loads the core action and appends the fill alternative and the three scope modes without wasted words. No filler, no 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 12-parameter, destructive, no-output-schema tool, the description covers the operation and its target granularity but omits operational context such as batch-mode/save semantics, live-vs-batch behavior, and reversibility. The rich schema compensates for the parameter gaps, but behavioral context is thin.

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%, above the 80% threshold, so the schema already documents nearly all 12 parameters thoroughly (color formats, frame ranges, tags, sprite/layer targeting, save flag). The description restates the targeting modes but adds no syntax or format meaning beyond the schema, so the baseline 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 verb (clears) and resource (a layer's cel(s)) with the outcome spelled out: to transparent, or filled with a color. The three target scopes (whole cel, rect, selected area) further pin down what it does. It does not name or contrast with the obvious sibling delete_cel, 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?

The description enumerates the ways the region can be targeted but gives no when-to-use guidance, prerequisites, or exclusions relative to alternatives like delete_cel, draw_pixels, or replace_color. An agent must infer selection from the parameter schema alone.

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

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

Annotations only supply readOnlyHint=false, so the description carries most of the burden. It discloses the batch-mode execution and that output is returned, but does not warn about the key behavioral traits of arbitrary CLI execution: arbitrary file writes from --save-as/--sheet, working-directory assumptions, or the timeoutSeconds budget. Useful context, but not the full safety picture.

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 invocation form, followed by concrete flag examples and a canonical doc link. No sentence is padding, and the most important information comes first.

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 that shells out to an external binary with no output schema and an undocumented timeout parameter, the description is adequate but thin. It says output is returned but omits where files are written, what the effective working directory is, and how timeouts manifest, all of 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 coverage is 50%: 'args' is documented in the schema with an example, while 'timeoutSeconds' is undocumented in both schema and description. The description's flag list helps an agent construct args, but adds no semantics for the timeout-bound parameter, so the baseline 3 fits.

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 ('Runs the Aseprite command line in batch mode (aseprite -b <args>) and returns its output'), which is concrete and distinguishable from wrappers like run_lua. It does not explicitly name sibling alternatives such as export_sprite_sheet or run_lua, so an agent must infer the boundary from the tool list.

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

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

The list of example flags ('--sheet/--data exports, --split-layers, --list-tags, --save-as...') implies the cases where this raw-CLI escape hatch is useful. However, it never says when to prefer the dedicated siblings (export, export_sprite_sheet, run_lua) instead, 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 only provide readOnlyHint=false, which is coarse for a tool that contains both reads (info, get_text, get_image) and writes (set_text, clear, set_image); the description never separates the read actions from the mutating ones. It does add useful behavior beyond the annotation, e.g. get_image returning a preview versus writing to file, and how backend selection works, but it never says that 'clear' or 'set_text' overwrite/destroy existing clipboard content.

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

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

A single front-loaded sentence that leads with read/write scope and then tucks action details into parentheticals. It is long and dense but nearly every clause carries information; the only slight redundancy is restating 'file' semantics that the schema already documents.

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 six action modes, eight parameters, a nested rect object, and no output schema, the description covers mode selection and one return form (image preview) but is silent on what info/get_text return, what clear does to existing content, and failure behavior (e.g. no image on clipboard, headless backend limits). Adequate but with clear gaps for a tool this broad.

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 63%, with 'rect', 'text', and 'action' documented only by the enum, yet the description compensates by binding parameters to actions: 'file' for get_image save / set_image load, and 'sprite frame/layer/rect' as set_image sources. That action-to-parameter mapping is genuine added meaning beyond the schema, though the full action/parameter matrix (e.g. which actions accept 'text') is left implicit.

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 ('Reads or writes the system clipboard') and then enumerates all six action modes with their sub-behavior, so an agent knows exactly what the tool covers. It does not, however, differentiate from adjacent siblings such as 'clear', 'get_pixels', 'draw_image', or 'render_preview', which overlap conceptually with some of these actions.

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 action enumeration implicitly tells the agent which mode to pick for text vs. image vs. metadata, and the backend note ('auto (default): live Aseprite if connected, else headless batch') plus 'Batch mode needs a file path' give real operational context. There is no explicit when-to-use/when-not guidance and no routing to alternative tools for image transfer.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is partly covered. However, the description does not disclose the important behavioral facts: what happens to unsaved changes, how save/discardChanges interact, or how the batch backend differs from live. For a destructive close operation this is a meaningful gap.

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 a single short sentence with no padding, which is good for front-loading, but the parenthetical qualifier is arguably misleading rather than earning its place. Brevity here reflects under-specification more than disciplined conciseness.

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

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

For a zero-required, four-parameter destructive operation with no output schema, the description omits the data-loss semantics and backend-dependent behavior an agent needs to call it safely. It is not complete enough to invoke confidently without inspecting the schema.

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

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

Schema coverage is only 50%, with save and discardChanges undocumented in both schema and description, and the description adds no parameter meaning at all. It fails to compensate for the coverage gap on the two parameters that determine whether closing destroys work.

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 ("Closes an open sprite") that an agent can readily distinguish from open_sprite and save_sprite. The "(live mode)" qualifier is ambiguous though, since the schema's backend enum supports auto/live/batch, implying the scope is narrower or different than the tool actually is.

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 indication of when to choose this tool versus save_sprite or open_sprite, nor any prerequisite or exclusion guidance. The only contextual hint is the trailing "(live mode)", which is not elaborated and is muddled by the backend enum.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered; the description adds nothing further. It never states whether existing pixel data is preserved, whether converting to/from Background flattens anything, or whether the change is undoable, which matters for a layer-type mutation.

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

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

A single front-loaded sentence that packs the three supported conversions without filler. It is efficient, though the colon-list construction is slightly dense and could be split for faster 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?

With five parameters (one required), 80% schema coverage, and no output schema, the description need not explain return values, but it should say what happens to the layer's content after conversion. For a mutation tool with no output schema, the absence of any side-effect statement leaves a real 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 80% and the 'save', 'layer', 'sprite', and 'backend' parameters are documented in the schema, so the baseline of 3 applies. The description lists the conversion modes that correspond to the 'to' enum but adds no syntax or defaulting nuance beyond what the schema already provides.

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

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

The description names a specific verb (converts) and resource (a layer) and enumerates the three conversion modes, which map cleanly onto the 'to' enum values. It is distinguishable from sibling mutators like update_layer or add_layer, though it never explicitly contrasts itself with them.

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 enumerated conversion directions imply when the tool is appropriate (changing layer type), but there is no explicit guidance on when to prefer it over update_layer or add_layer, and no mention of prerequisites such as needing an open sprite or a tilemap-capable document for the image/tilemap conversions.

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

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

Annotations declare this is a write operation (readOnlyHint=false) that is non-destructive, so safety is partly covered. The description adds that the copy can target a different sprite, but does not disclose whether an existing destination cel is overwritten (potential content loss), nor the live-vs-batch backend implications. Some added context, but a key mutation consequence is left implicit.

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

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

A single well-formed sentence with the operation front-loaded and the optional extension parenthetically scoped. No wasted words, though it is quite terse for a 10-parameter mutation 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 10-parameter mutation with no output schema and minimal annotations, the description omits the meaning of the x/y parameters and the overwrite/return behavior. Annotations carry the safety profile, which lowers the bar, but the description leaves gaps an agent would need to close by opening 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?

With 10 parameters and only 60% schema description coverage, the description's mention of 'another layer/frame' and 'another open sprite' loosely maps to toLayer/toFrame/sprite, but adds no syntax or format detail. The x, y coordinates go entirely unaddressed in both the description and (by coverage gap) parts of the schema, so it only marginally compensates.

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 (Copies) and resource (a cel's image) with the destination scope (another layer/frame, optionally another sprite). It distinguishes the operation from sibling tools like link_cels (which links rather than copies) and duplicate_layer (which duplicates whole layers). It stops short of explicitly naming a sibling, but the function is unambiguous.

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

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

The description implies when it applies (moving a cel's image to a target) but offers no explicit when-to-use vs alternatives, no prerequisites, and no note about how it differs from link_cels or get_cels/update_cel workflows. Nothing routes the agent among the copy-adjacent 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 and destructiveHint=false, so the mutation profile is covered structurally. The description adds no behavioral context beyond the mode semantics — it never mentions the live-vs-batch backend distinction or that in batch mode changes are written back to the sprite file (default save=true) before and after a crop.

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

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

A single, front-loaded sentence that names the operation first and then the three modes, with no filler. Slightly dense parenthetical structure, but 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 six-parameter, mutation-capable tool with no output schema and 50% schema coverage, the description is thin: it omits where changes land (live canvas vs file), the meaning of byGrid, and the rect parameter's semantics. It is adequate to call the tool in the simplest case but leaves 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 50%: save, sprite, and backend are documented in the schema, while mode, rect, and byGrid are not. The description partially compensates by explaining what the 'selection' and 'auto' mode values mean (the enum names alone don't convey this), but it says nothing about rect's coordinate space or what byGrid does.

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 (crops) and resource (the sprite) and enumerates the three operating modes, so the agent knows exactly what the call does. It does not differentiate itself from nearby siblings such as resize_sprite, canvas_size, or selection_edit, which is the only missing piece for a 5.

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

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

The mode-to-behavior mapping ('selection' crops to selection, 'auto' trims empty borders) implies when each mode applies, but there is no explicit when-to-use guidance, no exclusions, and no routing to alternatives like resize_sprite or selection_edit for related operations.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description's added clause ('of a layer in the given frames') merely restates scope already encoded in the layer/frames parameters, and it says nothing about reversibility, batch-vs-live side effects, or the save/batch write-back 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?

A single short sentence with the verb and scope front-loaded and no filler. It is efficient, though the brevity comes at the cost of the operational context this nine-parameter tool 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 destructive tool with nine parameters, zero required fields, and a live/batch backend switch, a one-line description leaves meaningful gaps: default resolution across layer/frame/sprite, batch mode requiring a file path, and whether undo is available. With no output schema, the description also gives no sense of what the call returns.

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 all nine parameters are documented in the schema itself, including defaults for frame, layer, sprite, and backend. The description mentions layer and frames but adds no syntax, precedence, or default-resolution meaning beyond what the schema provides, making the baseline 3 correct.

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

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

Names a specific verb and resource ('Deletes the cel(s) of a layer in the given frames'), so an agent immediately knows the operation. However, it offers no differentiation from near siblings like delete_frames, delete_layer, update_cel, or copy_cel, which share the same sprite-editing domain.

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

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

There is no guidance on when to use this versus delete_frames (which removes frames entirely) or clear/replace_color alternatives. No prerequisites, no note on how layer/frame defaults are resolved at call time, and no mention that deletion is undoable via undo_redo.

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 usefully widens the perceived blast radius by noting that a tag, list, or range can be deleted in one call, but it says nothing about reversibility/undo, the save-to-disk side effect, or per-backend 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?

A single front-loaded sentence with zero filler — the verb and the four modes come first. Given an 8-parameter destructive tool, it is arguably under-specified rather than over-long, but there is no wasted text.

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

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

For a zero-required-parameter destructive tool with no output schema, the description covers the core action but not the operational context: no mention of undo, of the save/batch side effect, or of mutual exclusivity among the targeting parameters. The schema carries most of the weight.

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 each of the 8 parameters is already documented in-schema; baseline is 3. The description's enumeration of delete modes loosely maps to frames/from/to/tag but adds no format or precedence detail (e.g. what happens if multiple selectors are supplied).

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

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

Specific verb (deletes) plus resource (frames) with the four targeting modes enumerated — single frame, range, list, or tag — which tells the agent the tool's blast radius. It does not differentiate itself from adjacent destructive siblings like delete_cel, delete_layer, or delete_tag, so a 4 rather than 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 at all: it does not say which selector to prefer (e.g. use from/to for a contiguous range vs frames for an arbitrary list), nor does it mention the live-vs-batch distinction in the backend parameter. The agent must infer invocation strategy entirely from the schema.

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 write/destructive nature is covered structurally. The description adds genuinely useful behavioral context — cascading deletion of children for group layers — but says nothing about undo/reversibility or the effect of the save/batch flag.

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

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

A single front-loaded sentence with zero filler. The most consequential fact (cascading child deletion) is stated immediately and nothing 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 destructive mutation with four parameters and no output schema, the definition covers the cascade behavior but omits whether the deletion is undoable and how save/backend interact with persistence. Annotations carry the safety signal, so this is adequate but not complete.

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

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

Schema description coverage is 100% and all four parameters (save, layer, sprite, backend) are thoroughly documented in the schema itself. The description adds no parameter-level detail, so the baseline of 3 for fully-covered schemas 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 verb (deletes) and resource (layer), plus the important cascade scope — children are removed when the target is a group. That scope detail helps distinguish it from sibling mutations like delete_cel or delete_frames, but it does not explicitly name or contrast those alternatives.

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

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

The description gives no when-to-use, prerequisites, or alternative guidance despite many nearby deletion siblings (delete_frames, delete_cel, delete_tag, delete_slice). The agent must infer the context of use entirely from the name and schema.

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 known. The description adds nothing beyond that — it says nothing about whether deletes are undoable, that the operation mutates a sprite file, or how batch/live mode affects persistence. No contradiction with annotations, but no value added either.

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 three-word sentence is not conciseness — it is under-specification. There is nothing front-loaded or structured, just a name restatement.

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

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

For a destructive mutation tool with four parameters, live/batch execution modes, and a save-to-file side effect, this description is far too thin. The absence of an output schema is fine, but the critical batch persistence behavior and slice-identifier semantics are left entirely unexplained.

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%, but the one required parameter (slice) has no description in either the schema or the description, so the agent cannot tell whether it takes a name or an index. The description contributes zero parameter meaning and does not compensate for the gap.

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?

"Deletes a slice." restates the tool name delete_slice with no additional specificity — it is essentially a tautology. It gives no hint of scope (which slice, how identified) or how it differs from sibling slice tools such as add_slice, update_slice, or delete_frames.

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

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

There is no guidance on when to use this tool versus alternatives like update_slice or delete_frames, no prerequisites, and no mention of the live-vs-batch distinction. An agent must infer everything from the schema.

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 the one piece of context annotations cannot convey: the destruction is scoped to the tag metadata only and frames are retained. It says nothing about idempotency when the tag is absent or undo behavior, but the key "what gets destroyed" fact is stated.

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

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

One short sentence with the critical scope qualifier front-loaded in parentheses. Every word earns its place.

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

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

For a destructive, no-output-schema tool, the description covers the essential scope of deletion but omits behavior on a missing tag, undo/rollback expectations, and any note that batch mode requires a file path (only in the sprite schema description). 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 coverage is 75% and save/sprite/backend carry their own descriptions, so the schema does most of the work. However, the required 'tag' parameter has no description and accepts string or integer without the description clarifying whether it is a name or an id, leaving a real ambiguity 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 and resource ("Deletes a tag") with an immediate scope clarification, which cleanly separates it from add_tag, update_tag, and the frame/layer deletion siblings. It does not name a sibling for disambiguation, but the resource is unambiguous.

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

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

No guidance on when to use this versus update_tag (e.g. renaming a tag) or whether prerequisites exist. The agent must infer the use case purely from the verb and noun.

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

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

The description goes beyond the annotations by defining each mode's effect: 'blend' composites, 'copy' overwrites the area, 'replace' swaps the whole cel image. That is real behavioral disclosure for a mutating tool whose annotations only say readOnly=false/destructive=false. It does not mention undo/reversibility or that batch mode writes to disk, which would complete the picture.

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, front-loaded with the core action and destination, then mode semantics, then the optional transforms. Every clause adds information with no filler.

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

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

For a 15-parameter mutation tool with no output schema and minimal annotations, the description covers the destination and modes but omits return/error behavior, undo implications, and the live-vs-batch save semantics. It is enough to attempt a basic call but not enough to use the tool confidently across backends.

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 low (33%), so the description must carry weight, and it does explain mode semantics plus the existence of source crop, scale and target size. However, it says nothing about x/y placement origin, opacity, blendMode, frame/layer/sprite resolution, or the save/batch distinction, leaving many of the 15 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?

States a specific verb and resource ('Draws an image file (PNG, etc.) into a layer/frame at (x,y)'), which implicitly separates it from draw_pixels, draw_shapes and draw_text by input type. No sibling is named explicitly, so an agent must infer the boundary rather than being told it.

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

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

Usage is only implied: you use it when you have an image file to place. There is no explicit 'use this instead of draw_pixels/draw_shapes when...' guidance, and no note about when live vs batch backend is required (only the schema covers backend/save).

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false. The description adds genuinely useful behavior: a single undo step, the cel auto-growing, out-of-canvas pixels being silently dropped, and the '.'-to-transparent erase convention. It does not disclose what the tool returns or how errors surface, but the added context is well beyond the annotations.

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

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

Three tightly packed sentences: purpose first, then the two input forms, then edge-case rules. No filler, no repetition of the name or schema, and the erase convention is grouped with the mapping rules it belongs to.

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 mutation tool with no output schema, the description covers the tricky invocation semantics (dual input formats, coordinate origin, erasure, clipping) well. It could say more about blend/save/batch mode and return behavior, but the schema fills those and the critical pixel-writing semantics are 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 coverage is 73%, so most parameters carry their own descriptions. The description still adds real meaning by explaining the pixels vs rows/legend duality, that rows start at (x,y), and the skip/mapping rules for ' ' and '.'. It leaves blend, save/batch, and backend semantics 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+resource ("Sets individual pixels on a layer/frame") and immediately characterizes the scope with "one undo step." It distinguishes itself from drawing-oriented siblings (draw_shapes, draw_image, draw_text) by describing per-pixel vs grid input, though it never names an alternative tool explicitly.

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

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

The description effectively explains the two mutually exclusive invocation modes (explicit pixels vs rows+legend) and their semantics, which is real usage guidance. However, it gives no when-to-use-this-vs-draw_image/draw_shapes guidance and no prerequisite context for choosing a backend or frame/layer target.

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 marking it as a non-read-only, non-destructive write, the description adds behavioral detail: antialiasing is off by default to preserve hard pixel edges, and each shape is stroked or filled. It stops short of describing save/write-back defaults or permission needs, but adds useful context beyond the annotations.

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

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

Front-loads the purpose and supported shapes, then covers stroke/fill, antialiasing default, and sibling routing in three compact sentences with no filler.

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

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

For a complex, 11-parameter drawing tool, the description covers shape semantics and antialiasing well, and the schema covers most remaining parameters. It could mention save/write-back behavior or target frame/layer defaults more directly, but output schema absence is acceptable.

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 82%, so parameters are already well documented; the description still adds value by explaining bezier point ordering ('start then control1, control2, end per segment') and path op semantics. It leaves many top-level parameters (frame, layer, save, opacity, blendMode) 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 ('Draws vector shapes') and enumerates all supported shape primitives, and it names use_tool as the alternative for pixel-exact aliased work, so an agent can distinguish its role from sibling drawing tools.

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

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

Provides a clear routing rule for one alternative: pixel-exact aliased shapes should use use_tool. It does not compare against draw_pixels or draw_image, but it gives enough antialiasing context to decide when vector drawing is appropriate.

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 establish only that this is a non-read-only, non-destructive mutate, so the description is free to add the more interesting behavioral detail: that rendering differs fundamentally between live and headless batch mode, and that font availability depends on the backend. It does not spell out persistence semantics (only the save param description hints at that) or error behavior, which keeps it below 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 sentences, front-loaded with the purpose before mode-specific detail, with no filler or repetition of the tool name. The middle sentence is dense but each clause carries distinct information about renderer selection. Slightly compressed prose keeps it from a 5.

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 18-parameter mutation tool with no output schema, the description covers the single most consequential complexity: the live/batch split and its effect on fonts, scaling, and persistence. The remaining parameters (align, opacity, letterspacing, measureOnly) are adequately covered by schema descriptions. It could say more about what happens to the target layer/cel, but the essentials are 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 description coverage is 78%, so the baseline is already a 3, and the description earns above that by clarifying what font accepts ('builtin', Aseprite's pixel font, or a named system font) and that its effect is mode-dependent. It also documents multi-line support via \n, a behavior absent from the schema. It doesn't touch the remaining ~22% of undocumented parameters, so it is not a 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?

Opening sentence gives a specific verb+resource ("Draws text onto a layer"), which cleanly separates it from draw_shapes and draw_pixels. It then explains the two rendering paths, adding precision about what "draw text" actually means here. It stops short of naming the sibling tools it competes with, so it lands at 4 rather than 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 which mode triggers which font renderer (live vs batch, or font='builtin'), which implicitly tells the agent when each behavior applies. However, it gives no explicit guidance on when to prefer draw_text over draw_pixels/draw_image, nor any prerequisites such as needing a connected Aseprite for live mode. 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 establish readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds one behavioral fact beyond annotations — that cels are carried along — but says nothing about whether the duplicated cels are linked or independent (relevant given the link_cels sibling), how the new layer is named, or how it interacts with the save/backend mode.

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

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

A single tight sentence with no waste and the core action front-loaded. It is arguably under-specified rather than over-verbose, so it does not reach a 5.

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 five parameters, no output schema and no required fields, the description is too thin: it omits how the copy is named, whether it lands on the active layer context, and how save/backend defaults affect the write. The schema and annotations carry most of the load, leaving the description incomplete.

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

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

Schema description coverage is 80%, so the schema already documents 'save', 'layer', 'sprite', and 'backend' thoroughly. The description adds no parameter-level detail beyond the implicit cels scope, so the baseline of 3 is appropriate.

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

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

States a specific verb+resource ('Duplicates a layer') and adds scope ('with all its cels'), so the agent knows exactly what the operation produces. It does not, however, distinguish itself from neighboring tools such as duplicate_sprite, copy_cel, or add_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?

There is no guidance on when to use this versus copy_cel, link_cels, add_layer, or duplicate_sprite, and no mention of prerequisites or context. The agent must infer usage purely 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?

Annotations declare readOnlyHint=false and destructiveHint=false, so safety is covered; the description usefully adds that the copy spans all layers/frames/tags/slices. However, it says nothing about where the copy lands, how it is named, or what handle the agent gets back for the new sprite.

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 purpose front-loaded and the batch constraint second. No filler, though the second sentence is somewhat redundant with the schema.

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, the description should explain what the caller receives (e.g. the new sprite's id/name) so the copy can be referenced; that is missing. For a 3-param duplication tool it is adequate but leaves this practical 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 67%, and the 'sprite' param description already states 'Batch mode needs a file path,' so the description's 'file is required in batch mode' largely restates schema content rather than adding new meaning. The undocumented 'file' parameter still lacks format details.

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 ('makes a copy') and resource ('a whole sprite') and enumerates scope (all layers, frames, tags, slices). The phrase 'whole sprite' implicitly distinguishes it from the sibling duplicate_layer, though it never names that sibling explicitly.

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

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

The only guidance is the conditional 'In batch mode file is required,' which is parameter usage rather than tool-selection guidance. It never says when to prefer duplicate_sprite over new_sprite, duplicate_layer, or open_sprite, nor 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 declare readOnlyHint=false and destructiveHint=false, but the description adds real behavioral context beyond them: single-image formats emit one file per frame, the trailing-number / templated naming scheme, and that the result lists every file written. It stops short of stating overwrite semantics or permission needs, but it is well above the annotation-only bar.

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

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

Three sentences, purpose front-loaded, with the options and the multi-file output behavior packed into the following sentences. Dense but every sentence carries information; 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 tool with a nested bounds object, two enums, and no output schema, the description usefully explains the return ('lists every file written') but leaves multiple parameters unexplained. It is adequate but not complete enough to call all 14 params 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 only 21%, so the description must carry the load; it explains scale, tag, 1-based frame range, slice, layers, and the filename template ({frame} counting from 0), which maps to several parameters. It still leaves bounds, aniDir, ignoreEmpty, and playSubtags undocumented in both schema and description, so it only partially compensates for the coverage gap.

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

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

The description gives a specific verb and resource ('Exports a copy of the sprite') plus the output surface ('any format' with a format list), so an agent immediately knows this writes image files. It does not, however, differentiate from the very close sibling export_sprite_sheet or save_sprite, leaving the agent to infer the boundary.

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

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

It enumerates the options (scale, tag, frame range, slice, layers, filename template), which implies how to use the tool, but never states when to reach for it over export_sprite_sheet, render_preview, or save_sprite, and offers no 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 declare readOnlyHint=false and destructiveHint=false, which is consistent with a file-writing export. The description adds useful context by disclosing that output is an image plus optional JSON data with various feature toggles, but says nothing about where files land, whether existing files are overwritten, or the required textureFilename 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?

Two tightly written sentences with the core purpose front-loaded and the menu path and capability list following. No filler, though the capability list is 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?

For a 31-parameter, side-effectful export with no output schema and near-zero schema coverage, the description is too thin. It omits the required textureFilename role, output destination conventions, and interaction between the many layout/split/trim options.

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 6% across 31 parameters, so the description carries real weight. It usefully groups features (layouts, padding, trimming, extrusion, splitting by layers/tags, tilesets, listing layers/tags/slices) that map to parameters like type, innerPadding/shapePadding/borderPadding, trim, extrude, splitLayers/splitTags, fromTilesets, and listLayers/listTags/listSlices, but gives no per-parameter semantics or formats.

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 (Exports) and resource (sprite sheet image plus optional JSON data), and references the exact menu path File > Export Sprite Sheet. It clearly conveys the resource and output shape, though it never explicitly distinguishes itself from the sibling generic 'export' 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?

The description offers no when-to-use guidance, no exclusions, and no mention of the sibling 'export' or 'import_sprite_sheet' tools. An agent must infer that this is the sprite-sheet-specific path from the name alone.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is known. The description adds the operation's scope targets but is silent on whether edits are applied live vs. batched, whether they are undoable, and how flip and rotate combine in a single call. Some useful behavioral context, but notable gaps remain.

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

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

A single tight sentence with the operation front-loaded and the affected targets enumerated. No filler, though the enumeration could be slightly better ordered by default scope.

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

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

For an 8-parameter mutation tool with no output schema and 63% schema coverage, the description is barely adequate. It never addresses the live-vs-batch distinction, the save behavior, or how simultaneous flip+rotate are applied, leaving an agent to rely on parameter descriptions alone.

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 63% and the schema itself documents the key ambiguities (save defaults true, frame defaults, layer/sprite resolution, backend auto). The description's scope sentence loosely mirrors the target enum but adds no format, ordering, or default information beyond the schema. Baseline 3 is appropriate when the schema carries most of the burden.

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

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

States a specific verb pair (flips/rotates) and names the resources it affects (whole sprite, active cel(s) of a layer/frame, or the selection). An agent immediately understands the operation and its scope. It doesn't explicitly distinguish itself from siblings, but no sibling overlaps this transform operation.

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

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

The description lists the three operation scopes, which implies when to use the tool, but gives no explicit when-to-use guidance, prerequisites, or alternatives. The caller must infer how target selection interacts with the other parameters.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuine value beyond that by enumerating the returned fields (bounds, opacity, z-index, data), which matters because there is no output schema, and by stating that results are filtered by layer and frames.

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

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

A single front-loaded sentence that names the operation, defines the resource, lists the returned data, and states the filtering dimension with zero 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 an 8-parameter read tool with no output schema, the description supplies the return shape and the filtering scope, while the schema carries all parameter defaults and constraints. It does not discuss batch-mode caveats or volume/pagination limits, so it is solid but not exhaustive.

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%, and the schema already documents defaults, allowed values, and formats for all 8 parameters. The description's 'filtered by layer and frames' merely restates a subset of those parameters without adding syntax or format detail, so baseline 3 is correct.

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

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

States a specific verb ('Lists') and resource ('cels'), and defines a cel as a layer/frame pair with images, which clearly separates it from the sibling mutators update_cel, delete_cel, copy_cel and link_cels. It does not name a sibling explicitly, 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?

The read-only listing intent is implied by 'Lists' and the annotations, but the description gives no explicit when-to-use guidance, no exclusions, and does not point to alternatives such as get_pixels or get_sprite_info. Usage must be inferred.

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 a safe read (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description usefully contributes the output format '#rrggbbaa' and ordering ('index 0 first'), but says nothing about live-vs-batch behavior or failure modes beyond what the schema's backend description provides.

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

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

A single front-loaded sentence that delivers purpose and return format with zero 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 simple read-only getter with no output schema, stating the color format is the most important missing piece and it is present. However, the ambiguous index parameter and unstated relationship between returned indices and the index input leave a real 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 67%; the sprite and backend params are documented in the schema, but index has no description. The description's '(index 0 first)' refers to the returned color ordering, not the index parameter, and with index minimum=1 the 0-vs-1 indexing distinction is left ambiguous.

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 ('Returns the sprite palette') and adds the return format, which cleanly separates it from set_palette, save_palette, and palette_edit. It does not explicitly name a sibling alternative, so it stops short of a 5.

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

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

There is no when-to-use guidance and no reference to alternatives such as get_sprite_info or palette_edit. Usage is only implied by the verb 'Returns'.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral detail about output shape (character rows + legend vs '#rrggbbaa' grid, transparency markers, indexed sprites returning palette indices), but says nothing about the maxPixels safety limit or failure conditions.

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 in the first clause, and the format semantics follow in compact clauses. Every sentence carries information; the density is high with no filler.

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

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

With no output schema, the description correctly takes on the burden of describing return values, which it does for both formats and for indexed sprites. For a 7-parameter, all-optional read tool this is close to complete, with only the maxPixels limit behavior left implicit.

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 71%, and the description meaningfully extends the 'format' enum by explaining what each mode returns (legend characters plus color legend with '.' = transparent; hex grid with null = transparent). It also clarifies composited-frame vs single-layer reading, though it leaves rect, frame, backend, and maxPixels 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 ('Reads') and resource ('pixels'), and scopes it to the rendered frame across all visible layers or a single layer. The read counterpart to draw_pixels is distinguishable from the verb alone, though no sibling is named explicitly.

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

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

Implies the read use case and offers a scope choice (whole frame vs one layer), but gives no explicit when-to-use vs alternatives like draw_pixels, get_cels, or render_preview, and no exclusions or prerequisites.

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

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

Annotations already declare a safe, read-only operation. The description goes beyond that by detailing the return structure (size, color mode, frames, layer tree, tags, slices, tilesets, palette size, grid, selection), which is valuable because there is no output schema. It does not discuss live-vs-batch output differences, but that is handled in the schema.

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

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

A single sentence with the main purpose front-loaded, followed by an efficient colon list. It is appropriately sized for a read tool and avoids filler.

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

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

With no output schema, the description compensates by enumerating the returned structure, and annotations cover safety. The schema handles parameters completely. Minor gaps remain around how live vs batch mode affects the returned structure, but the description is largely complete for this read tool.

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

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

Schema description coverage is 100%, so the schema fully documents sprite, backend, and includeCels. The description adds no parameter-level meaning beyond what the schema already provides, making the baseline 3 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 ('Returns a sprite's full structure') and enumerates the returned fields, making the tool's scope clear. It does not explicitly distinguish itself from overlapping siblings like list_sprites, get_cels, or get_palette, 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?

Offers no when-to-use guidance, no prerequisites, and no alternatives such as list_sprites or get_palette. The schema handles parameter defaults, but the description itself provides no routing information.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the mutation/safety profile is partly covered. The description adds that saving the result is optional, which is useful beyond the annotations, but it says nothing about the live vs batch backend behavior, failure modes, or what the slicing produces.

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, front-loaded sentences with no filler; the operation is stated first and the save caveat second. It is efficient, though perhaps terse given the tool's complexity.

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

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

With 10 parameters at 20% schema coverage, no output schema, and a write-capable operation, the description is too thin. An agent lacks guidance on the frame-grid parameters, the meaning of type, and how the optional save interacts with batch mode.

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 20% across 10 parameters; saveAs and backend are the only documented ones, and the description touches saveAs only obliquely ('Optionally saves the result'). Critical params like frameWidth, frameHeight, type, x/y, padding, and partialTiles are unexplained in both schema and description, so the description does not compensate for the coverage gap.

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+resource: opens an image and slices it into frames, with the parenthetical menu path (File > Import Sprite Sheet) anchoring it. This distinguishes it from siblings like open_sprite and export_sprite_sheet, though it doesn't name those alternatives directly.

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 UI menu reference and the note that saving is optional, but there is no explicit when-to-use guidance, no statement of when to prefer this over open_sprite or export_sprite_sheet, and no prerequisites.

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

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

Annotations only declare readOnlyHint=false. The description adds genuine behavioral context: the copy destination (user extensions folder) and the non-obvious prerequisite that a running Aseprite must be restarted to load it. It does not state overwrite behavior or whether the extension source is bundled.

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, zero waste. The core action is front-loaded and the restart caveat follows immediately as the second 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?

For a no-param, no-output mutation, the description covers what happens and the restart requirement. It stops short of noting whether an existing installed extension is overwritten, which would matter on re-runs.

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 per the baseline there is nothing for the description to disambiguate. The description correctly implies no inputs are required.

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 ('Copies') and a precise resource ('the bridge extension into Aseprite's user extensions folder'). An agent can tell exactly what this does. No sibling is close enough to require explicit differentiation.

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

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

Usage is only implied — install the extension when you need the bridge. There are no explicit when-to-use/when-not-to-use cues and no named alternatives (e.g., relaunching vs installing), leaving the agent to infer the trigger.

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

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

Annotations only give readOnlyHint=false, so the description carries the rest and does so well: it discloses that an external GUI process is spawned, that it blocks waiting for a connection, and that a trust dialog requires human interaction the first time. That interactive-friction detail is exactly the kind of context an agent needs and cannot get from structured fields.

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

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

Two sentences, zero filler, front-loaded with the primary action and effect before the first-run caveat. 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?

There is no output schema, and the description covers what the tool does, the blocking wait, and the first-run trust prompt. It stops short of saying what happens on connection timeout or what state the bridge is left in on failure, which would matter for a long-running launch step.

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 both parameters (file, waitSeconds with min/max and default) are already documented in the schema. The description adds nothing about either, which is acceptable given the coverage but earns only the baseline.

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

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

States a specific verb and resource ('Starts the Aseprite GUI with the bridge extension') plus the outcome ('waits for it to connect, enabling live mode'). No sibling tool does this, and the description makes the launcher/setup role unmistakable versus tools like use_tool, cli, or status.

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 context is implied: this must be done to enter live mode, and the 'The first time...' clause signals a one-off setup step. However, it never says when to prefer this over adjacent tools such as install_extension or cli, nor what to do if launch/connect fails.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false. The description adds real behavioral context beyond that: the mode requirement for linking vs unlinking, and the side effect that edits to one frame propagate to all linked frames. It does not explain failure modes or reversibility, 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?

Three short sentences: purpose first, then the mode constraints. Every sentence earns its place and the most important information is front-loaded with no filler.

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

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

With 11 parameters but 0 required and 91% schema coverage, the schema carries the parameter burden. The description covers purpose, side effects, and mode constraints, which is enough to call it correctly, though it could say more about how the many range/frame/layer parameters combine.

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 91%, so the schema already documents the parameters (from/to ranges, tag, frames, layers, save, etc.) in detail. The description adds no parameter-level meaning, so the baseline of 3 applies.

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

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

The description names a specific verb+resource (link/unlink cels) and goes further by explaining the semantic effect: 'several frames share one image (edits to one show in all)'. That is clear and unambiguous. It does not explicitly differentiate itself from siblings like copy_cel or update_cel, 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 an operational constraint ('Linking needs live mode. Unlinking works in both modes') which implies when each action is available, but offers no routing guidance versus alternatives such as copy_cel or update_cel. Usage context is implied rather than spelled out.

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

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

readOnlyHint=true already establishes this as a safe read, so the description need not restate safety. It does add one useful behavioral fact — the command data is extracted from Aseprite source, implying a static snapshot rather than live introspection — but says nothing about result size, pagination, or whether the list is version-specific.

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

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

A single front-loaded sentence that names the resource, the tool it pairs with, and the provenance of the data. No filler or redundant restatement of the name.

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 read-only listing with a fully documented schema and no output schema, the description is nearly sufficient: it tells the agent results include command parameters and where that data comes from. Minor gaps remain around result volume and whether the snapshot can go stale, but nothing essential 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 description coverage is 100%, so the single optional query parameter (case-insensitive filter on name/description) is already fully documented. The description's mention of 'with their parameters' refers to returned data, not the input parameter, so it adds no meaning beyond the schema. Baseline 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 verb and resource ('Lists Aseprite commands') and ties them to the consuming tool, run_command, which distinguishes it from nearby tools like run_lua or api_docs. The parenthetical about provenance adds a little scope detail, though it does not explicitly contrast with its closest siblings.

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

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

Usage is implied: the description references run_command, so an agent can infer this is a discovery step before invoking a command. However, there is no explicit when-to-use statement, no mention of when api_docs or run_lua would be preferable, and no guidance on whether the listing is exhaustive or how to narrow results.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds that data comes from pref.xml, a useful provenance detail, but does not cover return format or the discovery-then-set workflow. With annotations covering the safety profile, 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?

A single tight sentence with no filler, front-loading the verb and resource. 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 simple read-only list with no output schema, the description is sufficient: it says what is listed and where it comes from, and annotations carry the safety profile. Only the lack of any note on result structure or the follow-up workflow keeps it from a 5.

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 single 'section' filter is fully documented in the schema. The description adds no additional parameter meaning, making the baseline 3 correct.

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

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

States a specific verb+resource: lists Aseprite preference sections and options, and names the source (pref.xml). It points to the companion 'preferences' tool, which differentiates it somewhat from that sibling, though it doesn't contrast against other list_* tools.

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

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

The phrase 'for use with the preferences tool' implies this is a discovery step preceding the mutation tool, which is useful context. But it never states when to call it versus alternatives or when it is not needed, leaving usage largely 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=true and destructiveHint=false, so the safety profile is covered. The description adds only the 'open' scoping constraint; it says nothing about return format, ordering, or how the backend parameter changes 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?

A single front-loaded sentence with zero filler. It is appropriately sized for the scope, though it is arguably too bare rather than too verbose.

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 list tool with no output schema, the description never indicates what is returned (names, ids, count, active sprite). Combined with no usage guidance, the agent is left guessing about the result shape and when to reach for this versus get_sprite_info.

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 'backend' enum (auto/live/batch) is already documented in the schema, including the auto default. The description adds no extra meaning, which is the correct baseline when the schema does the heavy lifting.

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?

Clear verb+resource: 'Lists sprites open in Aseprite' tells an agent exactly what it returns at a high level. The scope word 'open' usefully narrows it from sprites-on-disk tools, but it does not distinguish itself from near-siblings like get_sprite_info or list_commands.

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

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

There is no when-to-use guidance, no exclusions, and no mention of alternatives such as get_sprite_info or app_state. The agent must infer from the name alone that this is a discovery step rather than a detail-fetch.

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 readOnlyHint=false, so the safety profile is covered. The description adds genuine context by specifying what destruction occurs — a layer is collapsed into the one below, or all/visible layers are flattened — which tells the agent the layer structure is lost. It stops short of mentioning undo-ability or irreversible side 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?

A single front-loaded sentence with three parallel clauses, no filler, and the core verb stated first. Every clause earns its place by defining a mode.

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, but the description need not explain return values for a mutation. Combined with 80% schema coverage and destructive annotations, the definition gives enough to invoke correctly; only undo/reversibility context 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 coverage is 80%, so most parameters are documented structurally, but the 'mode' enum is listed bare in the schema with no value descriptions. The description supplies the missing semantics for all three enum values, adding real meaning beyond the schema.

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

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

The description states a specific verb (merges/flattens) and resource (layers), and enumerates the three mode behaviors, so an agent knows exactly what each invocation does. It does not explicitly differentiate itself from layer-manipulation siblings such as convert_layer or delete_layer, which keeps it short of a 5.

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

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

The three modes are described, which implies the conditions for each, but there is no explicit when-to-use/when-not guidance and no named alternative (e.g. when to flatten vs. use convert_layer). Usage is inferable 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 declare non-read-only and non-destructive, so safety is partly covered, and the description usefully discloses that cels move with the frame. It says nothing about undo behavior, whether the source position is closed up or left empty, or how the live/batch backends affect the operation, all of which matter for a reordering mutation.

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 short sentence with no filler, front-loading the verb and resource. It is efficient, though arguably terse to the point of underspecification for a 5-parameter mutation 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 mutation tool with five parameters, no output schema, and only safety-hint annotations, the description is far too thin. It omits sequencing effects, undo/rollback behavior, the significance of the save/backend parameters, and return/error expectations.

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 60%, and neither required parameter (from, to) has a schema description beyond minimum: 1. The description's phrase 'another position' hints these are positional indices but does not clarify whether they are frame numbers, ordering indices, or 1-based, so it fails to compensate for the gap.

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 (moves) and resource (a frame with its cels) and adds the meaningful detail that contained cels travel with the frame. It does not, however, distinguish itself from sibling frame tools such as add_frames, delete_frames, or set_frame_duration, leaving the agent to 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 when-to-use guidance, no mention of prerequisites, and no comparison to alternative frame operations like delete_frames + add_frames or copy_cel. The agent must guess at the appropriate context.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation/safety profile is covered. The description adds a genuinely useful batch-mode constraint (file required, sprite saved there), but says nothing about the live-vs-batch execution difference, failure modes, or state side 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?

Two short sentences with zero filler, and the primary purpose is front-loaded before the conditional constraint. Nothing to trim.

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 creation tool with 45% schema coverage and no output schema, the description is thin. It addresses only 'file' and leaves the agent to infer defaults, backend behavior, and the meaning of most creation options.

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 45%, so the description should compensate. It clarifies the batch-mode requirement for the 'file' parameter beyond the schema's 'Save to this path' note, but 9 other parameters (frames, colorMode, layerName, frameDurationMs, etc.) get no description-level help. Partial compensation only.

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 ('Creates a new sprite'), which is clearly distinct from sibling tools like open_sprite and duplicate_sprite. It does not explicitly name those alternatives, so it falls 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?

The only contextual guidance is the batch-mode 'file' requirement. There is no indication of when to use this versus open_sprite (existing file) or duplicate_sprite, nor any prerequisites for the live backend.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds two useful facts: it returns the sprite's structure, and in live mode it opens a tab (a visible side effect). It says nothing about failure modes, unsupported-format errors, or persistence, so it adds only modest value over the annotations.

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

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

Two compact sentences, front-loaded with the core action and supported formats, then the live-mode caveat. 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?

There is no output schema, yet 'returns its structure' leaves the return shape vague for a tool whose main purpose is inspection. Combined with partial parameter coverage, an agent knows how to call it but not fully what to expect back.

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 67% schema description coverage, the schema already explains backend (auto/live/batch) and oneFrame, and the required 'file' is self-evident. The description adds no syntax, path, or format constraints beyond what the schema provides, so baseline 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 verb and resource ('Opens a sprite file') and enumerates accepted formats, which is genuinely informative. It implicitly distinguishes itself from new_sprite (create) and list_sprites (enumerate), but never names or contrasts those siblings explicitly.

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

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

The 'live mode opens a tab' clause hints at when the live path applies, and the backend parameter's enum/description in the schema carries the auto/live/batch logic. There is no explicit guidance on when to choose this over new_sprite, list_sprites, or get_sprite_info, so usage remains 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 only declare readOnlyHint=false and destructiveHint=false; the description adds genuinely useful behavior context beyond that — indexed-sprite pixels are remapped to preserve their colors, and pixels whose colors are removed fall back to the nearest remaining entry. It still omits whether the palette is persisted by default or how failures surface, but the remap semantics are substantial added value.

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 core verb and the full action inventory, then the side-effect caveat. The long parenthetical sort-key list is bulky but each operation enumerated is load-bearing for action selection.

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?

A 17-parameter mutation tool with no output schema, so the description carries more burden than it does. It covers the action space and the key side effect well, but says nothing about return shape, save/persistence defaults, or error behavior, which leaves 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 71% and the schema already documents most parameters including per-action applicability. The description contributes the sort key list (matching the 'by' enum), the remapPixels side effect, and the action vocabulary, but leaves many of the 17 parameters (save, backend, steps, insert, sprite, descending) solely to 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?

States a specific verb (Edits) and resource (palette structure) and enumerates the eight discrete operations, so an agent immediately knows the action space. It does not, however, distinguish itself from adjacent palette siblings like set_palette, get_palette, or save_palette, leaving that routing inference to the reader.

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 through the action list and one parameter-level hint ('set remapPixels=false to skip'). There is no explicit when-to-use guidance, no statement of when to prefer set_palette/replace_color instead, and no stated prerequisites for choosing between live and batch backends beyond what the schema says.

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