doc-control

Overview Schema Source Related Servers Discussions Admin

live_select

Select a paragraph or position the cursor at its start in an open Word or LibreOffice document to highlight a passage for discussion.

Instructions

Show the user a place in Word or LibreOffice: select a paragraph, or with mode cursor only put the cursor at its start, by address (at, p142#a7b2a7b2) or by a find_phrase from para.locate (matched loosely per match_level). paragraphs_after moves on that many paragraphs. Use it to point at a passage you are discussing; live.places offers several as buttons. Changes only the selection; needs live.open. STALE_ADDRESS when at no longer matches, ANCHOR_NOT_FOUND or ANCHOR_AMBIGUOUS for a phrase.

Input Schema

Name	Required	Description
`at`	No	Paragraph address, e.g. `p142#a7b2a7b2`.
`doc`	Yes	Path to the document, or the file name of one open in a live app.
`mode`	No	`select` (default) selects the paragraph; `cursor` only puts the cursor at its start, so typing or Delete cannot replace it.
`front`	No	Bring the app's window to the front (default true); the reply's `front` says whether it came.
`engine`	No	Always the live engine; may be left out.
`find_phrase`	No	A phrase that occurs once in the document (`\r` for a paragraph mark), as `para.locate` gives it.
`match_level`	No	How loosely `find_phrase` matches. `default` (the default) ignores case, accents and punctuation; `loose` symbols too. Either tries the levels from verbatim on and takes the first that matches, so one verbatim paragraph beats looser ones. `exact` is `para.locate`'s rule: case ignored, nothing else, no retry. Two meanings of exact: the request's `exact` allows a case difference, the reply's does not. The reply's `match_level` (`exact` character for character, `case`, `default`, `loose`) names the level that matched, with `matched_text` when it is not `exact`.
`paragraphs_after`	No	Select the paragraph this many after the one named.
`find_phrase_across`	No	`para.locate`'s `find_phrase_across`, for a phrase spanning a mark.

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": {
+        "at": {
+          "description": "Paragraph address, p<n>#<fingerprint> (story-prefixed in notes/headers).",
+          "type": "string"
+        },
+        "front": {
+          "description": "With front: whether the window was brought to the front.",
+          "type": "boolean"
+        },
+        "match_level": {
+          "description": "By find_phrase: the level it matched at.",
+          "type": "string"
+        },
+        "matched_text": {
+          "description": "By find_phrase: the text matched, when not exact.",
+          "type": "string"
+        },
+        "text": {
+          "description": "Text of the paragraph selected.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "text",
+        "at"
+      ],
+      "type": "object"
+    },
+    "warnings": {
+      "description": "Things to know about the result.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "api",
+    "ok",
+    "op",
+    "result",
+    "warnings",
+    "next"
+  ],
+  "type": "object"
+}

Changed3 schema fields changedv0.1.3Oct 15, 2026

changedInput schema / properties / find_phrase / description

Previous value: -"A phrase that occurs once in the document (`\\r` for a paragraph mark), as `locate` gives it."New value: +"A phrase that occurs once in the document (`\\r` for a paragraph mark), as `para.locate` gives it."

changedInput schema / properties / find_phrase_across / description

Previous value: -"`locate`'s `find_phrase_across`, for a phrase spanning a mark."New value: +"`para.locate`'s `find_phrase_across`, for a phrase spanning a mark."

changedInput schema / properties / match_level / description

Previous value: -"How loosely `find_phrase` matches. `default` (the default) ignores case, accents and punctuation; `loose` symbols too. Either tries the levels from verbatim on and takes the first that matches, so one verbatim paragraph beats looser ones. `exact` is `locate`'s rule: case ignored, nothing else, no retry. Two meanings of exact: the request's `exact` allows a case difference, the reply's does not. The reply's `match_level` (`exact` character for character, `case`, `default`, `loose`) names the level that matched, with `matched_text` when it is not `exact`."New value: +"How loosely `find_phrase` matches. `default` (the default) ignores case, accents and punctuation; `loose` symbols too. Either tries the levels from verbatim on and takes the first that matches, so one verbatim paragraph beats looser ones. `exact` is `para.locate`'s rule: case ignored, nothing else, no retry. Two meanings of exact: the request's `exact` allows a case difference, the reply's does not. The reply's `match_level` (`exact` character for character, `case`, `default`, `loose`) names the level that matched, with `matched_text` when it is not `exact`."

First observedv0.1.0Oct 15, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Annotations only say readOnly=false / destructive=false; the description goes further by disclosing the exact side-effect scope ('Changes only the selection'), the live.open dependency, and the failure modes (STALE_ADDRESS, ANCHOR_NOT_FOUND, ANCHOR_AMBIGUOUS). That is material behavior an agent cannot infer from the structured fields.

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 action and keeps everything in one dense but purposeful block with no filler sentences. It is slightly run-on with stacked parentheticals, which costs a point on readability.

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?

With an output schema present, return values need no explanation, and the description covers purpose, prerequisites, alternatives and error codes for a 9-parameter tool. Nothing an agent needs in order 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 coverage is 100%, so the schema already documents every parameter, including the match_level nuances. The description restates the at/find_phrase/paragraphs_after mechanics without adding syntax or format beyond the schema, 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 and resource ('Show the user a place in Word or LibreOffice: select a paragraph, or ... put the cursor at its start') and gives concrete addressing forms (at `p142#a7b2a7b2`, find_phrase). It distinguishes itself from the live.* family by pointing to live.places for the button variant.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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

Gives an explicit use case ('Use it to point at a passage you are discussing'), names a related sibling (live.places offers several as buttons) and a prerequisite (needs live.open). It stops short of stating when NOT to use it, so it is clear context rather than a full routing rule.

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

Deploy Server