Skip to main content
Glama
nuncaeslupus

doc-control

by nuncaeslupus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

para_list

Read-onlyIdempotent

Lists every paragraph in document order with address, text, style, heading level, and layout facts to index or scan a whole document.

Instructions

List every paragraph in document order with its address, text, style, heading level and layout facts (centred, page break before, blank paragraphs before, empty, table cell); heading_level is null for a body paragraph. normalized adds normalised text, pages the estimated page, stories notes or headers. Use it to index or scan a whole document; para.get reads one paragraph with formatting, doc.outline only headings, text.find searches. Read-only; paged: about 8,000 bytes per reply (limit up to 1,000), continue with cursor set to the reply's next.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
docYesPath to the .docx.
limitNoMost items to return; a response is also capped at about 8,000 bytes.
pagesNoAdd the estimated `page` and `page_label` per paragraph, and `page_basis`, `rendered_marks` and `page_count` (see page.estimate).
cursorNoThe `next` value of the previous response, to continue the list.
storiesNoStories to read (default ["body"]): "notes" adds footnotes and endnotes, each after the paragraph holding its mark; "headers" adds headers and footers, after the body. Their addresses carry a prefix (fn3/p1#…, hdr1.default/p1#…).
normalizedNoAdd `normalized`, the text as `text.normalize` gives it.

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": {
+        "page_basis": {
+          "description": "With pages: model, or rendered+model when Word's page marks are used.",
+          "type": "string"
+        },
+        "page_count": {
+          "description": "With pages: estimated page count.",
+          "type": "integer"
+        },
+        "paragraphs": {
+          "description": "This page of paragraphs, in document order.",
+          "items": {
+            "description": "A paragraph.",
+            "properties": {
+              "at": {
+                "description": "Paragraph address, p<n>#<fingerprint> (story-prefixed in notes/headers).",
+                "type": "string"
+              },
+              "blank_before": {
+                "description": "Empty paragraphs right before it.",
+                "type": "integer"
+              },
+              "cell": {
+                "description": "Inside a table: where.",
+                "properties": {
+                  "col": {
+                    "description": "Grid column (0-based).",
+                    "type": "integer"
+                  },
+                  "row": {
+                    "description": "Row (0-based).",
+                    "type": "integer"
+                  },
+                  "table": {
+                    "description": "Table number.",
+                    "type": "integer"
+                  }
+                },
+                "type": "object"
+              },
+              "centred": {
+                "description": "Whether it is centred.",
+                "type": "boolean"
+              },
+              "empty": {
+                "description": "No visible text.",
+                "type": "boolean"
+              },
+              "heading_level": {
+                "description": "1-9 for a heading, null for a body paragraph.",
+                "type": [
+                  "integer",
+                  "null"
+                ]
+              },
+              "kind": {
+                "description": "Header/footer kind: default, first or even.",
+                "type": "string"
+              },
+              "normalized": {
+                "description": "With normalized: the text as text.normalize gives it.",
+                "type": "string"
+              },
+              "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"
+                ]
+              },
+              "number": {
+                "description": "Paragraph number (1-based) in its story.",
+                "type": "integer"
+              },
+              "page": {
+                "description": "With pages: estimated page (body paragraphs).",
+                "type": "integer"
+              },
+              "page_break_before": {
+                "description": "Whether it starts a page.",
+                "type": "boolean"
+              },
+              "page_label": {
+                "description": "Page number as printed.",
+                "type": [
+                  "integer",
+                  "string"
+                ]
+              },
+              "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"
+              },
+              "style": {
+                "description": "Paragraph style id.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "style_name": {
+                "description": "Paragraph style display name.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "text": {
+                "description": "Full text.",
+                "type": "string"
+              },
+              "used_by_sections": {
+                "description": "Sections that show this header or footer.",
+                "items": {
+                  "type": "integer"
+                },
+                "type": "array"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "rendered_marks": {
+          "description": "With pages: rendered page-break marks found.",
+          "type": "integer"
+        },
+        "total": {
+          "description": "Items in the whole list, across pages.",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "total",
+        "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.5/5.0
Behavior4/5

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

Annotations already declare readOnlyHint/idempotentHint/openWorldHint=false, and the description reinforces 'Read-only' while adding genuinely new operational context: paging at ~8,000 bytes per reply, limit up to 1,000, and resumption via `cursor` set to the reply's `next`. It also clarifies the null semantics of heading_level. It stops short of stating prerequisites (e.g. whether doc_open is required first) or error behavior.

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 resource and the returned fields before the routing guidance and paging caveat, and every clause carries information. The middle sentence is dense and semicolon-packed, which slightly hurts scanability, but nothing 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, field-level return documentation is not required, and the description still covers scope, flags, pagination and alternatives for a 6-parameter tool with one required arg. The only real omission is whether the document must be opened via doc_open before calling.

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: it explains what the flags yield (normalized adds normalised text, pages adds the estimated page, stories adds notes or headers), which tells the agent the output shape each flag unlocks rather than just its boolean type.

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?

Specific verb+resource ('List every paragraph in document order') plus an enumeration of exactly what each item carries (address, text, style, heading level, layout facts). It also names and distinguishes the nearest siblings (para.get, doc.outline, text.find), so an agent can identify it 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 Guidelines5/5

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

Explicitly states the use case ('index or scan a whole document') and names three alternatives with the condition that selects each: para.get for one paragraph with formatting, doc.outline for headings only, text.find for searching. This is exactly the when/when-not/alternative structure.

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