aseprite_create_animation

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

With no annotations, the description carries the full behavioral burden. It says 'Add' frames, implying mutation of an existing sprite, but never states whether the file must exist, whether existing frames/tags are preserved or overwritten, whether the operation is reversible, or what is returned.

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 covering the three core actions with an inline example; there is no padding. It is efficient, though the parenthetical examples add little beyond the schema's own enum/examples.

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

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

For a 5-parameter mutating tool with no annotations and no output schema, the description omits file preconditions, overwrite semantics, and any return information. The unit mismatch further undermines completeness.

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 would be 3, but the description states durations are in milliseconds ('frame durations (ms)') while the schema defines duration in seconds (e.g. 0.1 for 100ms). This conflicting unit is actively misleading and could cause an agent to pass wrong values.

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 concrete verb+resource (create animation) and enumerates the three operations performed: adding frames, setting durations, and defining tags with examples. It is clearly distinguishable from siblings like aseprite_create_sprite or aseprite_draw_pixels, 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?

No when-to-use guidance, no prerequisites (e.g. that the sprite file at filepath must already exist, or how it relates to aseprite_create_sprite), and no exclusions or alternatives. An agent must infer when this is the right tool.

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