add_chamfer

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

No annotations are supplied, so the description carries the full burden. It discloses the geometric outcome ('round an arc the chamfer is a cone') and the return payload ('number of edges chamfered and the mass properties'), which is real added value, but says nothing about whether the operation mutates/marks the part destructively, permissions, or failure modes.

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?

Information density is high and nothing is pure filler, but the second sentence is a run-on that mixes the from_face rule, an example, and a parenthetical fragment ('round an arc the chamfer is a cone') in one breath. The core action is front-loaded, but the parameter guidance is harder to parse than it needs to be.

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?

With no output schema, the description correctly reports the return value, and with no annotations it is the only source of behavior — yet it omits the name parameter and any statement about mutating the active part. Adequate for calling it, but not complete for a 5-parameter, annotation-free mutation tool.

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 largely does: it documents distance_mm ('distance back along a face'), angle_deg's default and its dependency on from_face, from_face's meaning and format ('-z'), and the full selector grammar for edges. The name parameter is left entirely unexplained, which keeps it out of 5 territory.

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 ('Chamfer edges of the current part') and the geometry it operates on, so an agent immediately knows this is the edge-chamfering operation. It never names or contrasts with the closely related siblings add_fillet and add_full_round, which is what would have earned a 5.

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?

Provides conditional usage rules for the tool itself — 'Another angle than 45° needs from_face' and the printable-underside example at angle_deg=60 — which is genuinely helpful. It gives no guidance on when to choose chamfer over add_fillet/add_full_round or what document state is assumed, so usage is only implied relative to alternatives.

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