design_add_shore

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

With no annotations at all, the description carries the full behavioral burden; it does disclose the visual output (foam, debris, wet/dry gradient) which is real value. However it never states whether this mutates the active sketch, whether a water layer must already exist, how the new layer is ordered relative to it, or what happens on failure.

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?

Three sentences, all front-loaded with the identity of the layer first, then rendering behavior, then placement instruction, then presets. No filler and nothing repeated from the schema beyond a useful preset recap.

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 11-parameter, zero-annotation, no-output-schema tool, the definition explains what is drawn but leaves out the operational essentials: sketch/workspace context, dependency on an existing water layer, and layer stacking. An agent could call it successfully but may misorder layers or call it without water present.

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% across all 11 parameters, including enums for preset, debrisType and atmosphericMode, so the schema does the heavy lifting. The description only reinforces the preset list (already in the enum) and the waterline matching relationship, adding no syntax or default detail beyond the schema. Baseline 3 applies.

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 gives a specific verb and resource ('Add a shore/coastline transition layer between water and land') and enumerates exactly what the layer renders (foam lines, debris, wet/dry gradients), which clearly separates it from pure water or terrain tools. It stops short of naming a sibling (e.g. design_add_water_surface) as the complementary tool, so the reader must infer the boundary.

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?

It gives concrete placement guidance ('Position it at the same waterline as your water layer') and enumerates the six available presets so the agent knows the intended usage path. There is no statement of prerequisites (must a water layer exist first?) or when not to use it versus design_add_river or design_add_terrain_profile.

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