Skip to main content
Glama
Sign In
doc-control

doc-control

by nuncaeslupus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

live_status

Read-onlyIdempotent

Check which Word or LibreOffice apps are running, what documents they have open, which app holds a file, and whether it has unsaved changes. Use before live editing or choosing file edits.

Instructions

Check the live apps: which of Word and LibreOffice are installed and reachable, and which documents they have open; with doc, which app holds it, whether that app is driven by this server or only a lock file says so, its full path and whether it has unsaved changes. Call it before live.open, or to decide between live editing and the file engine (a file open in Word should be edited live or closed first). Read-only; never fails for a missing app.

Input Schema

NameRequiredDescriptionDefault
docNoPath to the document, or the file name of one open in a live app.
engineNoAlways the live engine; may be left out.

Output Schema

NameRequiredDescriptionDefault
okYesAlways true on success.
opYesThe operation that ran.
apiYesAPI version (1.0).
docNoThe document read or written: path, sha256 and paragraph count.
nextYesCursor for the next page (pass as cursor), or null.
resultYesWhat the operation returns.
warningsYesThings to know about the result.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.7.2
    • 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": {
+        "apps": {
+          "description": "Every live app, running or not.",
+          "items": {
+            "description": "A live app.",
+            "properties": {
+              "app": {
+                "description": "word, libreoffice (or a test adapter).",
+                "type": "string"
+              },
+              "available": {
+                "description": "Installed on this machine.",
+                "type": "boolean"
+              },
+              "listening": {
+                "description": "LibreOffice: its UNO listener is up.",
+                "type": "boolean"
+              },
+              "reachable": {
+                "description": "Can be driven now.",
+                "type": "boolean"
+              },
+              "reason": {
+                "description": "Why it is not available or reachable.",
+                "type": "string"
+              },
+              "version": {
+                "description": "App version, when known.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "dirty": {
+          "description": "With doc: it has unsaved changes.",
+          "type": "boolean"
+        },
+        "documents": {
+          "description": "Without doc: the documents the apps have open.",
+          "items": {
+            "description": "An open document.",
+            "properties": {
+              "app": {
+                "description": "App.",
+                "type": "string"
+              },
+              "name": {
+                "description": "File name.",
+                "type": "string"
+              },
+              "path": {
+                "description": "Full path.",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "open_in": {
+          "description": "With doc: the app holding it {app, controlled, stale}; controlled false means only a lock file says so. Null when no app has it open.",
+          "type": [
+            "object",
+            "null"
+          ]
+        },
+        "path": {
+          "description": "With doc: its full path.",
+          "type": "string"
+        },
+        "update": {
+          "description": "Opt-in update notice (DOC_CONTROL_UPDATE_CHECK): the newest release.",
+          "properties": {
+            "checked_at": {
+              "description": "When it was checked (UTC).",
+              "type": "string"
+            },
+            "current": {
+              "description": "This version.",
+              "type": "string"
+            },
+            "error": {
+              "description": "Why the check failed.",
+              "type": "string"
+            },
+            "latest": {
+              "description": "Newest release.",
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "mcpb_url": {
+              "description": "Download of the newest .mcpb bundle.",
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          },
+          "type": "object"
+        }
+      },
+      "required": [
+        "apps",
+        "open_in",
+        "dirty"
+      ],
+      "type": "object"
+    },
+    "warnings": {
+      "description": "Things to know about the result.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "api",
+    "ok",
+    "op",
+    "result",
+    "warnings",
+    "next"
+  ],
+  "type": "object"
+}
  2. First observedv0.1.0

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint and closed-world scope, so the safety profile is covered. The description nonetheless adds behavior beyond the structured fields: it will not fail when an app is missing, and it distinguishes a server-driven app from one inferred only from a lock file, which materially affects how the caller should interpret the result.

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?

Purpose is front-loaded in the first sentence and the usage rule follows immediately; nothing is padding. The first sentence is somewhat clause-heavy and could be split for faster scanning, which keeps this short of 5.

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?

An output schema exists, so return-value documentation is not required, yet the description still describes the key result fields (owner app, drive mode, path, dirty state). Combined with annotations covering read-only/idempotency and the explicit decision guidance, an agent has everything needed to call and interpret this tool.

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 baseline would be 3, but the description adds meaning the schema does not carry: supplying `doc` widens the report to that document's owning app, its path and its unsaved-changes state. The `engine` enum is not explained beyond the schema, which caps this slightly below 5.

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?

The description names a specific verb (check) and resource set (Word/LibreOffice, open documents, lock state, unsaved changes) rather than restating the tool name. The `doc` variant is spelled out in detail: which app holds the document, whether it is server-driven or only lock-file claimed, full path, and dirty state. An agent can distinguish this diagnostic tool from live_open/live_close 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?

It gives explicit call sites: 'Call it before live.open' and 'to decide between live editing and the file engine', plus the concrete decision rule that a file open in Word should be edited live or closed first. This is when-to-use guidance with named alternatives and a tie-breaking condition.

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

Deploy Server

Other Tools