add_shell

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

With no annotations, the description carries the full burden: it discloses the mutation (hollows the part), the geometric consequence of ordering, and that it returns resulting mass properties. It does not mention error conditions (e.g. thickness too large for the body) or that it replaces the existing body.

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 with the core action, then the parameter grammar, then the ordering caveat and return value. Dense but every clause conveys syntax or behavior; the multi-line layout is readable though slightly sprawling for two parameters.

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?

Two parameters, no output schema, no annotations – the description covers the action, full parameter grammar, ordering behavior, and the return value (mass properties), which is enough to invoke it correctly. Only failure modes and depth/direction beyond the listed axis strings are left implicit.

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 0%, so the description must define the parameters, and it does: open_face accepts "+z"/"-z"/"+x"/..., a "#5" list_faces index, a list mixing both, or "none" for a closed hollow, with a default implied by the examples. thickness_mm is defined by the opening sentence. This far exceeds the schema's bare numeric/anyOf types.

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 ("Hollow the current part to a wall of thickness_mm") plus the effect on faces. No sibling tool performs shelling, and the description makes the operation unambiguous.

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 a clear sequencing rule ("Shell before cutting openings: a shell after them puts a wall along every cut edge"), which is real when-to-use guidance for ordering this against cut/hole tools. It does not name an alternative operation or exclusion, so it stops short of a 5.

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