Paint: batch of operations

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

With annotations covering the mutation/safety profile (readOnlyHint=false, destructiveHint=false), the description adds real context beyond them: the return shape (summary line per op plus one preview) and undo semantics ('rolls back the whole batch step by step'). It also flags the layer-before-use ordering constraint, which the annotations do not.

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 ops structure, layer note, example, and return/undo behavior in a logical order. Longer than a minimal sentence but each block (op list, example, return note) earns its place for a complex batch tool.

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 complex nested-op tool with no output schema, the description covers purpose, item structure, layer handling, and return format adequately. Minor gaps remain (no mention of the 400-item cap or how op-level errors surface beyond stop_on_error), but the essential call-shaping context is present.

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 baseline is 3, but the description adds substantial meaning: it enumerates the available op names, defines the {op, ...params} item shape, shows a concrete multi-op example, and explains the per-item 'layer' field. Op-specific parameters are deferred to the individual tools, which is a reasonable scope boundary.

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 ('Run many drawing operations in ONE call') and frames the benefit ('cheapest way to build a whole scene'). It explicitly distinguishes itself from the 16 sibling paint_* tools by noting every op also exists as its own tool, so an agent can route correctly 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?

Clearly frames when to reach for this tool (multi-op scene in one call) versus the single-op siblings, and explains the layer prerequisite. It stops short of explicit when-not-use guidance (e.g., cost limits, maxItems of 400), but the batch-vs-single tradeoff is well conveyed.

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