Skip to main content
Glama
Sign In
doc-control

doc-control

by nuncaeslupus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

history_list

Read-onlyIdempotent

List a document's undo log newest first to find operation IDs for undo or restore and see deleted paragraphs that can be recovered. Read-only; filter by kind and page with cursor.

Instructions

List the document's undo log, newest first: each write's op_id, kind, time, author, the operations it ran, whether it was undone, and the deleted paragraphs history.restore can bring back (change numbers). Filter with kind (batch, restore, undo, open, purge, adopt); store reads an orphaned store instead. Use it to find the op_id for history.undo or history.restore; history.search finds a quote in the log. Read-only; paged with limit (default 20) and cursor (the reply's next).

Input Schema

NameRequiredDescriptionDefault
docNoPath to the .docx.
kindNoOnly entries of this kind (batch: every logged edit).
limitNoMost entries per page (default 20).
storeNoA store folder (see history.orphans) to read instead of the document's own.
cursorNoThe `next` of the previous response.

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. Changed3 schema fields changedv0.7.2
    • addedInput schema / properties / kind / description
      Added value: +"Only entries of this kind (batch: every logged edit)."
    • addedInput schema / properties / limit / description
      Added value: +"Most entries per page (default 20)."
    • 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": {
+        "entries": {
+          "description": "This page of log entries, newest first.",
+          "items": {
+            "description": "A logged write.",
+            "properties": {
+              "adopted_from": {
+                "description": "adopt: the store and document it came from.",
+                "type": "object"
+              },
+              "author": {
+                "description": "Revision author.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "backup": {
+                "description": "Backup taken before it.",
+                "type": "string"
+              },
+              "deleted": {
+                "description": "Paragraphs it deleted that history.restore can bring back (first 5).",
+                "items": {
+                  "description": "A deleted paragraph.",
+                  "properties": {
+                    "change": {
+                      "description": "Change number.",
+                      "type": "integer"
+                    },
+                    "text": {
+                      "description": "Text (clipped).",
+                      "type": "string"
+                    }
+                  },
+                  "type": "object"
+                },
+                "type": "array"
+              },
+              "engine": {
+                "description": "live for a live-engine edit.",
+                "type": "string"
+              },
+              "kind": {
+                "description": "batch, restore, style, undo, open, purge or adopt.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "op_id": {
+                "description": "Op id (history.undo / history.restore).",
+                "type": "string"
+              },
+              "ops": {
+                "description": "Operation kinds in the request.",
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "paragraphs": {
+                "description": "Paragraphs it changed.",
+                "type": "integer"
+              },
+              "removed": {
+                "description": "purge: entries removed.",
+                "type": [
+                  "integer",
+                  "null"
+                ]
+              },
+              "restores": {
+                "description": "Op id it restored from.",
+                "type": "string"
+              },
+              "scope": {
+                "description": "purge: what was removed.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "sha256_after": {
+                "description": "File hash after it.",
+                "type": "string"
+              },
+              "tag": {
+                "description": "Author tag.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "time": {
+                "description": "When (ISO 8601).",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "tracked": {
+                "description": "False for a plain write.",
+                "type": "boolean"
+              },
+              "undoes": {
+                "description": "Op id it undid.",
+                "type": "string"
+              },
+              "undone": {
+                "description": "Whether it was taken back.",
+                "type": "boolean"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "total": {
+          "description": "Entries in the log (after the kind filter).",
+          "type": "integer"
+        },
+        "unreadable_lines": {
+          "description": "Log lines that could not be read.",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "entries",
+        "total"
+      ],
+      "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. Changed1 schema field changedv0.1.3
    • changedInput schema / properties / kind / enum
      Previous value: -[
-  "batch",
-  "restore",
-  "undo",
-  "open",
-  "purge"
-]New value: +[
+  "batch",
+  "restore",
+  "undo",
+  "open",
+  "purge",
+  "adopt"
+]
  3. First observedv0.1.0

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already cover the read-only, idempotent, closed-world profile, but the description adds real behavior: newest-first ordering, pagination with default limit 20 and cursor taken from the reply's `next`, and the orphaned-store read path. It slightly over-specifies return fields that the output schema already defines, and repeats 'read-only' from the annotations.

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?

Dense but front-loaded, leading with the verb, resource, and ordering before filters and alternatives. It wastes a little space repeating 'read-only' (already in annotations) and listing return fields the output schema covers.

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 read-only paged list tool with an output schema, the description covers scope, ordering, filtering, pagination, the alternative read mode, and sibling routing. Nothing an agent needs to invoke it correctly is missing.

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%, so the schema already documents all five parameters including the `kind` enum and the cursor/limit semantics. The description mostly restates these (enum values, default 20, cursor = reply's `next`), adding only a marginal gloss on `store` reading an orphaned store, so baseline 3 is appropriate.

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 ('List the document's undo log') plus ordering ('newest first') and enumerates what each entry contains. This distinguishes it cleanly from history_search, history_undo, and history_restore, which are named as different tools.

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?

Explicitly says what it is for ('Use it to find the op_id for history.undo or history.restore') and names the contrasting alternative ('history.search finds a quote in the log'). It also explains the `kind` filter and the `store` orphaned-store case, giving the agent clear routing conditions.

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