Skip to main content
Glama
onshape-jamcp

onshape-jamcp

Shell

shell

Hollow out a CAD part with uniform walls, either opening selected faces or creating a closed internal void, instead of cutting an inner pocket manually.

Instructions

Hollow out a part with walls of the given thickness. Give remove_face_ids to leave those faces open (a box without a lid, a cup, an enclosure) or hollow_part_ids to hollow a part completely and leave a closed void inside - exactly one of the two. The walls grow inward by default; opposite_direction grows them outward from the original surface. Example: a 40 x 30 x 20 mm box (24 000 mm3) shelled to 2 mm walls with the top face removed keeps 7 152 mm3. Use it instead of cutting an inner pocket by hand with extrude (operation 'remove'); use boolean to combine or subtract whole parts. The face IDs come from get_body_details. It appends one shell feature and returns its health plus effect (parts and total volume before and after) and a warning when nothing changed: Onshape can accept a feature that does nothing, so read it: a wall too thick for the part is accepted as OK and changes nothing (a 50 mm wall on a 40 x 30 x 20 mm box answered OK with the volume unchanged), and only that warning tells you. Remove it with delete_feature.

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": {
      "document_id": "<document_id>",
      "element_id": "<element_id>",
      "thickness": "<thickness>"
    },
    "name": "shell"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNoFeature name (default 'Shell 2 mm').
verifyNoMeasure the Part Studio before and after (two extra requests) and report what changed: part count and total volume, plus a warning when nothing changed (Onshape can accept a feature that does nothing). Set false to save requests.
thicknessYesLength: a number in the configured unit (see get_settings; mm by default), a string with a unit such as '2.5 in', or an Onshape expression such as '#width'.
element_idYesElement (tab) ID: the string after /e/ in the Onshape URL. Get it from get_document.
document_idYesOnshape document ID: the 24-character hex string after /documents/ in the document URL. Get it from list_documents.
workspace_idNoWorkspace ID (the string after /w/ in the URL). Optional - defaults to the document's main workspace.
hollow_part_idsNoParts (list_parts) to hollow out completely, leaving a closed void inside. Give exactly one of remove_face_ids and hollow_part_ids.
remove_face_idsNoFaces to open up (from get_body_details): the part becomes a hollow shell open at these faces, like a box without a lid. Give exactly one of remove_face_ids and hollow_part_ids.
opposite_directionNoGrow the wall outward instead of inward.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.1.1

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare it is a non-readonly, non-destructive, non-idempotent mutation, but the description adds real value: it appends one `shell` feature, returns health plus an `effect` volume report, and warns when nothing changed. The pitfall about Onshape accepting a no-op wall (50 mm wall on a 40x30x20 mm box answered OK with unchanged volume) is exactly the kind of behavior an agent cannot infer from structured fields. It stops short of stating the return shape in full or permissions, so not a 5.

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

Conciseness4/5

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

The definition is front-loaded: mode selection first, then direction semantics, then alternatives, then the failure mode. The worked volume example (40x30x20 mm, 24 000 mm3 to 7 152 mm3) is somewhat verbose but is doing explanatory work alongside the no-op warning; a slightly tighter recounting would read better.

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

Completeness5/5

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

For a 9-parameter geometry mutation with annotations and an output schema, the description covers the mode choice, direction, alternatives, ID provenance, the appended feature, the returned `effect`, and the silent-failure case. An agent has everything needed to invoke it and to read its result correctly.

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?

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by contrasting the two face/part modes semantically (open shell like a box without a lid vs. a closed internal void) and by explaining that walls grow inward by default and outward with `opposite_direction`. It does not add unit or expression syntax for `thickness` beyond what the schema already documents.

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?

The opening sentence gives a precise verb and resource: 'Hollow out a part with walls of the given thickness.' It then explicitly carves out its territory against `extrude` (inner pocket by hand) and `boolean` (combine or subtract whole parts), so an agent can distinguish it from siblings without reading schemas.

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

Usage Guidelines5/5

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

It states the selection rule ('exactly one of the two') between `remove_face_ids` and `hollow_part_ids` and names the sibling alternatives with the condition that selects them. It also tells the agent where the face IDs come from (`get_body_details`), removing the main prerequisite ambiguity.

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