Skip to main content
Glama

Hole

hole

Drills parametric bores from sketch circles on body faces, supporting depth/through, counterbore/countersink, threading, and wall-aware direction control.

Instructions

Drill a parametric Hole from a sketch (one or more circles) placed on a face of an existing body feature. Lengths mm.

depth_type: 'Dimension' (use depth) or 'ThroughAll'. cut_type: 'None' | 'Counterbore' | 'Countersink' | 'Counterdrill'; when not 'None', cut_diameter (head clearance) and cut_depth apply. threaded=True taps it. thread_type / thread_size are COUPLED enums ('M4' fits 'ISOMetricProfile', not 'UNC') — discover them with list_thread_options(). intended_for ('print'|'machine'|'drawing'): sets the ModelThread default when threaded. print → modelled thread (a printed pilot won't self-tap); machine/drawing → cosmetic thread (CAM/drawings read the metadata; modelled threads bloat files and fight patterns/fillets). model_thread overrides it. through ('wall'|'body'): preferred over depth_type. 'wall' ray-casts to the first exit and drills exactly one wall — use it on shelled bodies, where 'body' (ThroughAll) destroys the cavity. Implies direction='into_body'; result carries wall_depth_mm. direction ('into_body'|'away_from_body', preferred over the legacy raw reversed, honoured only when neither is set; Hole and Pocket read it differently): picks the Reversed value that does / does not remove material. strict: raise instead of warn on a degenerate hole.

Returns {handle, name, volume, removed_volume, volume_ratio}, plus warnings ONLY when the hole consumed the whole body or removed nothing (strict=True makes those errors). direction='away_from_body' never warns.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "sketch": "<sketch>"
    },
    "name": "hole"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNoHole
depthNo
sketchYes
strictNo
throughNo
cut_typeNoNone
diameterNo
reversedNo
threadedNo
cut_depthNo
directionNo
workspaceNoRun this call in this named workspace
depth_typeNoThroughAll
thread_sizeNo
thread_typeNo
cut_diameterNo
intended_forNo
model_threadNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.5.7
    • addedInput schema / properties / workspace
      Added value: +{
      +  "default": "",
      +  "description": "Run this call in this named workspace",
      +  "title": "Workspace",
      +  "type": "string"
      +}
  2. Changed1 schema field changedv0.5.5
    • addedInput schema / properties / strict
      Added value: +{
      +  "default": false,
      +  "title": "Strict",
      +  "type": "boolean"
      +}
  3. First observed

TDQS

A4.4/5.0
Behavior5/5

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

Goes well beyond the annotations: it discloses the exact return payload {handle, name, volume, removed_volume, volume_ratio}, states that warnings appear ONLY when the hole consumed the whole body or removed nothing, and explains that strict=True converts those into errors. It also warns that 'body' (ThroughAll) 'destroys the cavity' in shelled bodies, which is exactly the failure mode an agent needs to avoid.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded and the per-parameter lines earn their place, but the block is dense and formatted with mid-clause line breaks and telegraphic fragments ('Hole and Pocket read it differently'), which costs scanning speed. Tightening the direction/reversed paragraph would remove most of the redundancy about legacy behaviour.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 18-parameter mutation tool with no output schema, the description covers the operation, the return shape, warning semantics, and the riskiest option combinations. The gaps are the unexplained `diameter`/sketch interaction and no statement that the sketch must be closed and attached to a face, which matters for first-call success.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

This is doing heavy lifting: schema coverage is 6% across 18 params, yet the description explains depth_type, depth, cut_type, cut_diameter/cut_depth, threaded, the coupled thread_type/thread_size enums, intended_for, model_thread, through, direction, reversed, and strict. Two consequential gaps remain: `diameter` (default 5) is never defined or reconciled against the sketch circle geometry, and `name`/`workspace` are unaddressed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource: 'Drill a parametric Hole from a sketch (one or more circles) placed on a face of an existing body feature', which also states the prerequisite input. An agent can distinguish this from siblings like pocket or add_thread because the source geometry and result are named concretely.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives conditional guidance for the hardest choices: through='wall' vs 'body' on shelled bodies, direction over the legacy `reversed`, and intended_for trade-offs between print and machine/drawing. It even routes to list_thread_options() for coupled enums. It stops short of naming an explicit alternative tool (e.g. when to use pocket instead), so it is clear-but-not-exhaustive rather than a 5.

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

Deploy Server

Other Tools