Manage sprites

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this tool can mutate state. The description adds one meaningful behavioral detail: canvas resize preserves existing pixels and uses an anchor to position them. It does not go further to explain what 'close' does to unsaved changes or that 'save' overwrites files, but the destructive annotation covers the general risk and the schema's 'force' parameter says to ask the user before discarding changes.

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—two sentences—and front-loads the action verb set before listing operations. The operation list is organized and scannable, and the resize note earns its place by adding targeted behavior not obvious from op names alone. There is no fluff or repetition.

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

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

For a tool with nine operations and nine parameters, the description gives a solid overview but leaves meaningful gaps: it never explains what 'set_properties' changes, nor does it map which parameters belong to which operation (e.g., 'new' likely needs width/height/colorMode, while 'open' needs path). The schema's per-parameter descriptions partly fill this, and an output schema exists, but the description itself still requires the agent to infer operation-parameter pairings. 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 coverage is 67%, and the description does add value by defining what 'list' returns (open documents) and by explaining the anchor's role in canvas resize. The schema already documents path, force, sprite, colorMode, pixelAspect, and anchor, leaving op, width, and height unduscussed in both schema and description; however, op is self-describing via its enum and width/height are intuitive integers. Overall the description complements the schema but does not fully compensate for the minimal param guidance on op-specific required inputs.

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

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

The description uses specific verbs ('Open, create, focus, resize, save and close sprites') and names the resource (sprites in the running Aseprite session), which gives an agent a clear subject and action set. It also enumerates all supported operations, making the tool's scope explicit and distinguishing it from sibling tools that operate on layers, frames, or cels. The title alone is generic, but the description fully specifies what the tool does.

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 sets a clear context—operations inside the running Aseprite session—and gives a list of operations, which implicitly tells an agent this is the sprite-management entry point. However, it does not explicitly state when to prefer this over siblings like sprite_info or layer, nor does it call out exclusions such as 'for layer-only changes use the layer tool.' The resize guidance ('keeps existing pixels — pass an anchor') is useful but is op-level instruction, not tool-selection guidance.

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