build_from_grid

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

With no annotations, the description carries the full behavioral burden, and it does disclose the observable side effects: which meshes and empties are created and under what naming convention. It stops short of stating whether existing objects with those names are overwritten, whether the operation is idempotent, or what the return payload looks like.

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?

It is dense but front-loaded: the core action and coordinate convention come first, then the character legend, then derived outputs and validation workflow. Nearly every clause carries information, though the legend/kinds enumeration is packed tight enough that a heavier markdown structure would have aided scanning.

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 10-parameter generative tool with no output schema and no annotations, this description covers a great deal: input format, coordinate orientation, character semantics, legend override syntax, generated object names, and a follow-up validation path. It is only incomplete on the undocumented tuning parameters (origin, wall_height, floor_thickness) and on overwrite/return behavior.

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 coverage is 0%, so the description must compensate, and it meaningfully documents layout (row 0 = top/+Y, column 0 = left), cell (metres, with 1 vs 0.5 guidance), legend (with a concrete JSON example and the full kind list), and ties cover_fill, door_height and cover_height to their in-layout characters. Gaps remain: origin, wall_height and floor_thickness are never explained, so it does not fully close a 10-parameter documentation deficit.

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 ('Block out a level from a text plan') and immediately defines the input format, so the agent knows exactly what this produces without consulting the schema. It also names the concrete artifacts created ({name}_floor, {name}_walls, {name}_cover, {name}_spawn_1 empties), which separates it from verification siblings like walkable_map and route.

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 states the scenario ('block out a level from a text plan') and prescribes a follow-up workflow ('Then prove it with walkable_map, route, check_passages, sightline_map'), which tells the agent both when to call this and what to call next. It also gives a scaling heuristic ('use 1 for rooms, 0.5 for detail'). There is no explicit when-not-to-use guidance, keeping it short of a 5.

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