doc-control

Overview Schema Source Related Servers Discussions Admin

recipe_run

Read-onlyIdempotent

Instructions

Run a cleanup recipe (a name from recipe.list, or an inline definition) over the document and return the edits it proposes as a ready doc.batch request (batch, guarded by expect.sha256), repeating until the text is stable. Writes nothing itself: review the proposal, then apply it with doc.batch (dry_run there to preview). RECIPE_INVALID for an unknown or invalid recipe; edits that would touch unsupported content are listed under skipped. engine live reads the document open in the app (text-only recipes) and returns a live batch without expect, plus the text of each paragraph it edits. Refused for .txt/.md/.odt sources, which cannot be written.

Input Schema

Name	Required	Description
`doc`	Yes	Path to the .docx file.
`engine`	No	`live` reads the document open in Word or LibreOffice (see live.open) and returns a live doc.batch.
`recipe`	No	Name from recipe.list.
`dry_run`	No	Accepted for symmetry; recipe.run never writes.
`definition`	No	An inline declarative recipe (same schema as a stored one).

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.

Changed4 schema fields changedv0.10.1Oct 22, 2026

addedInput schema / properties / engine

Added value: +{
+  "description": "`live` reads the document open in Word or LibreOffice (see live.open) and returns a live doc.batch.",
+  "enum": [
+    "file",
+    "live"
+  ]
+}

addedOutput schema / properties / result / properties / batch / properties / engine

Added value: +{
+  "description": "live when the open document was read.",
+  "type": "string"
+}

changedOutput schema / properties / result / properties / batch / properties / expect / description
```
Previous value: -"Guards the batch."New value: +"Guards the batch (file engine only)."
```

addedOutput schema / properties / result / properties / paragraphs

Added value: +{
+  "description": "Live only: the open document's text of each paragraph an edit touches, by address.",
+  "type": "object"
+}

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": {
+        "applied": {
+          "description": "Always false: nothing is written.",
+          "type": "boolean"
+        },
+        "batch": {
+          "description": "The doc.batch request to apply: pass it as is.",
+          "properties": {
+            "doc": {
+              "description": "The document.",
+              "type": "string"
+            },
+            "expect": {
+              "description": "Guards the batch.",
+              "properties": {
+                "sha256": {
+                  "description": "The file hash read.",
+                  "type": "string"
+                }
+              },
+              "type": "object"
+            },
+            "ops": {
+              "description": "The proposed edits.",
+              "items": {
+                "type": "object"
+              },
+              "type": "array"
+            }
+          },
+          "type": "object"
+        },
+        "matches": {
+          "description": "Matches found.",
+          "type": "integer"
+        },
+        "passes": {
+          "description": "Passes run until the text stopped changing.",
+          "type": "integer"
+        },
+        "recipe": {
+          "description": "The recipe's name.",
+          "type": "string"
+        },
+        "skipped": {
+          "description": "Proposed edits left out, with why.",
+          "items": {
+            "description": "A skipped edit.",
+            "properties": {
+              "at": {
+                "description": "Its address.",
+                "type": "string"
+              },
+              "op": {
+                "description": "Its kind.",
+                "type": "string"
+              },
+              "reason": {
+                "description": "Why.",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "stable": {
+          "description": "Whether it reached a fixed point.",
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "recipe",
+        "applied",
+        "matches",
+        "passes",
+        "stable",
+        "skipped",
+        "batch"
+      ],
+      "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.8/5.0

Behavior5/5

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

Consistent with readOnlyHint/idempotentHint and goes well beyond them: it discloses the until-stable iteration loop, that skipped content is reported under `skipped`, the RECIPE_INVALID failure mode, and the engine=live deviation (live batch without `expect`, plus the text of each edited paragraph). For a read-only tool these are the exact behavioral facts an agent needs before deciding to call it.

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-loaded with the action and the return value, and every sentence carries new information (proposal, application path, error code, skipped list, live variant, refusal case). It is dense and heavily parenthetical — several clauses could be split for readability — but nothing is padding.

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 five-parameter tool with a nested `definition` object, an output schema, and a live/file mode switch, the description covers the loop, the output contract, the failure mode, unsupported content, and the mode difference. What remains (the recipe schema itself, the batch payload) is legitimately delegated to the schema and output schema.

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 schema already defines all five parameters, but the description adds real meaning: `recipe` is a name from recipe.list *or* the tool takes an inline `definition`, and `engine: live` changes both the source read and the returned batch shape (no `expect` guard). It does not re-explain `doc` or `dry_run`, which is fine because the schema covers them.

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 ("Run a cleanup recipe ... over the document") plus the exact shape of what it returns ("a ready doc.batch request (`batch`, guarded by expect.sha256)") and the iteration semantics ("repeating until the text is stable"). It explicitly distinguishes itself from the sibling doc_batch by noting it writes nothing itself, and points at recipe.list as the source of names.

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?

Gives an explicit two-step workflow: "review the proposal, then apply it with doc.batch (dry_run there to preview)" — a named alternative with the condition that selects it. It also states exclusions ("Refused for .txt/.md/.odt sources, which cannot be written") and engine-specific selection criteria for live vs file.

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

Deploy Server