design_add_water_surface

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

With no annotations, the description must carry the full behavioral burden. It discloses that the tool adds a layer and renders a gradient fill with wave lines and shimmer highlights, but it does not clarify whether the layer is editable, where it is inserted in the layer stack, whether it affects existing layers, or whether the operation is reversible.

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 two concise sentences, front-loaded with the core action and followed by useful preset and rendering details. Every sentence contributes to understanding and there is no 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?

The description covers purpose, preset options, and visual output for a 5-parameter creation tool with no annotations and no output schema. It is adequate but leaves important gaps around usage relative to related water tools and the side effects or editability of the added layer.

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 100%, so the baseline is 3. The description names the preset options in prose, matching the enum in the schema, but adds no extra meaning for name, seed, waterColor, or waterlinePosition beyond what the schema already documents.

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 and resource: 'Add a water surface layer to the sketch.' It clearly identifies the tool as a layer-creation operation for water surfaces and names the available presets. It does not, however, explicitly differentiate this from nearby water-related siblings such as reflection, foam, shoreline, caustics, or ice.

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 no guidance on when to use this tool versus alternatives like design_add_river, design_add_shore, or the water reflection/foam/caustics/ice tools. It only says to choose from presets, which is selection advice rather than usage context or exclusions.

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