Skip to main content
Glama
nuncaeslupus

doc-control

by nuncaeslupus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

para_locate

Read-onlyIdempotent

Locate paragraphs in a .docx file and get their chapter, scene, estimated page, and a unique phrase for Word's Find. Use to tell a writer where a passage is.

Instructions

Say where paragraphs are, in terms a person can follow: for one paragraph, a range (p40#a1b2c3d4:0..p45#e5f6a7b8:0, offsets ignored) or the whole document, each one's chapter, scene, estimated page, shortest unique first … last words phrase, and a phrase Word's Find meets exactly once (for Ctrl+F or live.select). A phrase can be null with a reason (empty, duplicate). structure: false skips chapter detection for speed. Use it to tell a writer where a passage is; page.estimate gives only pages. Read-only; paged at about 8,000 bytes with cursor.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
atNoParagraph address or range (offsets ignored), e.g. p142#a7b2a7b2; default the whole document (empty paragraphs left out).
docYesPath to the .docx.
limitNoMost items to return; a response is also capped at about 8,000 bytes.
cursorNoThe `next` value of the previous response, to continue the list.
profileNoDetection settings for this document.
overridesNoForce or deny a chapter or scene at paragraphs by fingerprint.
structureNofalse: skip chapter, part and scene detection (they come back null), for callers that keep their own structure; faster on a single paragraph. Default true.

Output Schema

TableJSON 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": {
+        "basis": {
+          "description": "Page basis: model or rendered+model.",
+          "type": "string"
+        },
+        "estimated": {
+          "description": "Always true: pages are estimates.",
+          "type": "boolean"
+        },
+        "page_count": {
+          "description": "Estimated page count.",
+          "type": "integer"
+        },
+        "paragraphs": {
+          "description": "This page of paragraphs.",
+          "items": {
+            "description": "Where one paragraph is.",
+            "properties": {
+              "at": {
+                "description": "Paragraph address, p<n>#<fingerprint> (story-prefixed in notes/headers).",
+                "type": "string"
+              },
+              "chapter": {
+                "description": "Its chapter: id, title, number, kind; null if none.",
+                "type": [
+                  "object",
+                  "null"
+                ]
+              },
+              "complete": {
+                "description": "True when the phrase is the whole paragraph.",
+                "type": "boolean"
+              },
+              "context": {
+                "description": "When find_phrase is null: the nearest earlier paragraph with one.",
+                "properties": {
+                  "after": {
+                    "description": "Its find phrase.",
+                    "type": "string"
+                  },
+                  "after_word": {
+                    "description": "As typed in Word's Find box.",
+                    "type": "string"
+                  },
+                  "at": {
+                    "description": "Paragraph address, p<n>#<fingerprint> (story-prefixed in notes/headers).",
+                    "type": "string"
+                  },
+                  "paragraphs_after": {
+                    "description": "Paragraphs from there to this one.",
+                    "type": "integer"
+                  }
+                },
+                "type": "object"
+              },
+              "find_phrase": {
+                "description": "Text Word's Find meets exactly once, or null.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "find_phrase_across": {
+                "description": "previous or next: the phrase spans a paragraph break.",
+                "type": "string"
+              },
+              "find_phrase_reason": {
+                "description": "Why find_phrase is null.",
+                "type": "string"
+              },
+              "find_phrase_unique": {
+                "description": "Whether find_phrase is non-null.",
+                "type": "boolean"
+              },
+              "find_phrase_word": {
+                "description": "find_phrase as typed in Word's Find box (^p, ^t...).",
+                "type": "string"
+              },
+              "find_phrase_words": {
+                "description": "Words in find_phrase.",
+                "type": "integer"
+              },
+              "head_words": {
+                "description": "Words of the phrase's head.",
+                "type": "integer"
+              },
+              "kind": {
+                "description": "Header/footer kind: default, first or even.",
+                "type": "string"
+              },
+              "mark": {
+                "description": "A note paragraph: where its mark is (a row like this one).",
+                "type": [
+                  "object",
+                  "null"
+                ]
+              },
+              "note": {
+                "description": "A note's id, displayed number and the body paragraph holding its mark.",
+                "properties": {
+                  "id": {
+                    "description": "Note id.",
+                    "type": "integer"
+                  },
+                  "number": {
+                    "description": "Displayed number.",
+                    "type": "string"
+                  },
+                  "of": {
+                    "description": "Address of the paragraph holding the mark.",
+                    "type": "string"
+                  }
+                },
+                "type": [
+                  "object",
+                  "null"
+                ]
+              },
+              "page": {
+                "description": "Estimated page.",
+                "type": "integer"
+              },
+              "page_label": {
+                "description": "Page number as printed.",
+                "type": [
+                  "integer",
+                  "string"
+                ]
+              },
+              "part": {
+                "description": "Its part: id, title, number; null if none.",
+                "type": [
+                  "object",
+                  "null"
+                ]
+              },
+              "phrase": {
+                "description": "Shortest unique first … last words phrase, or null.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "reason": {
+                "description": "Why phrase is null (empty, duplicate...).",
+                "type": "string"
+              },
+              "scene": {
+                "description": "Its scene: id and ordinal within the chapter; null if none.",
+                "type": [
+                  "object",
+                  "null"
+                ]
+              },
+              "section": {
+                "description": "Section (1-based) whose header or footer this is.",
+                "type": "integer"
+              },
+              "story": {
+                "description": "Story kind outside the body: footnote, endnote, header or footer.",
+                "type": "string"
+              },
+              "tail_words": {
+                "description": "Words of the phrase's tail.",
+                "type": "integer"
+              },
+              "used_by_sections": {
+                "description": "Sections that show this header or footer.",
+                "items": {
+                  "type": "integer"
+                },
+                "type": "array"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "total": {
+          "description": "Items in the whole list, across pages.",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "estimated",
+        "paragraphs"
+      ],
+      "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. Addedv0.1.3

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare readOnlyHint/idempotentHint/openWorldHint=false, but the description adds real behavioral context: pagination at ~8,000 bytes with a `cursor`, that phrases may be null with a `reason` (empty, duplicate), and that structure:false skips detection to gain speed. It even flags the small annotation overlap ('Read-only') rather than contradicting 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 core capability and reasonably sized for a seven-parameter tool, with no filler sentences. It is, however, a single dense paragraph of stacked clauses and jargon-heavy tokens (p40#a1b2c3d4:0..) that slow parsing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/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 not be spelled out, yet the description still covers paging, null/duplicate phrase handling, the structure toggle, and the relationship to page.estimate. The dense profile/overrides detection semantics are left to the schema, which is acceptable.

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 every parameter including at, cursor, profile, overrides and structure. The description only lightly reinforces a few of these (offsets ignored, whole-document default, structure:false effect), so the baseline 3 for high coverage is correct.

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 concrete verb and resource ('say where paragraphs are') and enumerates the specific artifacts it returns: chapter, scene, estimated page, unique phrase, and a Word's-Find-safe phrase. It also names and distinguishes a sibling ('page.estimate gives only pages'), so an agent can tell it apart without opening the schema.

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?

Explicitly frames the use case ('Use it to tell a writer where a passage is') and contrasts with one alternative (page.estimate). It does not address when to prefer it over the nearer siblings para_list, para_get, or text_find, so the routing guidance is strong but incomplete.

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