Create terrain

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

Annotations only signal readOnlyHint=false, openWorldHint=true, destructiveHint=false; the description carries the behavioral burden and delivers—stating it 'Creates a new baseCOMP under parent_path,' exposes Height/Drift/WaterLevel/Zoom controls, and details the JSON return payload (container path, node paths, output path, errors, warnings, inline preview). No contradiction with annotations exists.

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 longer than average (about eight sentences) but front-loads the core purpose and every clause adds information: pipeline components, optional water/fog, sibling distinction, creation path, exposed controls, and return format. It is on the verbose side but contains no filler.

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 13-parameter creation tool with no output schema, the description covers the full build pipeline, optional behaviors (water, fog), create location, live controls, and exactly what the return payload contains. Prerequisites and failure modes are not spelled out, but node errors/warnings are part of the declared return, keeping this sufficiently 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?

With 100% schema-description coverage, the schema already documents all 13 parameters, so the baseline is 3. The description adds only marginal value—mapping exposed controls (Height, Drift, WaterLevel, Zoom) to the UI—and references water_level in context, but does not clarify anything the schema descriptions leave ambiguous.

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 opens with a specific action—'Build a procedural heightmap landscape'—and enumerates the exact pipeline (Noise TOP, Grid SOP, GLSL vertex-displacement MAT, light, camera, render). It explicitly differentiates itself from create_visual_system's 'terrain' keyword, which is the closest sibling. The verb+resource+technical scope fully anchors the tool's purpose.

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 explicitly names the main alternative: 'Distinct from create_visual_system's "terrain" keyword… this is a dedicated, fully parameterized terrain pipeline with its own displacement material, water, and fog.' This communicates when the more complete pipeline is needed versus the simpler recipe mapping. It does not enumerate every terrain-adjacent sibling, but the primary confusion point is directly addressed with a clear when-not distinction.

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