Skip to main content
Glama
onshape-jamcp

onshape-jamcp

Add a mate

add_mate

Join two part instances in an Onshape Assembly with a mate by selecting a spot on each and a mate type, then return the real status and resulting positions.

Instructions

Join two part instances of an Assembly with a mate. Pick a spot on each: for a nut on a bolt use the bolt's circular end edge (at 'center') and a face of the nut (at 'centroid'), with mate_type 'cylindrical' (free to turn and slide) or 'fastened'. The first instance stays where it is if it is grounded; the second moves to satisfy the mate. Returns the real status and both instances' resulting positions. Only when the user asks for an assembly. Note: the centroid of a threaded face can sit ~0.2 mm off the thread's axis.

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>",
      "assembly_id": "<assembly_id>",
      "mate_type": "<mate_type>",
      "first": "<first>",
      "second": "<second>"
    },
    "name": "add_mate"
  }
}

Input Schema

NameRequiredDescriptionDefault
flipNoFlip the primary axis (the second part faces the other way).
nameNoDefaults to e.g. 'Cylindrical 1'.
firstYes
offsetNo[x, y, z] offset between the connectors, in the configured length unit (strings may carry units).
secondYes
mate_typeYesfastened: no motion; revolute: rotates about the axis; cylindrical: rotates and slides along it (a nut on a bolt); slider, planar, pin_slot, ball, parallel as in Onshape.
assembly_idYesElement ID of the Assembly tab (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.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.1.1

TDQS

A4.4/5.0
Behavior4/5

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

Goes well beyond the annotations by disclosing the physical side effect (the second instance moves to satisfy the mate, the first stays if grounded), what the return contains (real status plus both resulting positions), and a precision caveat about threaded-face centroids sitting ~0.2 mm off axis. It doesn't say whether existing mates are invalidated or how failures surface, keeping it at 4.

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?

Roughly five tight sentences with the core action front-loaded, followed by the example, the motion rule, and the caveat. The example is placed before the general rule, which is slightly less efficient, but no sentence is filler.

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, non-idempotent assembly mutation with an output schema already covering return shape, the description supplies everything an agent needs: mating semantics, the grounding rule, mate_type options, and a tolerance caveat. Nothing material is missing.

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 78%, so the baseline is 3, and the description earns above that by translating enum choices into intent: 'at center' for a circular edge, 'at centroid' for a face, and 'cylindrical' as free to turn and slide. It adds real meaning rather than restating field titles.

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?

'Join two part instances of an Assembly with a mate' names a specific verb (join) and resource (part instances / mate), which is clearly distinct from siblings like insert_instance or get_assembly. An agent can identify the operation without opening the schema.

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

Usage Guidelines4/5

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

Gives concrete when-to-use guidance with a worked example ('for a nut on a bolt use the bolt's circular end edge at center and a face of the nut at centroid') plus a gate ('Only when the user asks for an assembly'). It doesn't name a specific sibling alternative or state when not to mate, so it stops short of a full 5.

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