Shape extrude sketch

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

Goes beyond the annotations (readOnly=false, idempotent=false, openWorld=false) by disclosing that add/cut replace the target in the tree, that the boolean kernel is manifold/watertight and tolerates coplanar faces, and that distance sign selects direction. It omits error conditions, permissions, and what is returned. Minor tension: 'cut' carves material out of an existing solid while destructiveHint is false, though the description at least discloses the mutation explicitly.

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?

One dense but front-loaded paragraph: the operation leads, followed by plane math, loop semantics, mode/target behavior, and the robustness note. Every clause carries information with no filler, though the run-on density slightly hurts scannability.

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-parameter geometry tool with no output schema and low schema coverage, the description is unusually complete on inputs, plane parameterization, and tree effects. The main gap is return behavior — it never says whether a new item id is produced for mode 'new' — which matters for chaining with tools like shape_set_params or shape_boolean.

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 only 13%, so the description must carry the load and largely does: it defines the plane object (origin/normal/x_axis with x_axis ⟂ normal and y = normal × x_axis), the loops array format with even-odd fill turning inner loops into holes, distance units and sign, and mode/target_id coupling. Only name, color, and surf_id are left unexplained, and those are self-evident.

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+resource with scope: 'draw closed 2D loops on ANY plane and extrude them along the plane normal.' It is clearly distinguishable from sibling geometry tools like shape_push_pull, shape_add_polygon_prism, and shape_boolean because it names the loop-extrusion operation rather than restating its own name.

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 through mode semantics — 'new' makes a separate solid, 'add'/'cut' fuse into or carve out of target_id, which requires target_id (also noted in the schema). However, it never states when to prefer this over shape_push_pull, shape_boolean, or shape_add_polygon_prism, and gives no exclusions or preconditions beyond the target_id note.

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