Skip to main content
Glama
kompas-mcp

kompas-mcp

by biryak

Save document

doc_save
Destructive

Saves an open KOMPAS-3D document in place or to a new path, blocks unintended overwrites unless explicitly allowed, and verifies the file after saving.

Instructions

Save a document in place, or Save As to a new path (the handle changes: use the returned one). An existing file is never replaced without overwrite=true. PDM folders and read-only files are refused. The file on disk is verified after saving.

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

Input Schema

NameRequiredDescriptionDefault
docYesDocument handle from doc_list/doc_open, e.g. 'doc:12001:0a1b2c3d'
pathNoSave As target (absolute, inside the allowed roots). Omit to save in place.
overwriteNoAllow replacing an existing file (only after the user explicitly agreed)

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.4.2

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the destructiveHint/readOnlyHint annotations by disclosing consequences the annotations cannot express: the document handle changes after Save As, an existing file is never silently replaced, PDM folders and read-only files are refused, and the on-disk file is verified after writing. These are exactly the preconditions and side effects an agent needs before invoking a destructive tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, no filler, and the mode split plus the handle-change warning are front-loaded where the agent will read them first. Every sentence carries a distinct operational fact.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description largely compensates by telling the agent to use the returned handle and that the file is verified after saving, though it does not describe the shape of the verification result. For a three-parameter destructive write tool this is close to complete.

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 100%, so the baseline is 3, but the description adds semantics the schema does not: that path implies a handle change and that the returned handle must be used thereafter, and it reinforces overwrite as a guard against file replacement. Only the absolute-path/allowed-roots constraint is left to the schema alone.

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+resource ("Save a document") and immediately splits it into the two distinct modes it supports: in-place save and Save As to a new path. An agent can distinguish this from doc_create/doc_close/doc_open without opening any 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?

Clear selection logic between the two modes: omit path to save in place, supply path for Save As, and overwrite=true only when the user explicitly agreed. It does not state when to use this instead of doc_create for a brand-new document, but the in-scope usage conditions are explicit.

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