use_tool

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 – it discloses drag-like point semantics and per-tool point cardinality (curve = 4 points, paint_bucket = 1 point), which prevents malformed calls. It still omits mutation/save side effects, though the save parameter schema partly covers that.

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, front-loaded with the core semantics (how drawing is performed) followed by the tool enumeration. No filler, though the tool list is long and packed into one clause.

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 tool with nested objects and no output schema, the description covers the drawing model and valid tool names but says nothing about coordinate space, color/brush interplay, layer/frame targeting, or live-vs-batch behavior. Adequate for the required call shape, thin for full correct usage.

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% across 20 parameters, so the description must compensate, and it does so for the two required ones – crucially 'tool', which is an untyped string in the schema and only gains valid values from the description. The other 18 parameters (brush, ink, tolerance, tilemapMode, selectionMode, etc.) get no description-level semantics, so it is only partially compensating.

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: drawing with an Aseprite tool by simulating a drag through 'points', and even names the underlying API (app.useTool). It also enumerates the full accepted tool-name space, which lets an agent distinguish this from siblings like draw_shapes, draw_pixels and draw_text.

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 list of supported tools (including selection tools, gradients, contours) signals broad coverage, but there is no explicit when-to-use vs draw_shapes/draw_pixels/draw_text, and 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.