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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: tween/oscillate operate 'in one transaction' and 'fill in any missing in-between cels from the start cel,' disclosing atomicity and side effects. It stops short of stating reversibility or permission needs.

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

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

Front-loaded with purpose followed by the op list, then targeted explanations of the less obvious operations. Dense but nearly every sentence carries information an agent needs to disambiguate ops. Slightly long, though not padded.

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 20-parameter, 11-operation tool with an output schema present, return values need not be explained. The description covers the op semantics and transaction behavior well, but leaves a few parameter interactions (sprite selection, toLayer/toFrame pairing) to the schema.

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

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

Schema coverage is 70%, so the schema does much of the work, but the description adds real semantic value by mapping operations to intent (move vs link vs tween vs oscillate) and clarifying the opacity/position distinction for tween. It does not document every parameter (e.g. sprite, toLayer, frames) but complements the schema well.

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

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

States a specific verb+resource and defines the concept precisely: 'Manage cels — one layer's image on one frame.' It then enumerates all 11 supported operations, so an agent immediately knows the tool's exact scope. It is clearly distinguishable from siblings like layer or frame.

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?

Explains what several operations mean and implicitly when to prefer them: 'move' for shifting a limb without redrawing, 'link' for sharing an image across frames, 'tween'/'oscillate' for procedural in-betweens. It gives clear operational context but never explicitly routes the agent away from alternative sibling tools (layer, frame).

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 say it is a non-readonly, non-destructive, non-idempotent write. The description adds genuinely useful behavior beyond that: ops execute in array order, palette colours are snapped by CIELAB ΔE before writes, text is expanded to pixels locally, and measureOnly returns ink bounds without calling Aseprite.

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

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

Long but dense and front-loaded: the core action leads, then the op list, then ordering, palette lock, and the text/measureOnly caveat. Nearly every sentence carries actionable detail, though it runs slightly long for a definition.

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?

Output schema exists so return shape is covered, and the description fills the remaining gaps for a mutation tool: ordering semantics, palette safety, cel creation defaults, and the measure-only escape hatch. An agent has what it needs to call this correctly on the first try.

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

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

Schema coverage is 100%, so the baseline is 3, but the prose adds meaning the schema does not: array-order execution, the intent behind paletteLock's default and when to flip it, and the label parameter's purpose as an undo-history name. It does not document every op field, but it enriches the highest-risk ones.

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 ('Apply a batch of drawing operations to one cel') plus the transactional scope ('single undoable action'). An agent can distinguish it from transform, recolor, and read_pixels without opening any schema.

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

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

Gives clear operational guidance — batch aggressively, paint fills before outlines, use measureOnly for centering a label — and states the condition for disabling paletteLock. It does not explicitly route the agent between this tool and siblings like transform or recolor, so it stops short of full when/when-not coverage.

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 the description adds meaningful context by clarifying that export does not persist the working document, which is a key behavioral distinction from sprite_manage. It also explains the output format (JSON atlas for spritesheet) without contradicting the annotations. It does not mention overwrite behavior or side effects on existing files, but the annotation already covers destructiveness, so the added context is sufficient.

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

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

The description is four sentences with zero wasted words. The main verb is front-loaded, ops are listed compactly, the critical spritesheet guidance is placed early, and the save-disambiguation is at the end. Every sentence 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?

Given the tool's complexity (12 parameters, 5 ops, multiple formats), the description covers the essential context: what each op does, the spritesheet consumption hint, and the crucial distinction from sprite_manage. The schema covers parameter details, and an output schema exists (not shown), so the description does not need to explain return values. It is complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 92% (most parameters have descriptions), so the baseline is 3. The description adds value beyond the schema by explaining the ops and how parameters like `sheetType` and `byTag` control spritesheet layout, and by clarifying the `path` pattern for 'frames'. This helps an agent understand the semantics without opening the schema, slightly exceeding the baseline.

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

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

The description opens with a specific verb+resource ('Write game-ready files') and then enumerates each operation with a short, distinct explanation (png, gif, spritesheet, frames, aseprite). It explicitly differentiates the spritesheet op as the engine-consumable format and names the sibling tool (sprite_manage op 'save') for a different purpose, making its scope 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?

It provides explicit when-not-to-use guidance by stating 'Exporting does not save the working document — use sprite_manage op 'save' for that.' It also gives usage direction for the spritesheet op ('Spritesheet is what an engine actually consumes: pass `sheetType` and `byTag` to control layout'), helping an agent choose the right op and 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 destructiveHint=true and readOnlyHint=false, so the mutating nature is known. The description adds domain context about durations carrying the life of a cycle, which is helpful but does not disclose operational details like irreversibility of delete or that operations affect the active sprite. Since annotations cover the core safety profile, the description's modest additional disclosure merits a 3.

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

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

The description is tightly written, with the ops list front-loaded and each sentence earning its place. The usage guidance for durations and batch operations is concise and directly actionable, 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?

Given the tool's complexity (9 parameters, 7 ops), an output schema exists to define returns, and annotations cover safety. The description covers the operation scope and provides key usage tips. It does not explain every edge case (e.g., behavior when frame is omitted, or activate semantics), but the schema already documents frame omission, and the ops list is self-explanatory. This is adequate for an experienced user.

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%, with descriptions for frame, sprite, toIndex, linkCels, durations, and afterFrame. The description adds value beyond the schema by explaining the semantics of durations (milliseconds per frame) and the purpose of count and durations in batch operations. This compensates for the undocumented parameters (op, count, durationMs) with practical usage context.

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

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

The description clearly states 'Manage animation frames' and enumerates seven operations (list, add, duplicate, delete, set_duration, activate, reorder), making the resource and verb specific. It does not explicitly distinguish this tool from siblings like layer or tag, but the ops list leaves little ambiguity about scope.

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

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

The description provides practical guidance on when to use certain parameters ('Use count to add several at once and durations to set a whole cycle's timing in one call') and explains the role of durations in animation cycles. It lacks explicit alternative routing to sibling tools, but the context is clear and not misleading.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real behavioral detail beyond that: batch is a single undoable action, and duplicate-to-another-sprite drops and reports frames past the target's frame count.

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 op list, then batch semantics, then the duplicate edge case, then a workflow tip. Efficient overall, though the final rigging-advice sentence is more ambient guidance than operational instruction.

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?

Output schema exists so return values need no explanation, and annotations carry the destructive flag. However, with 13 parameters at 54% coverage, the description never says which parameters apply to which op (e.g. name vs newName, what 'set' can change), leaving ambiguity for a multi-mode 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 coverage is 54%, so the schema documents some parameters while leaving others bare (name, newName, opacity, visible, editable have no descriptions). The description clarifies batch grouping, toSprite target semantics, and that 'set' covers visibility/opacity/blend/lock, but does not map the remaining params to their ops.

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 the resource ('Manage layers') and enumerates all eleven operations, so an agent can see exactly what surface it covers. It clearly reads as the layer-level counterpart to siblings like cel and frame, though it never names a sibling to differentiate itself 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?

Gives concrete context: pass `batch` to run several ops in one undoable action and 'building a rig in one call is the normal use', plus the constraint that `duplicate`'s toSprite must be another OPEN sprite. No explicit when-not or named alternative tools, but the conditions that select the main modes are 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 only declare readOnlyHint/openWorldHint; the description adds real behavioral context beyond them: the 64×64 ascii cap and region-crop requirement, the automatic ~1024px scaling target and clamping behavior, and the non-obvious caveat that a vision model reads only the first frame of a GIF (hence 'filmstrip'). These are exactly the operational facts an agent cannot derive from 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?

Long but well-structured: one summary sentence followed by a bullet per op, each front-loading the op name before its use case. The closing workflow line earns its place. Slightly verbose for an 11-word tool name, but nothing is padding.

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

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

For a 12-parameter, multi-mode, nested-schema tool with an output schema present, the description covers all six modes, their constraints, and the intended workflow. Return-value format is handled by the output schema, so no gap remains.

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 already 92%, so the baseline is 3. The description still adds per-op meaning for the 'op' enum and explains non-obvious constraints (region required for large sprites, scale defaults chosen for vision-model legibility, layer/frame selection semantics), earning above baseline without duplicating 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?

Opens with a concrete verb+resource ('See what is actually on the canvas') and then defines six distinct modes of inspection, each with its own purpose. An agent can tell immediately that this is a read/inspection tool and what each mode yields, distinct from a drawing or transform 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?

Each op carries an explicit 'Use for...' statement (silhouette read, precise pixel verification, animation review, spacing checks, edit confirmation, reference comparison), plus workflow advice ('Draw, then look, then fix'). No sibling is named, however — the pixel-level 'ascii' op overlaps conceptually with the read_pixels sibling and the description never routes between them.

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, openWorldHint=false, idempotentHint=false. The description adds real behavioral context beyond this: it implicitly separates read ops (get, analyze) from mutating ops (set, preset, load, ramp, extract), warns that 'extract' is RGB-sprite-only, and explains remap/replace effects. It does not cover permission needs or whether writes are reversible, 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?

Front-loaded one-line summary followed by a scannable bullet list keyed by op name. Most sentences earn their place, though the 'ramp' entry runs longer than needed with aesthetic rationale attached.

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

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

With an output schema present, return values need not be explained. For a 12-param, seven-op tool the description covers every op's purpose, the key edge cases (RGB-only extract, replace vs merge), and the ordering caution for palette work — nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is high (92%), so the baseline is 3, but the description adds meaning the schema lacks: it names the bundled preset keys (pico8, gameboy, cga, 1bit, grayscale-8), explains the hue-shift direction of 'ramp', and clarifies that 'extract' quantizes from the art. It leaves some params (base, spread, startIndex) 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?

Opens with a specific verb+resource ('Read and shape the sprite's palette') and then enumerates all seven ops with precise semantics, from 'get' (usage counts) to 'extract' (quantize from art). An agent can distinguish this palette-management tool from siblings like recolor, draw, or look without opening any schema.

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

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

Gives clear contextual guidance ('Use to derive a curated palette from a reference image imported at full colour', 'Decide the palette before drawing'), including the workflow consequence of retrofitting a palette. It stops short of naming sibling tools as explicit alternatives or stating when-not-to-use, so it lands at clear-context rather than full routing.

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

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

The description is genuinely rich about behavior — it explains that every editing tool writes into the live window or into a server-owned headless Aseprite, that there is no fallback, and that switching loses nothing because each side keeps its documents. However, it also states that passing mode changes what the session works with 'from now on', i.e. a persistent state mutation, which conflicts with the readOnlyHint=true annotation. The disclosure itself is strong, but it directly contradicts the structured safety hint, so this is flagged.

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

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

Front-loaded with the action and the 'call FIRST' imperative, then the failure condition, then the mode guidance. It is longer than average but every sentence carries decision-relevant information; nothing is padding.

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

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

An output schema exists (ready/capabilities), so return values need not be described. Combined with the safety, prerequisite, and mode-selection context the description supplies, an agent has everything needed to call this correctly first in a workflow.

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 enum is documented, so the baseline is 3. The description adds meaning beyond the schema by explaining the consequence of the parameter ('which one the session works with from now on'), the conditions that justify switching, and the risk of switching for the wrong reason.

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 ('Check that Aseprite is connected and report what this session can do') and immediately positions itself as the mandatory entry point ('Call this FIRST in any pixel-art task'). An agent can distinguish it from every sibling editing tool without opening a schema.

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

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

Explicit when-to-use ('FIRST in any pixel-art task'), when-to-stop ('stop if ready is false'), when to pass mode ('only because the user asked... or the request plainly needs no window'), and an explicit anti-pattern ('Never switch to get around a live session that is not ready: ask the user instead'). This is about as complete as usage guidance gets.

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, so the read-only behavior is known. The description adds value by describing the output structure ('a list of distinct colours plus a row-major index grid'), which goes beyond the annotation. It doesn't contradict annotations and provides useful context about the tool's non-mutating nature and return format.

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

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

The description is concise: two sentences that front-load the core function, then provide usage context and an alternative. Every word earns its place, with no redundancy or fluff.

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

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

Given the tool has an output schema (as indicated by context signals), the description does not need to detail return values. It covers purpose, usage, and differentiation from a key sibling. With read-only annotations and a fully documented parameter schema, the description is complete for an agent to select and invoke 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?

The input schema has 100% coverage with descriptions for all 5 parameters, including nested 'region' details. The tool description does not add any additional parameter-specific meaning beyond what the schema already provides. Per calibration, with high schema coverage, baseline is 3, and no extra param info is given, so this is appropriate.

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

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

The description clearly states the tool's function: 'Read a rectangular region as structured data: a list of distinct colours plus a row-major index grid.' It uses a specific verb (read) and resource (rectangular region), and explicitly differentiates from the sibling 'look' tool by contrasting computation vs. eyeballing. This allows an agent to distinguish it immediately.

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 explicit usage guidance: 'Use this when you need to compute over pixels (sample a palette from art, find a silhouette edge, copy a region) rather than just look at them. For eyeballing, 'look' is cheaper.' This clearly states when to use this tool and when to use an alternative, leaving no ambiguity.

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

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

The description goes beyond annotations by explaining behavioral details: operations run in one pass so a 64×64 recolour is one undo step, and it emphasizes palette legality and the clampToPalette option. It also clarifies that shade does proper hue shifting (shadows cool, highlights warm). Annotations indicate it's not read-only, which aligns with the mutation described. No contradictions, and the description adds valuable context about how the tool behaves.

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

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

The description is structured with a clear opening statement followed by a bulleted list of ops, making it scannable. While it is fairly long, each sentence adds information about operations or parameters. The front-loaded purpose and op list help an agent quickly grasp the tool's scope. Some redundancy exists (e.g., palette-legal mentioned twice), but overall it's efficient.

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

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

Given the complexity (12 parameters, nested region object), the description is remarkably complete: it explains each op's use case, relevant parameters, and notes on palette behavior and undo granularity. The output schema is present, so return values are covered elsewhere. It could mention edge cases like invalid colors or when clampToPalette might fail, but for an agent deciding to call the tool, it's sufficient.

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 high (83%), but the description adds crucial meaning: it explains the amount parameter with 'negative darkens, positive lightens. One ramp step is roughly 0.15,' defines from/to for replace, and clarifies clampToPalette's role in palette growth. These enrich the raw schema and help an agent select correct parameter values without needing extra inference.

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

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

The description clearly states the tool's purpose: 'Change colours in a region by intent, staying palette-legal.' It then enumerates specific operations (shade, snap, replace, hue_shift, desaturate) with examples, making it obvious what the tool does and how it differs from manual color editing. It's specific and distinct from sibling tools like draw or transform.

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

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

The description provides explicit guidance for each operation, e.g., 'Use this instead of picking a darker hex by hand' for shade, and 'useful for a value check' for desaturate. However, it does not explicitly mention alternative tools or when NOT to use recolor in favor of another sibling, so it's not fully exhaustive but gives solid contextual usage.

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 openWorldHint=false; the description adds real behavior: import lands on a locked, semi-transparent layer above the art; resizing uses nearest-neighbour; a 32×32 reference is a proportion guide, never a finished sprite; grid requires the sprite to already have enough frames. Missing specifics like whether 'remove' is reversible, but coverage is strong.

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

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

Front-loaded with the core purpose, then the op list, then the storyboard/grid mechanism, then the scaling caveat. Dense and mostly waste-free, though the panel-index explanation is slightly elaborate for the space it consumes.

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

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

An output schema exists, so return values need no explanation, and the description covers the four ops, region, and grid for a 12-param nested tool. Gaps remain around 'list'/'remove' semantics and the 'fit'/'opacity' parameters, but nothing critical to correct invocation 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?

With 67% schema coverage and 12 params, the description meaningfully supplements the schema: 'region' crops one panel of the SOURCE image, 'grid' places panel i on frame i of one reference layer, and import's scaling behavior is explained. It does not unpack the 'fit' enum values (contain/cover/stretch) or 'colors'/'opacity' effects, which remains a 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 the specific resource (external image as reference layer) and enumerates the four ops ('import', 'sample_palette', 'list', 'remove') with a one-clause gloss of each. An agent can distinguish this from the sibling 'layer', 'palette', and 'look' tools without opening any schema.

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

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

Gives clear when-to-use context per op: 'sample_palette' reads colours 'without importing', 'region' handles a single panel of a concept sheet, 'grid' handles a storyboard. It never names an alternative tool (e.g. why not use 'palette' to sample colours), so it stops short of the 5 bar.

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 idempotentHint=true. The description adds that the tool reads or changes the selection and that it affects downstream operations, which is useful behavioral context beyond the annotations. No contradiction found.

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 main action and a concise op list. The note about scoping is valuable and adds no fluff.

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 10 parameters, a nested object, and an output schema, the description covers the tool's purpose and effect on other operations. It does not explain return values (output schema exists) or detailed param behaviors (schema covers most). Adequate for agent use.

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 schema provides descriptions for several parameters (mode, color, frame, layer, amount, contiguous, sprite). The description itself only clarifies the 'color' op. With 70% schema coverage, the description adds marginal value over the schema, so baseline 3 is appropriate.

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

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

The description states the verb 'read or change' and the resource 'active selection', then enumerates the supported operations. It clearly distinguishes this tool from drawing/transform/recolor operations by explaining that selection scopes them, which separates it from sibling tools.

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

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

The description explains that a selection scopes draw, transform and recolor, and notes it is cheaper/safer than manual masking. This gives clear context for when to use selection, though it does not explicitly name alternatives or list 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 cover the safety profile (readOnly, not openWorld). The description adds real behavioral value: it is a comprehensive introspection tool, and it names the corruption risk of guessing at layer names/frame counts — an agent-relevant failure mode not encoded anywhere in structured data.

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

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

Two sentences, front-loaded with the full return contents, followed by the usage directive. Every clause earns its place; 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?

Output schema exists, so return values needn't be described in prose. Description enumerates the report's parts, gives usage context, and the schema handles parameter detail. Complete for a read-only introspection 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 coverage is 67%. The description's 'current selection' line complements schema. The sprite param already has a rich schema description (id/filename/display name, omit for focused). includePalette is self-documenting, but includeSlices lacks a schema description — the description doesn't clarify it either.

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 (full structured state of a sprite) and enumerates the exact contents: dimensions, colour mode, palette, layers, frames, tags, slices, selection. Distinguishes itself from siblings like layer, frame, palette which each cover subsets.

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?

Clear directive: 'Read this before editing — guessing at layer names or frame counts is the most common way an agent corrupts someone's file.' Strong when-to-use guidance tied to a concrete failure mode. No explicit when-not-to-use or named alternatives beyond the general edit workflow.

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, idempotentHint=false and readOnlyHint=false, so the safety profile is carried by structured data. The description adds useful operational context beyond that ('Canvas resize keeps existing pixels', what slices are for), but it never says which ops are the destructive ones (close/save), nor that ops act on a session-bound focused sprite. Solid addition, not rich.

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

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

Three dense sentences, front-loaded with the verb/resource scope before the op list and the two clarifying notes. Every sentence contributes (op inventory, resize behaviour, slice semantics); no filler, though the op list is long by necessity.

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, 12-op multiplexed tool with nested objects and an output schema, the description gives an adequate map: full op inventory plus targeted clarifications for the two least obvious families (resize anchor, slices). It stops short of per-op parameter pairing, but the schema's per-field op hints largely cover that.

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 a high 79%, so the baseline is 3, and the description genuinely adds meaning beyond it: the anchor parameter's effect on where existing pixels land, and the purpose of slice fields (nine-slice 'center', hotspot 'pivot'). It clarifies semantics of ops-scoped parameters rather than just restating names.

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

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

Opens with a specific verb list and resource ('Open, create, focus, resize, save and close sprites in the running Aseprite session') and enumerates all 12 supported ops, so the agent knows the exact capability surface. It does not, however, name or differentiate itself from close siblings like sprite_info, transform, or look, leaving that routing to inference.

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 op enumeration and one conditional note ('Omit to use the sprite Aseprite has focused'). There is no explicit when-to-use-this-vs-alternative guidance, e.g. why resize_canvas here rather than transform, or when to prefer sprite_info over 'list'. A capable agent can infer intent from op names, but nothing routes it deliberately.

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

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

The annotations already indicate destructiveHint=true and readOnlyHint=false, so the agent is aware this can modify state. The description adds that untagged spritesheets are unusable by the engine, but it does not disclose behavioral details such as immediate persistence or side effects of update/delete. This is adequate but not rich.

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

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

The description is compact, front-loaded with the core concept, and every sentence earns its place. The first sentence defines the resource and operations, and the second gives a practical workflow warning without padding.

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

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

The description covers what tags are and why they matter, and the schema provides parameter details. However, it does not clarify which parameters are required for each operation (e.g., create vs. delete vs. update), which is a notable gap for correct invocation. Output schema exists, so return-value documentation is not the missing piece.

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 schema already documents several parameters (from, to, color, sprite, repeats), while 'name' and 'newName' benefit only from the description's 'named frame ranges' context. With 56% schema coverage, the description adds some conceptual meaning but does not fully compensate for the undocumented parameters or op-specific requirements.

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

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

The description clearly states the tool manages animation tags (named frame ranges) and enumerates the supported operations: list, create, update, delete. It uses concrete examples like 'idle', 'walk', 'attack' to make the resource unambiguous. It does not explicitly differentiate from sibling tools, but the resource and examples make the purpose clear.

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

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

The description gives a clear workflow cue: 'Tag every cycle before export', and explains why tagging matters. It does not explicitly state when not to use this tool or point to alternatives among the siblings, so it stops short of a 5.

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

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

Annotations only set readOnlyHint=false and openWorldHint=false, leaving the description to carry behavioral detail. It discloses non-obvious behaviors: 'stamp' uses grid cells not pixels, 'pack' deduplicates and hides (not deletes) the source layer, 'blob47' refuses when ordering is wrong, and 'tolerance' has performance implications. This goes well beyond 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?

The description is long but appropriately so for a multi-operation tool. It front-loads the purpose, then lists ops in a scannable bullet format, and adds a rationale paragraph at the end. Every sentence serves a purpose, with no filler. It could be slightly more compact, but the structure aids readability.

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 12 parameters and six operations, the description covers most critical details: output formats, grid semantics, preconditions, and error behavior. An output schema exists (per context), which likely covers return structures. Minor gaps include exact return values for 'list' and 'create_layer', but these are not critical 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 58%, so the description must compensate for undocumented parameters. It explains 'tolerance', 'layout', 'sprite', and 'tiles' in detail, and clarifies grid-vs-pixel semantics. While 'name', 'tileWidth', and 'tileHeight' lack description-level context, they are straightforward from the schema defaults and bounds. The description meaningfully enhances understanding of the complex 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?

The description begins with 'Work with Aseprite tilemap layers' and then enumerates six distinct operations (list, create_layer, get, stamp, pack, export). It clearly states what the tool does and each op has a specific verb and resource. It distinguishes itself from sibling tools like 'layer' and 'export' by focusing on tileset-specific functionality, so an agent can immediately understand its scope.

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

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

The description provides clear guidance on when to use the 'pack' operation ('Painting a level by hand and packing it produces better tilesets than authoring tiles in isolation') and warns about prerequisites ('Requires an extension build advertising the 'tileset' feature — check preflight first'). It does not explicitly contrast with sibling tools like 'layer' or 'export', but the internal op routing is clear and context is sufficient.

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

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

Annotations already declare the mutation/read profile, and the description adds meaningful behavioral context on top: rotation is clean only at 90° multiples, arbitrary angles 'destroy pixel art' and require `allowLossy`, and scaling is nearest-neighbour and integer-only. This is genuinely useful operational disclosure beyond the annotation trio. It does not describe output or failure modes, keeping it from 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 sentences, front-loaded with the verb/resource/scope, then the op list, then the two constraints. Every clause carries information (no selection transform, lossy gating, integer scaling) 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 14-parameter mutation tool with an output schema present, the description covers scope, ops, lossy caveats and the partial-transform workaround adequately. Minor gaps remain, e.g. how translation handles out-of-bounds pixels (clip vs wrap) and the default outline color, but nothing blocking 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 71%, so the schema documents most parameters (axis, side, angle, color, factor, sprite, diagonals, allowLossy). The description still adds value by defining op-level semantics and the integer/90° constraints that explain why `factor` is integer-only and why `allowLossy` exists, which the schema's max/min bounds alone do not convey.

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

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

Opens with a specific verb set and resource ('Move, flip, rotate or scale pixels on ONE cel'), scopes it precisely to 'the target layer's image on the target frame', and enumerates the six ops. It also distinguishes itself from siblings by naming `draw` and ruling out any selection-scoped transform, so an agent can tell it apart from `select`/`draw` without opening schemas.

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

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

Gives a concrete when-not case and a workaround: partial transforms must go through `draw` op 'blit' because 'there is no selection-scoped transform'. It also gates lossy behavior behind `allowLossy` with an explicit 'Ask the user first'. No explicit statement of the ordinary when-to-use happy path, but the boundaries are clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds real value on top by enumerating the inspected fault classes (off-palette, strays, outlines, banding, anti-aliasing, asymmetry, empty layers, untagged frames, timing, volume drift) and promising located evidence. It stops short of saying whether findings block anything or how they are structured.

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

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

Front-loaded with verb + resource, then the check catalogue, then a one-line usage rule and rationale. The long middle sentence is dense but every clause maps to a distinct, verifiable check rather than padding, so it reads as substantive rather than 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?

An output schema exists, so return values need not be described, and parameters are fully covered by the schema. The description is complete enough for a read-only linter: it states what is examined, when to run it, and what kind of result to expect. Only the relationship to the `preflight` sibling is left unaddressed.

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

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

Schema coverage is 100%, and `expect`/`strict`/`sprite` are fully documented in the schema, which sets a baseline of 3. The description earns an extra point by glossing the otherwise opaque `checks` enum values — it explains that 'palette' means off-palette colours, 'strays' means orphan pixels, and so on — adding semantics the bare enum strings do not carry.

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 ('Lint a sprite'), followed by an explicit catalogue of what is checked, so an agent knows exactly what class of operation this is. It falls short of a 5 only because it never distinguishes itself from the sibling `preflight`, which reads as an overlapping pre-export verification 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?

Gives clear timing guidance — 'Run this before telling the user a sprite is finished' — and frames the tool's question as 'is this actually done'. It does not, however, name an alternative or state when this should be skipped in favour of `preflight` or `sprite_info`, so no exclusions are offered.

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