Shape hull

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the agent knows this is a non-destructive write. The description adds only '(blob/rounded forms)' as output character; it does not say whether a new shape is created, whether the source nodes are consumed/kept, or what makes repeated calls non-idempotent.

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?

A single compact sentence, front-loaded with the tool family and the operation. Nothing is padded, though the extreme brevity is what leaves the gaps above.

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 mutating geometry-construction tool with no output schema and a 0%-documented schema, the description should explain the input semantics and the effect on the document. Neither is covered, so an agent cannot invoke it confidently beyond guessing that 'inputs' is a node list.

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% and both parameters are bare. The required 'inputs' array of strings is the crux of the tool and is never explained; 'the given nodes' only loosely suggests it is the node list, without saying whether these are IDs, names, or coordinates. The optional 'name' parameter is not mentioned at all.

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 names a specific geometric operation (convex hull) on a specific input (the given nodes), which distinguishes it from sibling primitive-creators like shape_add_box or shape_add_sphere. It stops short of stating that it produces a new shape node in the document, so the verb of effect is implied rather than explicit.

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?

No guidance on when to use this versus the many other shape tools (boolean, extrude, revolve, add_*). The '(blob/rounded forms)' parenthetical hints at an output style but not at a selection condition. An agent gets no routing help in a sibling list of ~150 tools.

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