Skip to main content
Glama
Sign In
doc-control

doc-control

by nuncaeslupus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

para_get

Read-onlyIdempotent

Read a full paragraph by address to inspect its text, style, direct formatting, and layout facts before editing or checking a .docx.

Instructions

Read one paragraph in full by address (p142#a7b2a7b2, or fn3/p1#… in a note): text, style, direct paragraph formatting, character-formatted spans (bold, italic, font...) and layout facts (heading_level is null for a body paragraph, 1-9 for a heading). Use it before editing a paragraph or to check its formatting; para.list reads many paragraphs, style.get a style. Read-only; a very long text is paged (limit characters, cursor from the reply's next). STALE_ADDRESS if it changed since read.

Input Schema

NameRequiredDescriptionDefault
atYesParagraph address from a read result, e.g. p142#a7b2a7b2.
docYesPath to the .docx.
limitNoMost characters of text to return.
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": {
+      "additionalProperties": true,
+      "description": "What the operation returns.",
+      "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"
+        },
+        "centred": {
+          "description": "Whether it is centred.",
+          "type": "boolean"
+        },
+        "empty": {
+          "description": "No visible text.",
+          "type": "boolean"
+        },
+        "format": {
+          "description": "Direct paragraph formatting (alignment, indent, spacing...).",
+          "type": "object"
+        },
+        "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"
+        },
+        "length": {
+          "description": "Length of the whole text, in code points.",
+          "type": "integer"
+        },
+        "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"
+        },
+        "offset": {
+          "description": "Where this page of text starts in the paragraph.",
+          "type": "integer"
+        },
+        "page_break_before": {
+          "description": "Whether it starts a page.",
+          "type": "boolean"
+        },
+        "runs": {
+          "description": "Spans of the text with direct character formatting.",
+          "items": {
+            "additionalProperties": true,
+            "description": "A span: start/end offsets plus its formatting (bold, italic, font...).",
+            "properties": {
+              "end": {
+                "description": "End offset.",
+                "type": "integer"
+              },
+              "start": {
+                "description": "Start offset.",
+                "type": "integer"
+              }
+            },
+            "required": [
+              "start",
+              "end"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "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": "This page of the text.",
+          "type": "string"
+        },
+        "used_by_sections": {
+          "description": "Sections that show this header or footer.",
+          "items": {
+            "type": "integer"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "at",
+        "number",
+        "length",
+        "style",
+        "style_name",
+        "format",
+        "offset",
+        "text",
+        "runs"
+      ],
+      "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.6/5.0
Behavior4/5

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

Annotations already declare readOnlyHint/idempotentHint, so safety is covered; the description goes further by disclosing paging behavior (limit characters, cursor from the reply's next) and the STALE_ADDRESS error condition when the address has changed. "Read-only" repeats the annotation, but the paging and staleness semantics are genuine additions.

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, then return contents, alternatives, and behavioral caveats in a logical order. The heavy parentheticals make it dense, but each clause carries distinct information rather than 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?

Covers the address format, what is returned, paging, error semantics, and sibling routing. An output schema exists so return values need not be enumerated, yet the description's brief summary of returned fields (text, style, formatting spans, layout facts) is helpful and complete.

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; the description adds value beyond the schema by illustrating the address syntax (including note addresses like fn3/p1#…) and explaining that limit/cursor drive paging. It also clarifies heading_level semantics (null for body, 1-9 for heading), which the schema does not.

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 ("Read one paragraph in full by address") with the exact address formats shown. It distinguishes itself from siblings by naming para.list (many paragraphs) and style.get (a style). An agent can select this tool 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 says when to use it ("before editing a paragraph or to check its formatting") and routes to alternatives for other cases ("para.list reads many paragraphs, style.get a style"). Nothing is left to inference.

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