Generate a sprite procedurally

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

No annotations are supplied, so the description carries the full burden. It does add real behavior beyond the schema: animated kinds (slime/ghost/coin/star/torch/tile_water/tile_lava) automatically build a full looping timeline, which is a meaningful side effect an agent must know. However, it omits what happens to existing artwork when a kind is generated, whether the operation is destructive or reversible, and what the call returns.

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

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

Front-loaded with the core value proposition, then the operational details. The long kind list is justified by the absence of an enum in the schema, but it is a single dense sentence that is harder to scan than a grouped listing (base kinds vs. tile kinds vs. animated kinds).

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

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

For a 9-parameter mutation tool with no annotations and no output schema, the description should cover what is returned (asset id? preview? timeline handle) and whether generation overwrites the active project's timeline or layer. It covers kinds and animation well but leaves these return/overwrite questions to inference, which is a real gap at this complexity.

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

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

Schema coverage is 78% (baseline 3), and the description earns above baseline by supplying the complete kind vocabulary where the schema only offers examples like 'hero' or 'tile_water' with no enum constraint. The animated-kinds subset also tells the agent which values trigger timeline generation, a semantic link not present in the schema. Remaining params (frame, layer, frames, durationMs) are left entirely to the schema.

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

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

The description states the resource concretely: procedurally generated, seeded pixel-art 'recipes', then enumerates all 23 valid kinds so the agent knows exactly what can be produced. It implicitly distinguishes itself from drawing-based siblings by emphasizing 'one-call, hand-designed', but does not name sprite_draw_ops or sprite_animate as the 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?

There is one routing hint ('Call sprite_catalog for the full list'), which is more about discovery than alternative selection. The description never says when to prefer this over sprite_draw_ops, sprite_draw_grid, or sprite_quickstart, nor what prerequisites exist (active project, palette). 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.