Shape export obst

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

Annotations establish a non-destructive write; the description adds real behavioral context: the voxels sit on FDS cell boundaries via align_to_mesh (no +/-1 snapping), origin repositions the bbox and 'breaks mesh alignment', and voxel_size is ignored when align_to_mesh is set. It does not mention permissions, side effects on the shape, or whether the source shape is consumed, but the alignment/snapping semantics are valuable beyond the annotations.

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?

Front-loaded purpose followed by dense, earning sentences covering alignment, size overrides, mode, and origin. Slightly cluttered by the trailing '[bulc-mcp rules]' reference, but overall efficient for an 8-parameter tool.

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 8-param, no-output-schema write tool, the description covers all the semantic decisions an agent must make (alignment, sizing, fill mode, positioning). It is complete enough to invoke correctly, with only minor gaps around side effects and source-shape handling.

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 100%, so the baseline is 3, but the description adds precedence rules the schema does not state (cell overrides voxel_size; voxel_size ignored under align_to_mesh) and concrete examples for shell mode ('hoods, ducts, funnels, open imported STL'). It enriches the interaction between parameters rather than restating them.

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 verb and resource: 'voxelize the shape ... and add it to the model as an obstacle with voxel geometry.' It distinguishes itself from sibling geometry tools and obstacle-creation tools by naming the exact transformation (Shape Studio -> FDS). An agent can identify this as the shape-to-obstacle conversion step without opening a schema.

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?

Gives strong conditional guidance: 'Recommended: align_to_mesh=true', shell vs solid based on whether the mesh is hollow, and voxel_size vs per-axis cell. It does not name alternative tools (e.g. shape_preview_voxels or add_obstacle) or state when not to use this tool, so routing vs siblings is left implicit.

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