design_update_paint_field

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

No annotations exist, so the description carries the full behavioral burden. It usefully enumerates accepted input forms (shorthand, VectorField JSON, 'algorithm:channelName'), but says nothing about what happens to the prior field beyond 'Replace', whether the layer must be a specific type, error behavior for an unknown algorithm channel, or whether the operation is undoable. That is a significant gap for a mutation tool with zero annotation coverage.

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?

Two sentences, front-loaded with the action, then the accepted input formats. No filler and nothing that could be cut without losing information.

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 two-parameter mutation with no annotations and no output schema, the description covers the input side adequately but leaves the effect side thin: no statement of what the replacement destroys, no layer-type constraint, no failure modes. It is minimally sufficient rather than complete.

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 is 3. The description still adds real meaning beyond the schema: it specifies three accepted formats for `field`, including the 'algorithm:channelName' bridge syntax, which the schema description ('New field shorthand or VectorField JSON') does not mention at all. That is genuine added value.

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?

Names a specific verb and resource: 'Replace the vector field on an existing painting layer.' That is far more precise than a tautology and immediately tells the agent the operation is an update of a field on a layer. It stops short of differentiating against siblings such as design_get_paint_field or design_generate_field_from_points, so a 4 rather than 5.

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?

'on an existing painting layer' and 'Replace' imply this is a mutation of an already-painted layer rather than creation, which gives implicit usage guidance. However, there is no explicit when-to-use versus design_get_paint_field, design_paint_layer, or design_generate_field_from_points, and no stated preconditions. Guidance is implied only.

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