Build and edit terrain

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, but the description adds extensive behavioral detail: terrain snaps to a 4-stud voxel grid, positions are the centre of the solid, fill applies multiple solids as one undo step, clear with confirm=true wipes everything, stats cannot report where terrain is because Roblox exposes no bounding box, and carving is done via Air material. These insights go far beyond the annotations and give the agent a realistic model of the tool's side effects and limitations.

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 long but every sentence carries essential information: the core purpose, the differentiation from instance tools, per-operation details, shape requirements, carving, position/grid behavior, and advice for usage. It is front-loaded with the most important fact (what it does) and then progresses logically. No filler or repetition; the length is justified by the tool's complexity.

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?

Given the tool's complexity (multiple operations, shapes, carving, destructive potential) and the lack of an output schema, the description covers everything an agent needs: all operations and their semantics, parameter details, positional conventions, grid snapping, undo behavior, and strategic advice (call stats first, use screenshot). Nothing critical is missing for correct invocation.

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?

While schema coverage is 100%, the description enriches the parameters significantly. It explains that `fill` takes an array of solids and applies them as a single undo step, that `replace` swaps materials without changing shape, that `clear` can be scoped to a region or globally with confirm, and that `stats` only reports presence, not location. It also ties shape types to their required parameters (e.g., block needs size, ball needs radius) and explains the carving mechanic via Air. This is value beyond the schema's brief property descriptions.

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 first sentence states exactly what the tool does: 'Fills, repaints and clears Roblox terrain — hills, water, caves, roads.' It uses specific verbs and a resource, and clearly distinguishes itself from instance tools by explaining that terrain is not made of instances and that this is the only way to shape it (besides hand-written FillBall calls). This unequivocally differentiates it from siblings like create, modify, and delete.

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 states when to use this tool: 'none of the instance tools reach it: there is nothing to create, no path for find, and no property for modify. This is the only way to shape it short of writing FillBall calls by hand through execute_luau.' It also gives tactical advice, such as calling `stats` first in an unfamiliar place and taking a `screenshot` to see the shape. This covers both when to use and what alternatives exist (execute_luau), leaving nothing to inference.

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