add_hole

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

Annotations already declare destructive=true, idempotent=false and readOnly=false, so the risk profile is covered structurally. The description usefully adds the unit convention (mm, degrees, kg) and hints that the result should be checked for measurements and error evidence, but it never says what geometry is removed, whether a body must exist, or that repeated calls create duplicate holes.

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?

Three short sentences with no padding, and the action is front-loaded. The final sentence ("Inspect verified measurements and error evidence") is vague and does not tell the agent concretely what to do or expect, weakening the structure.

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 destructive mutation with no output schema and zero schema annotation, the definition leaves significant gaps: no return-value expectation beyond a vague hint, no placement semantics, and no disambiguation among the crowded set of hole-creating siblings. The unit statement is a helpful addition but not enough to make it complete.

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% across four parameters, so the description carries the burden, yet it only confirms that *_mm parameters are in millimetres. It never explains that x_mm/y_mm are the hole centre location on the sketch plane, what "name" identifies, or that diameter must be positive.

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 states a verb and resource ("Add hole") and names the engine, so the basic action is clear. But it never says what kind of hole (simple through-hole?), where it is placed, or how it differs from the many hole siblings such as add_counterbore_hole, add_hole_on_face, and add_hole_wizard, which the agent must pick between.

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?

There is no when-to-use guidance at all: no mention of prerequisites (an open part, sketched coordinates), no exclusions, and no routing to alternative hole tools. "Through the independent native SOLIDWORKS engine" hints at an execution backend but not at usage conditions.

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