Skip to main content
Glama
Sign In
onshape-mcp

onshape-mcp

by gpambrozio
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Insert an instance

onshape_insert_instance

Insert a part, a whole Part Studio or another assembly into an assembly. Insert from a version when pulling from a different document.

Instructions

Insert a part, a whole Part Studio or another assembly into an assembly. Insert from a version when pulling from a different document.

Input Schema

NameRequiredDescriptionDefault
wsYesWorkspace id — the <ws> segment of the document URL.
docYesDocument id — the <doc> in cad.onshape.com/documents/<doc>/w/<ws>/e/<elem>.
elemYesElement id (tab) — the <elem> segment of the document URL.
partNoPart id, to insert a single part.
fixedNoFix the new instance in place, to ground the assembly. Onshape has no public call to fix or unfix an instance afterwards; to change it, insert again and delete the old instance.
src_docNoSource document id (defaults to the target document).
src_elemYesElement id of the source Part Studio or assembly.
is_assemblyNoThe source element is an assembly.
src_versionNoSource version id, required when inserting across documents.
whole_studioNoInsert every part of the source Part Studio.
configurationNoEncoded configuration for the inserted element.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.3.0
    • addedInput schema / properties / fixed
      Added value: +{
+  "description": "Fix the new instance in place, to ground the assembly. Onshape has no public call to fix or unfix an instance afterwards; to change it, insert again and delete the old instance.",
+  "type": "boolean"
+}
  2. First observedv0.1.0

TDQS

B3.4/5.0
Behavior2/5

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

Annotations carry only a title, so the description bears the full burden. It confirms this is a mutating insert, but does not mention that the target element must be an assembly, what happens on id collision, whether the inserted instance is grounded (that detail lives only in the `fixed` schema text), or that undoing requires onshape_delete_instance.

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?

Two tight sentences with the primary capability front-loaded and the cross-document caveat second. No filler, though the second sentence is somewhat redundant with the src_version schema text.

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 an 11-parameter tool with no output schema and only a title annotation, the description adequately frames the operation's three modes and the cross-document requirement, while the unusually detailed schema (especially the `fixed` note about no public fix/unfix call) covers the finer mechanics.

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

Parameters3/5

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

Schema description coverage is 100%, so the definitions already explain doc/ws/elem, part, whole_studio, is_assembly, src_version and fixed. The description adds only the cross-document version rule, which the schema already states for src_version, so baseline 3 applies.

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

Purpose4/5

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

The description gives a concrete verb and resource — insert a part, a whole Part Studio, or another assembly into an assembly — so the operation and its three input shapes are unambiguous. It does not explicitly contrast with sibling tools like onshape_delete_instance or onshape_transform_instance, which is the only thing separating it from a 5.

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

Usage Guidelines3/5

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

Usage is implied by the scenario it describes (building up an assembly), and it adds one targeted rule: use a version when pulling from a different document. It never states when not to use it or names alternatives such as delete_instance or assembly_mate for repositioning/constraining the inserted instance.

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