Skip to main content
Glama
Sign In
doc-control

doc-control

by nuncaeslupus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

page_estimate

Read-onlyIdempotent

Estimate which page each paragraph starts or ends on in a .docx, using Word page marks or a words-per-page model; results are flagged estimated.

Instructions

Estimate the page each paragraph starts on (and ends on when it spans pages): from Word's rendered page marks and explicit breaks where present, else a words-per-page model; always flagged estimated. at (p142#a7b2a7b2) gives one paragraph; by "page" lists pages with their first and last paragraph instead. Use it to tell a user roughly where text is; para.locate adds chapter, scene and a find phrase. Read-only; paged at about 8,000 bytes with cursor.

Input Schema

NameRequiredDescriptionDefault
atNoOnly this paragraph, by address, e.g. p142#a7b2a7b2.
byNoList one row per paragraph (default) or per page.
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.

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": {
+        "at": {
+          "description": "With at: the paragraph.",
+          "type": "string"
+        },
+        "basis": {
+          "description": "model, or rendered+model when Word's page marks are used.",
+          "type": "string"
+        },
+        "end_page": {
+          "description": "Page it ends on, when it runs onto another page.",
+          "type": "integer"
+        },
+        "end_page_label": {
+          "description": "Page number as printed.",
+          "type": [
+            "integer",
+            "string"
+          ]
+        },
+        "estimated": {
+          "description": "Always true: pages are estimates.",
+          "type": "boolean"
+        },
+        "model": {
+          "description": "The model's constants.",
+          "type": "object"
+        },
+        "notes": {
+          "description": "Caveats about the estimate.",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "page": {
+          "description": "Estimated page (1-based).",
+          "type": "integer"
+        },
+        "page_count": {
+          "description": "Estimated page count.",
+          "type": "integer"
+        },
+        "page_label": {
+          "description": "Page number as printed.",
+          "type": [
+            "integer",
+            "string"
+          ]
+        },
+        "pages": {
+          "description": "by page: this page of rows.",
+          "items": {
+            "description": "A page.",
+            "properties": {
+              "from": {
+                "description": "First paragraph number on it.",
+                "type": "integer"
+              },
+              "page": {
+                "description": "Page.",
+                "type": "integer"
+              },
+              "page_label": {
+                "description": "Page number as printed.",
+                "type": [
+                  "integer",
+                  "string"
+                ]
+              },
+              "paragraphs": {
+                "description": "Paragraphs starting on it.",
+                "type": "integer"
+              },
+              "to": {
+                "description": "Last paragraph number on it.",
+                "type": "integer"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "paragraphs": {
+          "description": "by paragraph: this page of rows.",
+          "items": {
+            "description": "A paragraph.",
+            "properties": {
+              "at": {
+                "description": "Paragraph address, p<n>#<fingerprint> (story-prefixed in notes/headers).",
+                "type": "string"
+              },
+              "end_page": {
+                "description": "Page it ends on, when it runs onto another page.",
+                "type": "integer"
+              },
+              "end_page_label": {
+                "description": "Page number as printed.",
+                "type": [
+                  "integer",
+                  "string"
+                ]
+              },
+              "page": {
+                "description": "Estimated page (1-based).",
+                "type": "integer"
+              },
+              "page_label": {
+                "description": "Page number as printed.",
+                "type": [
+                  "integer",
+                  "string"
+                ]
+              },
+              "source": {
+                "description": "rendered (Word's page marks), break (explicit break) or model.",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "rendered_marks": {
+          "description": "Rendered page-break marks found.",
+          "type": "integer"
+        },
+        "source": {
+          "description": "rendered (Word's page marks), break (explicit break) or model.",
+          "type": "string"
+        },
+        "total": {
+          "description": "Items in the whole list, across pages.",
+          "type": "integer"
+        },
+        "words_per_page": {
+          "description": "Words per page the model assumes.",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "estimated",
+        "page_count",
+        "basis",
+        "words_per_page",
+        "rendered_marks",
+        "model",
+        "notes"
+      ],
+      "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.3/5.0
Behavior4/5

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

Annotations cover safety (readOnly, idempotent, non-open-world), and the description adds real behavioral context beyond them: results are always flagged `estimated`, the two estimation fallbacks, and the ~8,000-byte pagination with `cursor`. It does not discuss accuracy limits of the words-per-page model, 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-loaded with the core action and mechanism, and every clause carries information (fallback model, flag, addressing, pagination). It is densely packed into a few sentences and slightly compressed, but no sentence is wasted.

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 explained, and the description covers mechanism, the `estimated` caveat, addressing, sibling routing, and pagination. Only minor gaps remain, such as the practical accuracy of the words-per-page estimate when no page marks exist.

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 baseline is 3, but the description adds meaning beyond the schema: `at` accepts the address form p142#a7b2a7b2, `by: "page"` yields pages with their first and last paragraph, and `cursor` is tied to the ~8,000-byte page cap. It complements rather than repeats the schema.

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 precise verb+resource (estimate the page each paragraph starts/ends on) and explains the estimation basis (rendered page marks, explicit breaks, else a words-per-page model). It distinguishes itself from the closest sibling, para.locate, by naming what that tool adds.

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 explicit usage context ("Use it to tell a user roughly where text is") and names an alternative with its differentiating capability (para.locate adds chapter, scene and a find phrase). It stops short of stating when NOT to use it, so it is strong but not exhaustive.

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