Skip to main content
Glama
nuncaeslupus

doc-control

by nuncaeslupus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

doc_segment

Read-onlyIdempotent

Split a .docx manuscript into chapters, parts, scenes, sentences, or dialogue lines with stable IDs for chapter-by-chapter work and sentence-level addresses.

Instructions

Split a manuscript into units with stable ids: unit chapters (default), parts or scenes (detected from headings, numerals, centring, scene markers; signals say which), or sentences or dialogue lines within range (an address, p24#a1b2c3d4..p60#e5f6a7b8, or a unit id such as ch-d5a3930d). chapter limits scenes to one chapter; language (default es) sets sentence rules; profile and overrides tune detection. Use it to work chapter by chapter or to get sentence addresses (p142#a7b2a7b2.s3); doc.outline lists only styled headings. Read-only; paged at about 8,000 bytes with cursor.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
docYesPath to the .docx.
unitNoWhat to list (default chapters).
limitNoMost items to return; a response is also capped at about 8,000 bytes.
rangeNosentences and dialogue only: what to cover — a paragraph address or range, a run of whole paragraphs (p24#fp..p60#fp), or a chapter, scene or part id (ch-…, sc-…, pt-…; same profile and overrides).
cursorNoThe `next` value of the previous response, to continue the list.
chapterNoscenes only: the chapter id whose scenes to list.
profileNoDetection settings for this document.
languageNoSentence rules (default es).
overridesNoForce or deny a chapter or scene at paragraphs by fingerprint.

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": {
+        "chapters": {
+          "description": "unit chapters: this page of chapters.",
+          "items": {
+            "description": "A chapter.",
+            "properties": {
+              "at": {
+                "description": "Paragraph address, p<n>#<fingerprint> (story-prefixed in notes/headers).",
+                "type": "string"
+              },
+              "first": {
+                "description": "First paragraph number.",
+                "type": "integer"
+              },
+              "heading_last": {
+                "description": "Last paragraph number of its heading.",
+                "type": [
+                  "integer",
+                  "null"
+                ]
+              },
+              "id": {
+                "description": "Stable id (ch-…, sc-…, pt-…), usable as `range`.",
+                "type": "string"
+              },
+              "kind": {
+                "description": "How its heading reads: chapter, numeral, ...",
+                "type": "string"
+              },
+              "last": {
+                "description": "Last paragraph number.",
+                "type": "integer"
+              },
+              "number": {
+                "description": "Its number, when the heading has one.",
+                "type": [
+                  "integer",
+                  "null"
+                ]
+              },
+              "part": {
+                "description": "Id of the part holding it.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "scenes": {
+                "description": "Scenes in it.",
+                "type": "integer"
+              },
+              "signals": {
+                "description": "What detected it (heading_style, numeral, centred, scene_marker...).",
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "text": {
+                "description": "Heading text (clipped).",
+                "type": "string"
+              },
+              "words": {
+                "description": "Words in it.",
+                "type": "integer"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "dialogue": {
+          "description": "unit dialogue: this page of dialogue lines.",
+          "items": {
+            "description": "A dialogue line.",
+            "properties": {
+              "at": {
+                "description": "Paragraph address, p<n>#<fingerprint> (story-prefixed in notes/headers).",
+                "type": "string"
+              },
+              "end": {
+                "description": "End offset.",
+                "type": "integer"
+              },
+              "parts": {
+                "description": "Its speech and narration pieces.",
+                "items": {
+                  "description": "A piece.",
+                  "properties": {
+                    "end": {
+                      "description": "End offset.",
+                      "type": "integer"
+                    },
+                    "kind": {
+                      "description": "speech or narration.",
+                      "type": "string"
+                    },
+                    "start": {
+                      "description": "Start offset.",
+                      "type": "integer"
+                    }
+                  },
+                  "type": "object"
+                },
+                "type": "array"
+              },
+              "start": {
+                "description": "Start offset.",
+                "type": "integer"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "front": {
+          "description": "chapters/parts: front matter before the first one (at, first, last, words).",
+          "type": [
+            "object",
+            "null"
+          ]
+        },
+        "parts": {
+          "description": "unit parts: this page of parts.",
+          "items": {
+            "description": "A part.",
+            "properties": {
+              "at": {
+                "description": "Paragraph address, p<n>#<fingerprint> (story-prefixed in notes/headers).",
+                "type": "string"
+              },
+              "chapters": {
+                "description": "Chapters in it.",
+                "type": "integer"
+              },
+              "first": {
+                "description": "First paragraph number.",
+                "type": "integer"
+              },
+              "heading_last": {
+                "description": "Last paragraph number of its heading.",
+                "type": [
+                  "integer",
+                  "null"
+                ]
+              },
+              "id": {
+                "description": "Stable id (ch-…, sc-…, pt-…), usable as `range`.",
+                "type": "string"
+              },
+              "kind": {
+                "description": "How its heading reads: chapter, numeral, ...",
+                "type": "string"
+              },
+              "last": {
+                "description": "Last paragraph number.",
+                "type": "integer"
+              },
+              "number": {
+                "description": "Its number, when the heading has one.",
+                "type": [
+                  "integer",
+                  "null"
+                ]
+              },
+              "signals": {
+                "description": "What detected it (heading_style, numeral, centred, scene_marker...).",
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "text": {
+                "description": "Heading text (clipped).",
+                "type": "string"
+              },
+              "words": {
+                "description": "Words in it.",
+                "type": "integer"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "scenes": {
+          "description": "unit scenes: this page of scenes.",
+          "items": {
+            "description": "A scene.",
+            "properties": {
+              "at": {
+                "description": "Paragraph address, p<n>#<fingerprint> (story-prefixed in notes/headers).",
+                "type": "string"
+              },
+              "chapter": {
+                "description": "Id of its chapter.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "first": {
+                "description": "First paragraph number.",
+                "type": "integer"
+              },
+              "id": {
+                "description": "Stable id (ch-…, sc-…, pt-…), usable as `range`.",
+                "type": "string"
+              },
+              "last": {
+                "description": "Last paragraph number.",
+                "type": "integer"
+              },
+              "signals": {
+                "description": "What detected it (heading_style, numeral, centred, scene_marker...).",
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "words": {
+                "description": "Words in it.",
+                "type": "integer"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "sentences": {
+          "description": "unit sentences: this page of sentences.",
+          "items": {
+            "description": "A sentence.",
+            "properties": {
+              "at": {
+                "description": "Sentence address, p<n>#<fp>.s<k>.",
+                "type": "string"
+              },
+              "end": {
+                "description": "End offset.",
+                "type": "integer"
+              },
+              "start": {
+                "description": "Start offset.",
+                "type": "integer"
+              },
+              "text": {
+                "description": "Its text (clipped).",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "suppressed": {
+          "description": "Suppressed breaks (capped).",
+          "items": {
+            "description": "A suppressed break.",
+            "properties": {
+              "at": {
+                "description": "Paragraph address, p<n>#<fingerprint> (story-prefixed in notes/headers).",
+                "type": "string"
+              },
+              "kind": {
+                "description": "chapter or scene.",
+                "type": "string"
+              },
+              "reason": {
+                "description": "Why.",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "suppressed_total": {
+          "description": "Breaks suppressed (by an override or rule).",
+          "type": "integer"
+        },
+        "total": {
+          "description": "Items in the whole list, across pages.",
+          "type": "integer"
+        },
+        "unit": {
+          "description": "chapters, parts or scenes.",
+          "type": "string"
+        },
+        "unmatched_overrides": {
+          "description": "Overrides that matched no paragraph.",
+          "items": {
+            "description": "An override.",
+            "properties": {
+              "action": {
+                "description": "force or suppress.",
+                "type": "string"
+              },
+              "fp": {
+                "description": "Fingerprint.",
+                "type": "string"
+              },
+              "kind": {
+                "description": "chapter or scene.",
+                "type": "string"
+              },
+              "nth": {
+                "description": "Which occurrence.",
+                "type": "integer"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "total"
+      ],
+      "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.3/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/closed-world, but the description adds real value beyond them: pagination behavior ('paged at about 8,000 bytes with `cursor`') and the fact that detection is signal-driven. It doesn't disclose limits on what splits, but the pagination detail is useful context the annotations don't cover.

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?

Dense but well front-loaded: the core action and unit list come first, then range syntax, then modifiers, then routing. Nearly every clause carries information, though the sentence is long and slightly burdensome to parse.

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?

For a 9-parameter tool with nested objects and an output schema, the description covers the main flows, id semantics, pagination and sibling contrast, so an agent can invoke it correctly. Detection internals live in the schema, which is appropriate, but a note on default output ordering/shape would make it fully 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, but the description adds examples beyond the schema: concrete address/range syntaxes (p24#a1b2c3d4..p60#e5f6a7b8, ch-d5a3930d, p142#a7b2a7b2.s3) and the meaning of `chapter`, `language`, `profile` and `overrides`. This meaningfully enriches otherwise-documented params.

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 ('split a manuscript into units with stable ids') and enumerates the outputs (chapters, parts, scenes, sentences, dialogue). It also explicitly distinguishes itself from the sibling 'doc.outline lists only styled headings'.

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 clear context ('Use it to work chapter by chapter or to get sentence addresses') and points to the alternative doc.outline. It lacks an explicit when-not or a fuller routing list among the many sibling segmentation/inspection tools, so it stops just short of a 5.

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