geometry_structured_blocks

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses the empty-session requirement, metre units, cell-count agreement on shared edges, automatic inlet/outlet cap and fluid groups, locked counts, and no arbitrary CAD decomposition. It does not describe error behavior or all mutation side effects, so it is not exhaustive.

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 purpose is front-loaded and the dense detail is necessary for a complex nested geometry recipe. The parameter-map sentence is run-on and could be structured better, but almost every sentence carries actionable information.

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 complex nested parameters, zero schema coverage, and no annotations, the description provides prerequisites, parameter structure, constraints, automatic behaviors, and next steps. An output schema exists, so return values need not be explained, and the remaining gap around generic session fields is minor.

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 description coverage is 0%, so the description must compensate, and it does extensively: it explains the nested parameters object, vertices, edges with kind/vertices/cells/progression/center, faces with signed edge names, span, span_cells, patches, and span_heights. It adds syntax, constraints, and field-level meaning far beyond the empty schema.

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 gives a specific verb and resource: construct connected planar quadrilateral blocks and extrude along +Z in metres. This clearly distinguishes it from sibling geometry tools such as geometry_pipe_oh and geometry_external_cylinder_oh, which create different geometry types.

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 prerequisites (empty session), a direct follow-up action (then call mesh_generate), and explicit alternatives for a sub-task (use mesh_layer_plan or mesh_grading_two_sided to calculate span_heights). It does not explicitly say when to choose this tool over competing geometry-creation siblings, but the geometry type makes that largely implicit.

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