build_plate_with_hole_pattern

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

No annotations are provided, so the description carries full burden. It explains the plate geometry and hole modes but omits critical behavioral details: it does not state whether the tool creates a new part or modifies an existing sketch, whether the holes are destructive (through-cuts) or additive, or what the output is. The phrase 'drawing-grounded through holes' is ambiguous. Missing: required document context, effect on existing features, and return value.

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?

The description is two sentences, each delivering essential information. The first sentence states the core function; the second explains the hole pattern alternatives and coordinate system. No redundant or extraneous text. Well-structured and front-loaded with the most important action.

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?

Given the tool's complexity (14 parameters, no output schema, no annotations), the description is insufficient. It does not explain the broader build context (e.g., requires an active part document? affects existing geometry?), nor does it describe the result type. Sibling tools exist for similar operations, but no guidance is provided on when to use this tool over composing smaller steps. The description leaves many agent decisions unaddressed.

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?

With 0% schema description coverage, the description compensates partially. It adds meaning for `hole_positions_mm`, `bolt_circle_diameter_mm`, `bolt_count`, and the rectangle coordinate system (origin, width, height). However, many parameters remain undocumented: `plane`, `angle_offset_deg`, `reverse_direction`, `bolt_circle_center_x_mm`, `bolt_circle_center_y_mm`. The description covers about 6 of 14 parameters, which is adequate but not comprehensive.

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 clearly states 'Build a rectangular plate and drill drawing-grounded through holes,' specifying the action (build, drill) and resource (plate with holes). It further distinguishes two hole pattern modes (explicit positions vs. bolt circle), which differentiates it from sibling tools like add_bolt_circle or add_drill_pattern that only handle hole patterns without creating the plate.

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?

The description explains the two modes of hole creation ('Use either explicit `hole_positions_mm` or a bolt circle'), giving clear context for parameter usage. However, it does not explicitly state when to use this compound tool versus alternative tools (e.g., build_rectangular_pocket plus add_bolt_circle), nor does it mention any prerequisites or exclusions.

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