Skip to main content
Glama
onshape-jamcp

onshape-jamcp

Get assembly

get_assembly
Read-only

Reads an assembly's instances, placements, and mates to verify structure before edits and confirm parts moved after applying mates. Read-only single request; use for instance IDs and mate validation.

Instructions

Read an Assembly tab: what it contains, where everything sits and what is mated. Call it before changing an assembly (to get the instance IDs add_mate needs after insert_instance) and after add_mate to confirm a part really moved - an accepted mate is not proof. Read-only, one request, nothing is changed. It returns instances (instance_id, name and suppressed; for an inserted single part also type 'Part' and the part_id and element_id of its source - an instance of a whole Part Studio carries only its id and name, so those fields are then absent), placements (the instance path, fixed, and position: the translation of its origin in the configured length unit - rotation is not reported) and mates (feature_id, name, type, suppressed). An empty assembly gives empty lists. For the parts of a Part Studio use list_parts; for the tabs of a document use get_document; for volume or size use get_part_properties on the Part Studio.

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>"
    },
    "name": "get_assembly"
  }
}

Input Schema

NameRequiredDescriptionDefault
element_idYesElement ID of the ASSEMBLY tab (from get_document, type ASSEMBLY). For a Part Studio use list_parts instead.
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.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / element_id / description
      Previous value: -"Element (tab) ID: the string after /e/ in the Onshape URL. Get it from get_document."New value: +"Element ID of the ASSEMBLY tab (from get_document, type ASSEMBLY). For a Part Studio use list_parts instead."
  2. First observedv1.1.1

TDQS

A4.6/5.0
Behavior5/5

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

Annotations declare readOnlyHint=true and openWorldHint=true, and the description reinforces this with "Read-only, one request, nothing is changed." Beyond that it discloses the actual payload shape (instances, placements, mates), the caveat that rotation is not reported, the case where source fields are absent for whole-Part-Studio instances, the empty-assembly behavior, and the important warning that an accepted mate is not proof a part moved.

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?

Front-loaded with purpose, then usage, then behavior, then return shape, then sibling routing – a logical order with no filler. The returns block is dense with parenthetical detail and slightly long, but nearly every clause carries information an agent would otherwise have to discover by calling the tool.

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 three-parameter read tool with annotations and an output schema, the description covers purpose, invocation timing, mutation context, return-field semantics and edge cases (empty assembly, missing part_id/element_id). Nothing an agent needs to select or call this tool is missing.

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 document_id, element_id and workspace_id are already fully documented in the schema, including the ASSEMBLY-tab requirement and the default workspace behavior. The description adds no parameter-level detail (e.g. how to obtain the element ID); baseline 3 applies when the schema does the heavy lifting.

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: "Read an Assembly tab: what it contains, where everything sits and what is mated." It explicitly names the resources it is not for (Part Studio parts -> list_parts, document tabs -> get_document, size/volume -> get_part_properties), so an agent can distinguish it from siblings without opening a schema.

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?

Gives concrete when-to-use conditions tied to workflow: call before changing an assembly to obtain instance IDs needed by add_mate after insert_instance, and call after add_mate to verify a part actually moved. It also states the exclusions by routing Part Studio, document-tab and size queries to other tools.

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