Skip to main content
Glama
Sign In
doc-control

doc-control

by nuncaeslupus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

history_orphans

Read-onlyIdempotent

List orphaned undo stores after document moves, renames, or deletions; then adopt, read, or purge retained history.

Instructions

List undo stores whose document is gone (moved, renamed or deleted): the app-data stores, plus dir/.doc-control when dir is given, each with its folder, last document path, entry count and last time; unknown holds stores that name no document. Their history is never deleted automatically. Use history.adopt to re-attach one to a moved document, history.list or history.restore with store to read from it, history.purge with store to delete it. Read-only.

Input Schema

NameRequiredDescriptionDefault
dirNoAlso scan this folder.

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": {
+        "orphans": {
+          "description": "Stores whose document is gone.",
+          "items": {
+            "description": "A store.",
+            "properties": {
+              "doc": {
+                "description": "Path of the document it last recorded.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "doc_id": {
+                "description": "Id of that document's history, null when unknown.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "entries": {
+                "description": "Log entries.",
+                "type": "integer"
+              },
+              "last_time": {
+                "description": "Time of the last entry (ISO 8601).",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "store": {
+                "description": "Store folder.",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "total": {
+          "description": "Orphans found.",
+          "type": "integer"
+        },
+        "unknown": {
+          "description": "Stores that name no document.",
+          "items": {
+            "description": "A store.",
+            "properties": {
+              "doc": {
+                "description": "Path of the document it last recorded.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "doc_id": {
+                "description": "Id of that document's history, null when unknown.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "entries": {
+                "description": "Log entries.",
+                "type": "integer"
+              },
+              "last_time": {
+                "description": "Time of the last entry (ISO 8601).",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "store": {
+                "description": "Store folder.",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "orphans",
+        "unknown",
+        "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. 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, so the safety profile is given. The description still adds real behavioral context beyond them: orphaned history 'is never deleted automatically', and it names the fields each entry carries. It does not add auth or rate-limit caveats, so not a 5.

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-loads the core definition, then the scope extension, then the routing sentence, ending with 'Read-only.' No sentence is filler, though the first sentence is heavily packed with clause-nested enumerations that take a second read to parse.

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 values need no prose, and the description uses the space for what the schema cannot carry: orphan classification, the `dir`/`unknown` edge cases, non-deletion behavior, and next-step siblings. Nothing an agent needs to call this correctly is missing.

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% and the schema only says 'Also scan this folder'. The description adds meaning the schema lacks: when `dir` is supplied, the scan covers `dir`/.doc-control in addition to the app-data stores. That is genuine semantic enrichment beyond the one-param baseline of 3.

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 ('List undo stores whose document is gone') and immediately enumerates what counts as an orphan (moved, renamed, deleted) plus the special `dir`/.doc-control case and the `unknown` bucket. This cleanly separates it from siblings like history_list, history_search and history_purge.

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 routes the agent: history.adopt to re-attach to a moved document, history.list/history.restore with `store` to read from it, history.purge with `store` to delete it. It also scopes when the optional `dir` matters, so both when-to-use and what-to-use-next are covered.

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