Shape register item

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

Annotations already declare the safety profile (not read-only, not destructive, not idempotent, closed-world). The description usefully adds that the shape is voxelized, becomes a reusable library entry, appears in the Item panel, and can carry FDS fire properties concurrently. It does not flag that idempotentHint=false means repeated calls likely create duplicate catalog entries.

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, front-loaded with the 'Shape Studio:' scoping prefix and no filler. Each sentence adds a distinct fact (voxelize/register, catalog visibility, optional FDS props).

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 9-parameter, no-output-schema mutation tool, the description covers the essential outcome (what is created and where it shows up) and the optional FDS angle. It leaves some gaps around the non-idempotent duplicate risk and the required name/voxel_size pair, but the schema carries defaults and required flags.

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 high (89%), so the baseline is 3, and the description lifts it by tying the 'FDS fire properties' clause to the hrrpua/combustible/material parameters, giving them practical context. It adds little on voxel_size or node_id beyond what the schema 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?

States a specific compound verb (voxelize + register) and resource (reusable library item / furniture catalog), plus the resulting placement behavior. It reads as a clearly distinct operation from siblings like shape_set_item_fds_props or place_furniture, though it never names an alternative to contrast against.

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?

Usage is implied rather than stated: the agent can infer this is the tool to mint a new catalog item after shaping geometry, and the 'optionally set FDS fire properties at the same time' clause hints at a relationship with shape_set_item_fds_props. No explicit when-to-use vs. when-not, and no prerequisites or ordering advice are given.

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