design_add_layer

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

With no annotations, the description carries the full burden. It does add real behavioral detail for the painting path feature (linear interpolation from depth=0 to maxDepth, clamping beyond maxDepth, multi-pass channel reuse), but it omits what the tool returns (no output schema and no mention of a layer ID), what happens with an unregistered type, and how available layer types can be discovered.

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?

The core purpose is front-loaded in one sentence before the painting special case, and the depthMapping example earns its length by being directly copy-adaptable. Some redundancy exists (type IDs are repeated from the schema) and the painting block is dense, but nothing is truly 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 an 8-parameter mutation tool with no annotations and no output schema, the description covers the hardest part (painting stroke properties) but leaves notable holes: no return value, no error behavior for invalid types, no pointer to how to enumerate registered layer types, and no guidance on blendMode or transform interplay despite related siblings like design_list_blend_modes existing.

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, but the description goes further by documenting the four keys that go inside the untyped `properties` object (pathSource, pathBrushId, pathColor, depthMapping) with concrete value examples and a full depthMapping JSON sample. That is genuine value the schema cannot provide, since `properties` is declared as additionalProperties:{}.

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 ('Add a new design layer of a given type to the active sketch') and enumerates concrete type IDs, so an agent knows exactly what the tool creates. It does not, however, distinguish itself from overlapping siblings such as design_add_shape, design_paint_layer, or design_add_solid, which can plausibly produce the same 'shapes:rect' or painting results.

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 only implied: the layer-type enumeration and the painting:stroke section suggest when this tool is appropriate, but there is no explicit 'use X instead when Y' guidance against the many sibling creation tools, and no stated prerequisite (e.g. whether a sketch must be active/selected). The painting subsection is the only place a concrete scenario is spelled out.

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