doc-control

Overview Schema Source Related Servers Discussions Admin

live_save

Save the document open in Word or LibreOffice to its file from inside the app after live edits, keeping changes by overwriting the disk version; no backup is taken.

Instructions

Save the document open in Word or LibreOffice (attached with live.open) to its file, from inside the app. Call it after live edits (doc.batch with engine live) to keep them; live.close with save: true saves and closes in one call. Overwrites the file on disk with the app's version; no backup is taken.

Input Schema

Name	Required	Description	Default
`doc`	Yes	Path to the document, or the file name of one open in a live app.
`engine`	No	Always the live engine; may be left out.

Output Schema

Name	Required	Description
`ok`	Yes	Always true on success.
`op`	Yes	The operation that ran.
`api`	Yes	API version (1.0).
`doc`	No	The document read or written: path, sha256 and paragraph count.
`next`	Yes	Cursor for the next page (pass as cursor), or null.
`result`	Yes	What the operation returns.
`warnings`	Yes	Things to know about the result.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.7.2Oct 15, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "api": {
+      "description": "API version (1.0).",
+      "type": "string"
+    },
+    "doc": {
+      "description": "The document read or written: path, sha256 and paragraph count.",
+      "properties": {
+        "characters": {
+          "description": "text.normalize of a text string: its length.",
+          "type": "integer"
+        },
+        "paragraphs": {
+          "description": "Body paragraphs.",
+          "type": "integer"
+        },
+        "path": {
+          "description": "Path of the document.",
+          "type": "string"
+        },
+        "sha256": {
+          "description": "sha256 of the file (pass as expect.sha256 to a write).",
+          "type": "string"
+        },
+        "source": {
+          "description": "A .txt/.md/.odt source's format, encoding and split mode; \"text\" for a text string (text.normalize).",
+          "type": [
+            "object",
+            "string"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "next": {
+      "description": "Cursor for the next page (pass as cursor), or null.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "ok": {
+      "description": "Always true on success.",
+      "type": "boolean"
+    },
+    "op": {
+      "description": "The operation that ran.",
+      "type": "string"
+    },
+    "result": {
+      "description": "What the operation returns.",
+      "properties": {
+        "saved": {
+          "description": "Always true: the app saved the file.",
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "saved"
+      ],
+      "type": "object"
+    },
+    "warnings": {
+      "description": "Things to know about the result.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "api",
+    "ok",
+    "op",
+    "result",
+    "warnings",
+    "next"
+  ],
+  "type": "object"
+}

First observedv0.1.0Oct 15, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations only declare readOnlyHint=false, destructiveHint=false, openWorldHint=false. The description adds non-obvious behavior: it overwrites the on-disk file with the app's version and takes no backup, plus the prerequisite that the doc must already be attached with live.open. That is meaningful disclosure beyond the structured fields, and it does not contradict destructiveHint=false since a normal save is not a destructive operation.

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?

Three tight sentences: action first, then the sequencing/alternative, then the risk disclosure. Every sentence carries distinct load with no redundancy or 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?

Output schema exists, so return values need not be explained. The description covers the prerequisite (live attachment), the persistence workflow, the close-and-save alternative, and the overwrite/no-backup consequence - everything needed to invoke it correctly.

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% and both parameters are documented in the schema (doc path or live-app file name; engine enum with default). The description adds no per-parameter syntax or format detail beyond noting the live.open attachment context, so the baseline 3 applies.

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 (save) and resource (the document open in Word/LibreOffice, attached via live.open) and scopes it to acting inside the app. An agent can immediately distinguish this from live_open, live_close, and doc_batch 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 Guidelines5/5

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

Explicit sequencing guidance: call after live edits via doc.batch with engine live to persist them, and the alternative live.close with save: true is named for the save-and-close case. This is exactly the when-to-use-vs-alternative routing an agent needs.

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

Deploy Server