Skip to main content
Glama
onshape-jamcp

onshape-jamcp

Create document

create_document

Creates a new Onshape document in the user's account and returns its IDs, URL, and existing tabs; private by default.

Instructions

Create a new, empty-looking Onshape document in the user's account and return its document_id, workspace_id, name, url and the tabs it already has (Onshape usually adds a 'Part Studio 1' and an 'Assembly 1': reuse and rename them before adding more with create_element). Private by default. Onshape's FREE plan only allows PUBLIC documents: the call then fails with nothing created and a message to ask the user, because a public document is visible to everyone; retry with public=true only after they agree. Use it only when the user wants a new document; to work in an existing one find it with list_documents. There is no tool to delete a document, so tell the user a scratch document stays in their account until they delete it in Onshape.

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

Input Schema

NameRequiredDescriptionDefault
nameYesDocument name.
publicNoMake the document visible to everyone. Leave false unless the user's plan requires it: Onshape's FREE plan can only create public documents (the call then fails and tells you to retry with public=true - only do that after the user agrees).
descriptionNoOptional description.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.1.1

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), it discloses the critical free-plan failure mode: the call fails with nothing created and must be retried with public=true only after consent, because public documents are globally visible. It also discloses that the new document is private by default, that starter tabs already exist and should be reused/renamed, and that no deletion tool exists so scratch documents persist.

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 the create action and return payload, then safety and alternative guidance, which is the right ordering. It is dense but long, with a nested parenthetical about default tabs and several back-to-back caveats; a small amount could be tightened without losing value.

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 create tool with an output schema, an agent gets everything it needs: what is created, what comes back, privacy default, the plan-dependent failure path with consent gate, how to handle the auto-created tabs, and the absence of a delete tool. Nothing material is left to inference.

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 coverage is 100%, and the schema's own description of `public` already spells out the free-plan/consent rule, so the description largely repeats rather than extends parameter meaning. The one added nuance is procedural — reuse and `rename` the pre-existing 'Part Studio 1'/'Assembly 1' tabs before calling `create_element` — which is about the return value more than the inputs. Baseline 3 is appropriate 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?

States a specific verb and resource ('Create a new, empty-looking Onshape document in the user's account') and immediately names the outputs (document_id, workspace_id, name, url, tabs). It also explicitly distinguishes itself from `list_documents` for working in an existing document, so an agent can route correctly 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 an explicit when-to-use ('only when the user wants a new document'), an explicit alternative for the other case ('to work in an existing one find it with `list_documents`'), and a gated retry condition for public=true requiring user agreement. It even covers the post-creation situation where no delete tool exists.

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