Add a part or sub-assembly instance to an assembly

Position source instance flush against a face of target instance. Faces: front (min Y), back (max Y), left (min X), right (max X), bottom (min Z), top (max Z). Only moves the perpendicular axis; other axes stay unchanged.

Check for overlapping/interfering parts in an assembly using bounding box detection. Returns which parts overlap and by how much.

Render your current Part Studio at iso/top/front/right and COMPOSITE the result directly under a reference image from disk. Returns a single side-by-side PNG: reference on top, your build's 4 views on the bottom row, both at the same horizontal extent so silhouettes line up visually. Use this whenever you want to cross-check feature count / placement / proportion against the brief's reference figure — it removes the need to squint back and forth across separate images. The reference path you pass is a filesystem path readable by the MCP server (typically the brief's iso or drawing PNG).

Create a new Assembly in an existing document

Perform a boolean operation (union, subtract, intersect) on bodies

Create a chamfer (beveled edge) on one or more edges

Create a circular pattern of features around an axis

Create a cylindrical (slide + rotate) mate between two assembly instances. The first instance slides and rotates relative to the second along the mate connector Z-axis. Requires face IDs from Part Studio body details. Optional offsets shift connectors from face centers.

Create a new Onshape document. Returns the documentId AND the main workspaceId AND the default Part Studio elementId in one shot — no need to follow up with get_document_summary + find_part_studios before you start building.

Create an extrude feature from a sketch

Create a fastened (rigid) mate between two assembly instances. Requires face IDs from Part Studio body details to place mate connectors on specific faces. Optional offsets shift connectors from face centers (in the face's local XY plane + Z along normal).

Create a fillet (rounded edge) on one or more edges

Create a linear pattern of features. Requires a deterministic edge id whose direction the pattern will follow — Onshape has no implicit world-X axis usable here. Workflow: create a reference (a sketch line on any plane pointing the direction you want, or pick an existing body edge via list_entities), then pass its id as directionEdgeId.

Create an explicit mate connector on a face of an assembly instance. The connector is placed at the face center with its Z-axis along the face normal. Offsets are in the connector's LOCAL coordinate system (X/Y in-plane, Z along normal). Flipping the Z-axis also reverses the other axes via the right-hand rule, which affects how offset translations map to world space.

Create an offset construction plane: a datum plane parallel to a reference plane or face, shifted by a signed distance. Use when you need to sketch at a specific Z (e.g. 2.5 mm above the Top plane) without an existing face there. Pass a plane (Front/Top/Right) to offset from a standard datum, OR a referenceFaceId (from list_entities) to offset from a face. The new plane becomes a sketch target — pass its feature_id as the faceId arg to any sketch primitive.

Create a new Part Studio in an existing document. Returns the new Part Studio's elementId AND a list of other Part Studios in the same workspace (so callers don't accidentally target the empty default 'Part Studio 1' that most fresh Onshape documents ship with). Prefer this tool's returned elementId over re-enumerating via find_part_studios.

Create a revolute (rotation) mate between two assembly instances. The first instance rotates relative to the second around the mate connector Z-axis. Requires face IDs from Part Studio body details. Optional offsets shift connectors from face centers.

Create a revolve feature by rotating a sketch around an axis

Create a rounded rectangle sketch (4 lines + 4 tangent corner arcs) in ONE feature. Use instead of hand-rolling 4 lines + 4 arcs with the per-primitive tools -- fewer turns and no radians/degrees mistakes. Sketch location: pass either plane (Front/Top/Right) or faceId (from list_entities). faceId wins when both are given. cornerRadius must be > 0 and no more than half the short side of the bounding rect (otherwise there'd be no straight segments left).

Hollow out a solid body into a thin-walled shell. Pass the face IDs (from list_entities) you want REMOVED; the remaining faces become the shell wall. Inward by default — the outer bounding box is preserved and material is eaten inside. Returns the standard {ok, status, feature_id, changes?} contract.

Create ONE sketch feature atomically. Two surfaces in one tool:

Coordinate-first (legacy, for simple sketches): pass entity dicts without id and no constraints. The builder hand-computes positions from your coordinates. Fast for 1–3 primitives where you already know where everything goes.

Constraint-first (for drawing transcription): give each entity a user-level id, list real-world constraints between them, and let Onshape's solver resolve positions. This is how the UI works and how engineering drawings are specified.

Sketch location: pass either plane (Front/Top/Right) or faceId (from list_entities or the feature_id of a create_offset_plane). faceId wins when both are given.

Coordinate-first entity types

rectangle: {type, corner1:[x,y], corner2:[x,y], variableWidth?, variableHeight?} rounded_rectangle: {type, corner1:[x,y], corner2:[x,y], cornerRadius} circle: {type, center:[x,y], radius, variableRadius?, variableCenter?:[xv,yv]} line: {type, start:[x,y], end:[x,y]} arc: {type, center:[x,y], radius, startAngle?, endAngle?, variableRadius?, variableCenter?:[xv,yv]}

Constraint-first entity types (require id)

line: {type:'line', id, start:[x,y]?, end:[x,y]?, construction?} circle: {type:'circle', id, center:[x,y], radius, construction?} arc: {type:'arc', id, center:[x,y], radius, start_angle?, end_angle?, short_arc?, construction?} — short_arc defaults true: if CCW sweep > 180° the builder silently swaps endpoints so the arc goes the short way (matches Onshape UI's three-point-arc default). Set false for the explicit long-way case. point: {type:'point', id, at:[x,y]?, construction?}

Circle / arc SEEDS (center + radius) are required even when a DIAMETER or RADIUS constraint will drive the final value — Onshape's solver needs a starting guess. Line start/end are optional; seed to [0,0] when omitted and let COINCIDENT / TANGENT constraints pull endpoints into position.

Constraints (constraint-first surface only)

Each item: {type, entities?:[id,...] | entity?:id, value?, direction?}. Entity refs are ids, optionally with a sub-point suffix: line.start, line.end, circle.center, arc.center Supported types: Entity-ref only: HORIZONTAL, VERTICAL (LINES ONLY — not points), COINCIDENT, TANGENT, CONCENTRIC, PARALLEL, PERPENDICULAR, EQUAL, MIDPOINT Dimensioned: DIAMETER, RADIUS, DISTANCE (add direction: HORIZONTAL|VERTICAL|MINIMUM), ANGLE (value in degrees by default — string "90 deg" / "1.57 rad" for explicit units) Binary pair: OFFSET (offset entity + master — pair it with a DISTANCE constraint on the same two for the offset length) Aliases: HORIZONTAL_DISTANCE → DISTANCE(direction=HORIZONTAL), VERTICAL_DISTANCE → DISTANCE(direction=VERTICAL), LENGTH → DISTANCE(direction=MINIMUM) (for line-length or slot end-to-end dimensions). POINT_ON is NOT a separate type — use COINCIDENT with a point sub-ref.

Pinning to the sketch origin

There is no magic origin keyword. To anchor geometry to the sketch plane origin (prevents drift on parametric resize), add a point entity at [0,0] and COINCIDENT to it: entities: [{id:'origin', type:'point', at:[0,0]}, ...] constraints: [{type:'COINCIDENT', entities:['hub.center', 'origin']}, ...] This gives you a sketch-local anchor the solver treats as fixed.

Bare numbers are mm; pass strings like "10 mm" / "0.5 in" for explicit units.

Create an arc sketch. Pass either plane (Front/Top/Right) or faceId (from list_entities) to choose the sketch surface. faceId wins when both are given.

Create a circular sketch. Pass either plane (Front/Top/Right) or faceId (from list_entities) to choose the sketch surface. faceId wins when both are given.

Create a line sketch. Pass either plane (Front/Top/Right) or faceId (from list_entities) to choose the sketch surface. faceId wins when both are given.

Create a rectangular sketch in a Part Studio. Sketch location: pass either plane (standard datum: Front/Top/Right) or faceId (deterministic ID of a face from list_entities). Pass faceId to sketch on an existing part face; if both are given, faceId wins and a warning is returned.

Create a slider (linear motion) mate between two assembly instances. The first instance slides relative to the second — positive travel moves the first instance along the face normal direction away from the second. Swap instance order to reverse slide direction. Requires face IDs from Part Studio body details. Optional offsets shift connectors from face centers.

Create a thicken feature from a sketch

Create a Variable Studio element in a workspace. Required before set_variable on modern Onshape docs -- the legacy Part Studio /variables write path is read-only. Returns the new VS element id; use it as elementId for set_variable / get_variables.

Zoom into a region of a cached image by normalized 0..1 bounding box. Use after render_* when you need to inspect a detail — a specific face, a feature edge, a suspicious fillet. (0,0) is top-left, (1,1) is bottom-right. Returns a new image keyed by its own image_id. This is the pattern behind Anthropic's CharXiv 84.7 -> 91.0% 'with tools' benchmark result; use it liberally.

Move an Onshape document to the trash. Irreversible via the API; intended for cleanup of throwaway docs created by an agent (test/iteration runs). Returns {ok, status, document_id}.

Delete a feature from a Part Studio or Assembly

Delete a Part Studio feature by its display name (e.g. 'Extrude 10mm', 'Sketch 1') without having to look up the feature ID first. Returns ERROR if zero or multiple features match the name so the caller can disambiguate.

One-shot snapshot of a Part Studio's entire design state. Returns BOTH a structured text representation (feature tree with statuses, body topology with every face and edge classified by type + deterministic ID + coordinates, bounding box, mass properties) AND the multi-view rendered images (iso/top/front/right by default). Use this INSTEAD OF chaining get_features + list_entities + render_part_studio_views + get_mass_properties after every mutation. The text is what you reason over (reliable for you). The images catch visual regressions the text misses. Image_ids returned in the text can be cropped via crop_image.

Iterate on an existing sketch without rebuilding it. Pass any of addEntities, addConstraints, removeIds and the server fetches the current BTMSketch-151, splices the lists, and re-POSTs. Use this for the second/third pass on a sketch (adding a hole pattern after the outline lands; tightening a constraint after a regen check) instead of delete+recreate.

Add semantics are STRICT: every entity/constraint dict must carry a non-empty id string and ids may not collide with anything already on the wire. To retarget an id, removeIds it first and then addEntities it back.

removeIds is a single bag matched against entity ids AND constraint ids. Cascade: any constraint whose entities/entity (or sub-point ref like line1.start) names an entity in removeIds is auto-dropped and reported back in cascaded_removals so you see exactly what got pulled.

Evaluate a FeatureScript expression in a Part Studio (read-only, for querying geometry)

Export an Assembly to STL, STEP, or GLTF. Blocks until Onshape finishes the translation, downloads the bytes, and writes them to /tmp/onshape-mcp-exports/. Returns on-disk path, size, and final state.

Export a Part Studio to STL, STEP, PARASOLID, GLTF, or OBJ. Blocks until Onshape finishes the translation, downloads the bytes, and writes them to /tmp/onshape-mcp-exports/. Returns the on-disk path, size, and final state so the user can open the file. Raises an explicit error on FAILED or timeout.

OCR a drawing PNG and return every numeric callout it can read, grouped by kind: length / radius / diameter / thread / angle / count / scale. Each callout includes pixel-position so you can map it to a specific feature in the drawing (compare against your view of the image). USE THIS BEFORE READING DIMS BY EYE — Tesseract is more reliable than your vision pass on small text. Known limit: Ø often misreads as '9' (e.g. 'Ø50' → '950'); cross-check high-significance dims with crop_image at native resolution.

Find Part Studio elements in a specific workspace, optionally filtered by name

Get assembly structure including instances and occurrences

Get all features (mates, mate connectors, etc.) from an assembly with their current state (OK, ERROR, SUPPRESSED). Useful for inspecting existing mates and debugging assembly issues.

Get positions, sizes, and world-space bounds of all instances in an assembly (in mm).

Get face-level geometry details for all parts in a Part Studio. Returns face deterministic IDs, surface types (PLANE, CYLINDER, etc.), and for planar faces: normal vectors and origin points. Use face IDs with mate connector tools.

Get the tight bounding box of all parts in a Part Studio

Get detailed information about a specific document

Get a comprehensive summary of a document including all workspaces and elements

Get all elements (Part Studios, Assemblies, etc.) in a workspace

Query the true outward-facing coordinate system for a face on an assembly instance. Returns the guaranteed outward normal (Z-axis), tangent axes (X/Y), and origin. More reliable than body details normals. Use this to verify face orientations before creating mates.

Get all features from a Part Studio

Mass properties (volume, mass, center of mass, principal inertia, bbox) for every body in a Part Studio, or a specific part if partId is given. Values come as [min, mean, max] uncertainty triples. Mass is zero unless a material is assigned; volume and centroid are always meaningful.

Get all parts from a Part Studio element

Get all variables from a Variable Studio (or Part Studio). Modern Onshape stores variables in dedicated Variable Studio elements; pass a Variable Studio elementId here to read its variables. Pass a Part Studio elementId to read the (usually empty) variables owned by that PS.

Return a compact, structured view of a BTMSketch-151's entities and constraints. Use before calling edit_sketch to learn the entity ids + sub-points (<id>.start / .end / .center) that constraint refs target. Cheaper and easier to scan than get_features; includes a human-readable text block plus machine-readable lists.

Locate the sketch by sketchFeatureId (preferred), by sketchName, or — if the element has exactly one sketch — omit both.

List every image currently in the in-process render cache with its metadata (view, source part studio, dimensions, crop lineage). Use to recover an image_id you need to crop or re-render, or to audit what you've looked at so far.

List documents in your Onshape account with optional filtering and sorting

Enumerate every face, edge, and vertex of every body in a Part Studio with deterministic IDs you can drop into subsequent feature payloads. Each entity has a human-readable 'description' like 'plane / outward +Z / origin (0.0,0.0,15.0) mm' or 'cylinder / radius 5.00 mm / origin ... mm' so you can pick the right one by reading rather than geometric reasoning. Call this after ANY feature that creates or modifies bodies, before sketching on a face, filleting an edge, mating to a face, or otherwise referencing picked geometry. IDs (JHK, JNC, JHl, ...) are the 'deterministicIds' you put in a BTMIndividualQuery-138 query entry.

FILTERS (all optional; prune BEFORE serialization so responses stay small on complex parts): geometry_type (PLANE/CYLINDER/LINE/ARC/...), outward_axis (+X/-X/+Y/-Y/+Z/-Z), at_z_mm + at_z_tol_mm (faces pick by origin Z; edges pick by midpoint Z), radius_range_mm ([min,max] mm; cylinders/arcs/circles), length_range_mm ([min,max] mm; edges only). The response echoes filters and reports both original_counts and filtered_counts per body so you can see how much pruning happened.

List every sketch in a Part Studio with featureId, name, status, and entity / constraint counts. Use to pick the right sketch before drilling in with inspect_sketch.

Read a PNG from disk (e.g. the brief's reference drawing) into the image cache so you can crop_image into it at native resolution. Returns image_id + dimensions. Without this, the reference image lives only in the prompt as inline base64 — no way to zoom into a dimension callout. Use this ONCE per brief on the reference path you were given, then crop_image to read small text.

Numeric distance + angle between two entities (faces/edges/vertices) picked by deterministic ID. Use this instead of eyeballing a render when you need precise geometric facts: 'are these faces parallel?', 'what's the distance between the top face and the hole floor?', 'is this edge perpendicular to that plane?'. Input: two IDs from list_entities. Returns point_distance_m, angle_deg, parallel/perpendicular flags, and when applicable a projected plane-to-plane or point-to-plane distance. Always prefer this over visual inspection for precision-sensitive decisions.

Render shaded views of an Assembly. Same semantics as render_part_studio_views.

Render one or more shaded views of a Part Studio and return the PNGs so Claude can actually see the 3D result. Use this after every feature that creates or modifies visible geometry. The returned image_ids can be passed to crop_image to zoom into suspicious regions. Claude Opus 4.7 spatial reasoning is weak — always render the view you need rather than mentally rotating. Default views: iso, top, front, right.

Render a BTMSketch-151 to a 2D PNG (sketch-local mm, looking down the sketch normal). Onshape's /shadedviews shows solids but not sketch geometry — this plots each line / arc / circle / point directly and overlays constraint badges: FIX = red square, LENGTH / DIAMETER / RADIUS / DISTANCE = green label, HORIZONTAL / VERTICAL = H/V tag.

Complements inspect_sketch (structured text). Same entity ids are labeled on the drawing. Returns an image_id that crop_image can zoom into.

Search for documents by name or description

Set an instance to an ABSOLUTE position (bare numbers = mm; strings like "20 mm" / "0.5 in" for explicit units). Unlike transform_instance this sets absolute coords and resets rotation to identity. Note: fails on fixed/grounded instances (API returns 400).

Write or update a variable in a Variable Studio. elementId MUST be a Variable Studio element id (from create_variable_studio); writing to a Part Studio /variables endpoint 404s on modern docs. Other Part Studios in the same workspace can reference this variable as #name in any expression (sketch dimensions, extrude depths, etc.).

Apply a RELATIVE transform to an assembly instance. Translations: bare numbers = mm; strings like "20 mm" / "0.5 in" for explicit units. Rotations: degrees. Note: fails on fixed/grounded instances — use get_assembly_positions to check the 'fixed' flag first.

Modify parameters on an existing Part Studio feature (for iteration: 'change the extrude depth from 10mm to 15mm', 'swap the fillet radius to 2mm', 'flip oppositeDirection'). Updates are keyed by the feature's parameterId (e.g. 'depth', 'radius', 'operationType', 'oppositeDirection'). For quantity params, set expression ("15 mm", "0.5 in", "90 deg"). For boolean/enum params, set value. Returns the standard {ok, status, feature_id, ...} contract so you can tell if the patched feature still regenerates.

Paradigm escape hatch. Author an arbitrary FeatureScript custom feature (threads, helices, shells, drafts, sweeps along a path, patterns along a curve -- anything our primitives can't express) and apply it to a Part Studio in one call. The system creates a Feature Studio element in the same workspace, uploads your source, confirms it compiles, fetches the sourceMicroversionId, and instantiates a BTMFeature-134 with the correct e{fs_eid}::m{microversion} namespace.

featureScript is a COMPLETE FS source file. Prelude: FeatureScript 2909;\nimport(path:"onshape/std/geometry.fs",version:"2909.0");. Export exactly one defineFeature(...) whose binding name matches the featureType arg. Minimal worked example (offset plane):

FeatureScript 2909;
import(path:"onshape/std/geometry.fs",version:"2909.0");
annotation { "Feature Type Name" : "My feat" }
export const myFeat = defineFeature(function(context is Context, id is Id, definition is map)
    precondition { annotation{"Name":"Offset"} isLength(definition.offset, LENGTH_BOUNDS); }
    {
        opPlane(context, id + "p", {"plane": plane(vector(0,0,definition.offset), vector(0,0,1), vector(1,0,0))});
    });

parameters is a list of {id, type, value} dicts to bind precondition variables. type ∈ {quantity, string, boolean, real}. For quantity, value is a unit-tagged string like "25 mm" or "0.5 in".