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

There are no annotations, so the description carries the full burden of behavioral disclosure. It adds useful traits: the layer is a native vector shape, and omitted x/y/w/h defaults to canvas center. However, it says nothing about return values, reversibility, or the important default timeline behavior (persistent overlay) that is only described in the block parameter schema.

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 description is front-loaded with the core action, and the long shape list earns its place by disambiguating the `kind` enum. The image-layer warning and default-position note are compact and add real decision value without padding.

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 tool with no output schema and no annotations, the description is serviceable but not fully self-contained. An agent still must rely on the block schema to learn that omitting the block creates a persistent overlay and that passing it creates a bounded clip; return/output behavior is also unspecified.

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 description coverage is only 38%, so the description needs to compensate, and it does for key params: it explains that `kind` selects a primitive and lists the allowed values, and clarifies that omitted x/y/w/h places the shape at the canvas center. The schema already documents block, color, and projectId, leaving only coordinate units and width/height semantics implicit.

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 starts with a specific action and resource, 'Add a shape layer,' and enumerates the exact primitive kinds, making the tool's scope clear. It also distinguishes itself from image layers with 'never substitute an image layer for one,' though it doesn't explicitly name sibling alternatives like add_text_layer or add_curve.

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?

The description gives clear context for when to use the tool: for native vector shapes, and explicitly warns against using an image layer instead. It also provides a useful behavioral hint by saying default placement is canvas center if x/y/w/h are omitted, which helps agents decide whether to supply geometry. It doesn't discuss when to prefer other layer-adding siblings.

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