Change appearance

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

Annotations already establish idempotent, non-destructive, write behaviour, and the description adds genuinely new context: that a figure colour propagates to every keyframe containing the figure and that a part colour mutates the shared figure definition so all instances change. That cascading side effect is exactly the kind of hidden blast radius an agent needs. It stops short of saying whether changes are undoable via history_undo or what an invalid colour yields.

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?

Four sentences, front-loaded with the capability statement, then the two non-obvious propagation rules, then value formatting. The opening sentence is a long enumeration but every clause maps to a distinct target, so nothing is wasted.

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 10-parameter mutation tool with no output schema, the description covers what each target restyles, the indirect effects, and the value format, while the schema handles per-parameter applicability. It leaves the return value and error behaviour unexplained, but with 100% schema coverage and safety annotations those are modest omissions.

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 schema already documents all ten parameters including per-target applicability (uid, layerId, handleId, frames). The description adds colour syntax ('#rrggbb' or three RGB bytes), but its blanket statement omits the layer special case where the schema requires a palette name — a small gap that the schema has to correct.

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 a specific verb (change) plus the exact resources it applies to — figure colour/opacity, part colour/thickness, layer colour, and scene background — which maps cleanly onto the four `target` enum values. This differentiates it from nearby mutators such as figure_transform and layer_edit, which touch geometry and layer metadata rather than appearance.

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 by the enumeration of targets, and the scope rules ('a figure colour applies to every keyframe the figure appears in', 'a part colour changes the shared figure definition') tell the agent the consequences of choosing one target over another. However, no sibling tool is named as an alternative, and there is no explicit when-not-to-use guidance (e.g. when to prefer layer_edit or figure_transform).

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