/onshape

name: onshape
description: Protocols for driving Onshape CAD via the onshape-mcp plugin. Render-first and entity-first workflows, unit + coordinate conventions, iteration discipline, when to reach for FeatureScript, and the gotchas (REMOVE-on-face auto-flip, Variable Studios as separate elements, deterministic ID remapping). Load before building anything in Onshape — the plugin's MCP tool surface makes more sense with this doc in context.

Jarvis Onshape MCP — Claude Skill Guide

Loaded as context for any Claude session driving the Jarvis Onshape MCP plugin. Encodes the protocols that keep CAD builds from silently failing. Short, imperative.

Think out loud

Before every non-trivial tool call (sketch, extrude, boolean, fillet, chamfer, describe, export), emit a short plan text (1-3 sentences, plain assistant output) saying **WHY** you're making this call and **WHAT you expect to see / build**. Example before an extrude:

> *"Extruding the base rectangle 30 mm up. Expect a flat plate with the > four corner arcs intact, bbox (500, 780, 30)."*

After each result, also say 1-2 sentences about **what actually happened** — especially if the result surprised you. If a describe_part_studio shows a feature at the wrong Z, name that out loud before deciding how to fix.

Don't let your only visible output be tool-call JSON. The observer watching the run relies on these thought lines to catch bugs in your reasoning.

Units

Onshape's API works in meters. Two safe ways to pass lengths:

• **String with explicit suffix**: `"30 mm"`, `"0.5 in"`, `"15 deg"`. Always unambiguous; prefer this form.
• **Bare number**: treated as millimeters by default (CAD industry norm). `60` means 60 mm.

**Never assume inches** when reading a tool's schema even if the legacy description says "in inches." The builders were ported from an inch-default codebase; the bare-number default is now mm. When a tool response shows unexpected geometry sizes, suspect units first.

This applies on the assembly side too: `transform_instance` translations, `set_instance_position` x/y/z, and every `create_*_mate` / `create_mate_connector` offset accept bare numbers as mm or explicit unit strings. Slider / cylindrical mate `minLimit`/`maxLimit` are lengths (mm-default). Revolute `minLimit`/`maxLimit` are ANGLES in degrees (float). `get_assembly_positions` returns mm in its report text.

Coordinate frames

• **Top plane** = XY, normal +Z. `corner1: [0, 0]` in a Top-plane sketch is on the world origin.
• **Front plane** = XZ, normal **-Y**. Note the sign flip (classic trap).
• **Right plane** = YZ, normal +X.

When sketching on a picked face (`faceId` from `list_entities`), the sketch-local axes are defined by that face's own coordinate system. Geometry you sketch is interpreted in the face's plane, not world space.

The render-first protocol

After every feature that creates or modifies visible geometry:

1. Call `describe_part_studio` (not individual `render_` calls — describe gives structured text + images in one shot). 2. **Verify against expectations in the text** first: is the new feature present in `FEATURE TREE` with status `OK`/`INFO`? Are the expected new faces/edges in `BODIES`? Does `MASS PROPERTIES: volume` line up with what you predicted? 3. If text checks out, glance at the iso view for anything visually off (asymmetric when should be symmetric, missing material, flipped direction). 4. If suspicious, `crop_image` on the specific area. Normalized `[x1,y1,x2,y2]` in `[0,1]`.

Text checks catch arithmetic and counting errors (my weak spot). Image checks catch orientation and topology errors. Neither alone is sufficient.

Sketches: coordinate-first vs constraint-first

`create_sketch` has two surfaces. The right one depends on what you're modeling.

Coordinate-first (simple sketches, 1-3 primitives)

Pass entity dicts without `id` and no `constraints`. Positions are what you type.

{
  "entities": [
    {"type": "circle", "center": [0, 0], "radius": "25 mm"},
    {"type": "circle", "center": [100, 0], "radius": "12 mm"}
  ]
}

Fast. Use for mounting plates, single holes, obvious rectangles. Don't use this when the drawing specifies tangencies, concentricities, or dimensional chains — the solver makes those easy, hand-computed coordinates don't round-trip cleanly.

Constraint-first (drawing transcription)

Give each entity a user-level `id`, list `constraints`. Onshape's solver resolves positions from the constraints.

{
  "entities": [
    {"id": "hub",   "type": "circle", "center": [0, 0],   "radius": "25 mm"},
    {"id": "tip",   "type": "circle", "center": [100, 0], "radius": "12 mm"},
    {"id": "upper", "type": "line",   "start": [0, 25], "end": [100, 12]}
  ],
  "constraints": [
    {"type": "DIAMETER", "entity": "hub", "value": "50 mm"},
    {"type": "DIAMETER", "entity": "tip", "value": "24 mm"},
    {"type": "DISTANCE", "entities": ["hub.center", "tip.center"], "value": "100 mm", "direction": "HORIZONTAL"},
    {"type": "COINCIDENT", "entities": ["upper.start", "hub"]},
    {"type": "COINCIDENT", "entities": ["upper.end", "tip"]},
    {"type": "TANGENT", "entities": ["upper", "hub"]},
    {"type": "TANGENT", "entities": ["upper", "tip"]}
  ]
}

Entity refs are ids with optional sub-point suffixes: `line.start`, `line.end`, `circle.center`, `arc.center`. Seed positions (center, radius on circles/arcs; start/end on lines are optional) are just solver starting guesses — the constraints drive final geometry.

14 constraint types

Entity-ref only (no value): `HORIZONTAL`, `VERTICAL` (lines only), `COINCIDENT`, `TANGENT`, `CONCENTRIC`, `PARALLEL`, `PERPENDICULAR`, `EQUAL`, `MIDPOINT`.

Dimensioned (require `value`): `DIAMETER`, `RADIUS`, `DISTANCE` (with `direction`: `MINIMUM | HORIZONTAL | VERTICAL`), `ANGLE` (value in degrees default; `"90 deg"` / `"1.57 rad"` for units).

Binary pair: `OFFSET` (offset entity ↔ master; pair with a `DISTANCE` constraint on the same