This server enables verified semantic document chunking — splitting long PDF and DOCX files into coherent, concept-aware chunks with AI-assisted boundary decisions and content integrity verification.
Parse and initialize a session (split_document): Start a boundary planning session from a PDF or DOCX file, configuring min/max pages, output format (Markdown, PDF, or both), and overlap pages.
Retrieve safe boundary candidates (get_boundary_context): Get the current content window and structurally safe cut points for the agent to choose from — without allowing arbitrary cuts.
Commit a boundary decision (commit_boundary): Apply a conceptual cut at a specific element ID, or extend the current window by one page, with a required human-readable reason.
Write and verify chunks (write_chunks): Generate the actual Markdown/PDF chunk files and automatically run content integrity verification (coverage, word count, table/image checks).
Read a generated chunk (get_chunk): Retrieve the content of a specific chunk by its numeric ID for review or further processing.
Re-run integrity checks (verify_integrity): Independently verify that all chunks correctly cover the source document without gaps, duplications, or alterations.
Get chunk analysis context (get_chunk_analysis_context): Retrieve full chunk content so an AI agent can perform conceptual analysis and assess coherence.
Commit chunk analysis (commit_chunk_analysis): Store bilingual (Persian and English) topic labels, study focus descriptions, and a coherence flag (confident or needs_review) for each chunk.
Get study index context (get_study_index_context): Retrieve verified chunk metadata and analyses to support authoring of final study indexes.
Commit study indexes (commit_study_index): Store agent-authored Persian and English study indexes for the full document.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@doc-splitter split 'calculus-notes.pdf' into study chunks"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Verified semantic document chunking for AI agents.
Turn long PDF and DOCX files into coherent, study-sized Markdown or PDF chunks—without cutting through paragraphs, lists, tables, or ideas.
CLI · MCP server · PDF · DOCX · Markdown · Verified PDF output
VeriChunk combines deterministic document parsing with constrained AI judgment. The parser decides where a cut is structurally safe; an AI agent decides where a cut is conceptually correct; the verifier proves that the generated chunks preserve the source.
It is designed for textbooks, lecture notes, research material, technical manuals, and other long documents that need to fit into human or model-sized working sessions.
Project status: Beta. The workflow and verification model are production-minded, but public interfaces may still evolve before 1.0.
Related MCP server: BigContext MCP
Long documents create three problems for AI-assisted reading and analysis:
Context pressure — entire books and manuals do not fit comfortably into a model context window.
Bad boundaries — page-based splitting cuts through arguments, tables, examples, and definitions.
Silent corruption — a generated chunk may omit, duplicate, reorder, or alter content without anyone noticing.
VeriChunk addresses all three. It creates bounded sessions around complete concepts, restricts agents to structurally valid cut points, and verifies the final output against a deterministic intermediate representation.
Typical splitter | VeriChunk |
Cuts every N pages or tokens | Chooses among structurally safe, concept-aware boundaries |
Lets an LLM invent arbitrary ranges | Constrains decisions to parser-generated element IDs |
Trusts generated output | Reconstructs and verifies content, images, tables, and PDF pages |
Produces anonymous numbered files | Supports agent-authored topics, study focus, and semantic filenames |
Fails or degrades silently | Records parser fallbacks, skipped pages, and reconciliation notes |
One-shot workflow | Supports review, repair, re-verification, and auditable session state |
Semantic-first splitting — prefers 5–12 page sessions, allows page 13 for concept completion, and enforces an absolute 20-page cap.
Safe-cut constraints — boundaries can occur only after complete headings, paragraphs, lists, tables, or images.
Heading-free topic detection — scores semantic change points even when the source has weak structure.
Independent topic review — transition, continuity, and adjudicator roles evaluate possible topic changes with evidence from both sides.
PDF and DOCX support — structured extraction, native Word lists, tables, and embedded images.
Resilient PDF parsing — pymupdf4llm, native PyMuPDF fallback, and optional OpenDataLoader reconciliation.
Markdown and PDF output — generate AI-friendly text, page-faithful PDF chunks, or both.
Content-derived verification — detects missing, duplicated, unknown, reordered, or altered source elements.
Boundary repair — incoherent chunks can be split again without rewriting unaffected chunks.
CLI and MCP — run directly or expose the workflow to Claude Code, Codex, Cursor-compatible hosts, Grok, OpenCode, and other MCP clients.
Bilingual study artifacts — supports Persian and English topics, study focus, indexes, and a document-level study map.
Bounded execution — external processes use timeouts, cancellation, output limits, and strict JSON handling.
Dependency | Version | Needed for |
Python | 3.10+ | Core parser, workflow, writers, and CLI |
Node.js | 18+ | MCP server |
Java | 11+ | Recommended OpenDataLoader PDF reconciliation |
AI agent | — | Conceptual boundary decisions and content analysis |
Java is recommended, not mandatory. If OpenDataLoader is unavailable, PDF parsing continues and records the fallback in the verification report.
git clone https://github.com/alifazelidehkordi/VeriChunk.git
cd verichunk
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,agents]"
npm ciConfirm the installation:
verichunk --help
node --check server.js
java -version # optional, but recommended for PDF reconciliationverichunk run \
--input ./book.pdf \
--out ./output/book \
--min-pages 5 \
--max-pages 12This writes the normalized document representation to ir.json, creates a revisioned .split-session.json, and returns the next required action.
A document starts in one of two states:
topic_review when possible semantic transitions need independent review;
boundary when the planner can immediately request a cut decision.
Use an external JSON reviewer, OpenAI, Anthropic, or your MCP host's own subagents.
export OPENAI_API_KEY="..."
export DOC_SPLITTER_OPENAI_MODEL="your-review-model"
verichunk run-topic-reviews \
--out ./output/book \
--workers 6 \
--backend openaiThe DOC_SPLITTER_* environment variable prefix is retained for backward compatibility.
Request the current decision window:
verichunk boundary-context --out ./output/bookThe response includes source content and a list of allowed candidates. An agent selects one returned element_id:
verichunk commit-boundary \
--out ./output/book \
--action cut \
--element-id el-042 \
--reason "The current mechanism is complete; the next section introduces a different learning objective."If the same concept continues from page 12 to page 13:
verichunk commit-boundary \
--out ./output/book \
--action extend \
--allow-oversize \
--reason "The concluding example on page 13 completes the same mechanism."Extensions beyond page 13 require at least two independent reviewers and evidence element IDs. No extension can cross a confirmed topic change. At 20 pages, VeriChunk forces the best available safe boundary and records continuation metadata.
Repeat boundary-context and commit-boundary until the stage becomes boundary_complete.
verichunk write \
--out ./output/book \
--output-format bothwrite generates chunks, a manifest, and a verification report. It exits non-zero when integrity checks fail.
For each chunk:
verichunk analysis-context --out ./output/book --chunk-id 1
verichunk commit-analysis \
--out ./output/book \
--chunk-id 1 \
--topic-fa "تنظیم گلوکز و پاسخ انسولین" \
--topic-en "Glucose Regulation and Insulin Response" \
--study-focus-fa "مسیرهای اصلی تنظیم قند خون، نقش انسولین و تفاوت پاسخ طبیعی و پاتولوژیک را مرور کنید." \
--study-focus-en "Master the main glucose-control pathways, insulin's role, and the distinction between normal and pathological responses." \
--coherence confident \
--reason "The chunk presents one continuous regulatory mechanism."A chunk marked needs_review enters the constrained repair flow:
verichunk repair-context --out ./output/book --chunk-id 4
verichunk repair-boundary \
--out ./output/book \
--chunk-id 4 \
--cut-element-id el-118 \
--reason "The diagnostic framework ends before treatment planning begins."After every chunk has been read and analyzed:
verichunk index --out ./output/book
verichunk commit-index \
--out ./output/book \
--fa-file ./agent-written-study-index-fa.md \
--en-file ./agent-written-study-index-en.md \
--map-file ./agent-written-study-map.mdInstall the Node dependencies and register the server with available clients:
npm ci
./scripts/install-mcp.shManual registration examples:
REPO=/absolute/path/to/verichunk
claude mcp add verichunk -s user -- \
env DOC_SPLITTER_PYTHON="$REPO/.venv/bin/python3" \
node "$REPO/server.js"
codex mcp add verichunk -- \
env DOC_SPLITTER_PYTHON="$REPO/.venv/bin/python3" \
node "$REPO/server.js"Project-level configuration:
{
"mcpServers": {
"verichunk": {
"command": "node",
"args": ["/absolute/path/to/verichunk/server.js"],
"env": {
"DOC_SPLITTER_PYTHON": "/absolute/path/to/verichunk/.venv/bin/python3",
"DOC_SPLITTER_REVIEW_BACKEND": "openai",
"DOC_SPLITTER_OPENAI_MODEL": "your-review-model",
"OPENAI_API_KEY": "set-this-through-your-secret-manager"
}
}
}
}Suggested agent prompt:
Use the VeriChunk MCP tools to split
book.pdfinto coherent Markdown chunks underoutput/book. Prefer 5–12 pages, allow page 13 only to finish the same concept, and never exceed 20 pages. Review possible topic changes, choose only returned safe candidates, write and verify the chunks, analyze every chunk in Persian and English, repair incoherent chunks, and author the final study indexes.
Provider keys are read from the MCP server environment. They are not accepted in tool inputs and are not written to session files or logs.
flowchart TD
A[PDF or DOCX] --> B[Format detector]
B -->|PDF| C[pymupdf4llm]
B -->|PDF fallback| D[Native PyMuPDF]
B -->|Optional layout pass| E[OpenDataLoader]
B -->|DOCX| F[python-docx]
C --> G[Document IR]
D --> G
E --> H[PDF reconciliation]
H --> G
F --> G
G --> I[Structure analysis]
I --> J[Semantic change-point scoring]
J --> K[Independent topic review]
K --> L{Constrained boundary agent}
L -->|safe cut| M[Revisioned boundary plan]
L -->|evidence-gated extension| J
M --> N[Markdown/PDF writers]
N --> O[Content-derived verifier]
O -->|pass| P[Chunk analysis]
O -->|fail| Q[Actionable verification report]
P -->|coherent| R[Study indexes and map]
P -->|needs review| S[Split-only boundary repair]
S --> NThe AI never edits parser state directly. It chooses from deterministic options and supplies an auditable rationale.
VeriChunk verifies generated output against the parsed source rather than trusting filenames or manifest metadata.
every expected IR element appears exactly once;
no unknown element is introduced;
element order is preserved;
protected Markdown blocks reconstruct correctly;
word counts remain within configured tolerance;
expected table rows remain present;
image references exist and extracted image hashes match.
every non-skipped source page is covered;
page ranges match the manifest;
output pages are visually compared with rendered source pages;
overlap pages are accounted for explicitly;
missing-text and skipped pages are reported.
boundary plans cannot contain gaps or overlaps;
confirmed topic changes cannot be crossed;
unreviewed semantic transitions block planning;
indexing is blocked until every chunk has committed analysis;
agents must read every chunk before committing final indexes;
generic auto-generated reasons and study-focus templates are rejected.
The primary command is verichunk. doc-splitter remains a compatibility alias.
Command | Purpose |
| Parse a document and start a revisioned split session. |
| Parse only and write |
| Build evidence-backed topic-change review tasks. |
| Store independent topic-change votes. |
| Run reviewer tasks through heuristic, command, OpenAI, or Anthropic backends. |
| Return the current content window and safe cut candidates. |
| Commit a safe cut or an evidence-gated extension. |
| Write chunks and run verification. |
| Re-run integrity checks against existing output. |
| Read one generated chunk. |
| Return full chunk content and analysis instructions. |
| Store bilingual topic, study focus, and coherence. |
| Return an incoherent chunk and safe internal repair candidates. |
| Split a queued chunk and re-verify affected output. |
| Return verified context for final indexes and study map. |
| Store agent-authored Persian, English, and map artifacts. |
Option | Default | Description |
|
| Session, IR, chunk, report, and index directory. |
|
| Preferred minimum; a confirmed topic change may cut earlier. |
|
| Preferred maximum. |
|
| Output type; PDF output requires PDF input. |
|
| Neighboring pages included around PDF boundaries. |
|
| Reading-time estimate used in indexes. |
Use verichunk COMMAND --help for command-specific options.
Tool | Mutates state? | Purpose |
| yes | Parse input and create a split session. |
| no | Return independent semantic review tasks. |
| yes | Execute and commit reviewer votes. |
| yes | Store host-supplied evidence-backed votes. |
| no | Return source context and safe candidates. |
| yes | Commit a cut or one-page extension. |
| yes | Write Markdown/PDF chunks and verify them. |
| no | Re-run verification. |
| no | Read one generated chunk. |
| no | Return full content for analysis. |
| yes | Store bilingual analysis and coherence. |
| no | Return safe internal repair points. |
| yes | Apply split-only repairs and verify again. |
| no | Return context for final index authoring. |
| yes | Store final indexes and study map. |
When output_dir is omitted, the MCP server creates an isolated directory under output-runs/, preventing concurrent jobs from overwriting each other.
Use get_topic_change_review_batch, distribute tasks to independent host agents, then submit the resulting votes with commit_topic_change_reviews.
The command must read one JSON task from stdin and write one JSON review object to stdout.
verichunk run-topic-reviews \
--out ./output/book \
--backend command \
--agent-command ./scripts/my-json-reviewer \
--workers 6pip install -e ".[openai]"
export OPENAI_API_KEY="..."
export DOC_SPLITTER_OPENAI_MODEL="your-review-model"
verichunk run-topic-reviews --out ./output/book --backend openaipip install -e ".[anthropic]"
export ANTHROPIC_API_KEY="..."
export DOC_SPLITTER_ANTHROPIC_MODEL="your-review-model"
verichunk run-topic-reviews --out ./output/book --backend anthropicThe heuristic backend exists for deterministic offline testing and baselines; it is not a substitute for independent semantic review.
Setting | Default | Notes |
Minimum pages |
| Soft target only. |
Preferred maximum |
| Normal planning window. |
Soft maximum |
| Allowed to finish the same concept with a specific reason. |
Absolute maximum |
| Cannot be raised; forces a continuation split. |
Words per page |
| Converts page targets to word-count windows. |
PDF overlap pages |
| Reduces context loss at page-level PDF boundaries. |
Study reading speed |
| Appropriate for dense technical or medical material. |
Topic reviewers |
| Transition, continuity, and adjudicator roles. |
Continuity reviewers |
| Minimum required beyond page 13. |
OCR | disabled | Image-only pages are skipped and flagged. |
Internal defaults live in src/doc_splitter/config.py.
Variable | Purpose |
| Python interpreter used by the MCP server. |
| Default |
| External JSON reviewer command. |
| OpenAI review model. |
| Anthropic review model. |
| CLI subprocess timeout. |
| Maximum captured process output. |
| Base directory for isolated MCP runs. |
| Set to |
A typical Markdown run:
output/book/
├── 01-introduction-to-glucose-regulation.md
├── 02-insulin-signaling-and-feedback.md
├── images/
├── ir.json
├── semantic-map.json
├── manifest.json
├── verification-report.json
├── semantic-review-report.json
├── study-index-fa.md
├── study-index-en.md
├── study-map.md
└── .split-session.jsonFile | Purpose |
| Ordered, normalized source elements. |
| Revisioned workflow state, decisions, analyses, and failures. |
| Chunk ranges, filenames, element IDs, pages, and boundary reasons. |
| Coverage, content, image, table, and PDF integrity results. |
| Coherence summary and repair queue. |
| Persian session index. |
| English session index. |
| Topic map, dependencies, suggested study order, and session directory. |
PDF or both runs also include one .pdf file per chunk.
The enforced state machine is:
topic_review → boundary → boundary_complete → writing → verification
→ content_analysis → index → complete
↘ boundary_repair → writing → verificationSafety properties:
state files are revisioned and written atomically under an advisory lock;
stale concurrent writes fail with SessionConflictError;
saved run settings persist across commands;
only explicitly supplied CLI values override saved settings;
write is blocked when reviews, boundaries, gaps, or overlaps are unresolved;
repair can only split inside the queued chunk and cannot merge across established boundaries;
unchanged chunks preserve their exact body and analysis during repair.
Scanned PDFs: OCR is disabled by default; image-only pages are skipped and reported.
Password-protected PDFs: not supported.
DOCX page numbers: estimated from word count because DOCX has no stable rendered pagination.
PDF cut precision: semantic decisions occur at element boundaries, but PDF output contains whole pages.
Very short documents: may produce fewer or smaller chunks than the target range.
Very long concepts: extensions after page 13 require evidence; page 20 is absolute.
Non-Latin filenames: semantic filenames are ASCII-folded, with section-N as fallback.
Layout fidelity: Markdown is best for semantic processing; PDF is best for preserving visual layout.
Problem | Likely cause | Fix |
| Input is not PDF or DOCX. | Convert the file or use a supported extension. |
Password-protected PDF error | The source requires a password. | Save an unlocked copy and rerun. |
Java/OpenDataLoader warning | Java 11+ is missing or the layout parser failed. | Install a JDK and confirm |
Missing elements during verification | Generated blocks, order, or manifest ranges differ from the IR. | Regenerate with |
Image/hash/page mismatch | Generated assets changed after writing. | Restore or regenerate the named chunk and inspect the report. |
PDF output rejected for DOCX | PDF chunks require PDF source pages. | Use |
Missing content analyses | Not every chunk has committed analysis. | Run |
Chunk files not read | The agent tried to index unread chunks. | Call |
Conceptual reason rejected | The reason is generic or auto-generated. | Explain what ends, what begins, and why the boundary is coherent. |
MCP cannot import the package | MCP is using the wrong Python interpreter. | Point |
Temporary-file error | No writable temporary directory exists. | Set |
verichunk/
├── server.js # MCP server
├── mcp/ # Node process and argument helpers
├── pyproject.toml # Python packaging and CLI entry points
├── package.json # MCP dependencies
├── scripts/install-mcp.sh # MCP registration helper
├── src/doc_splitter/
│ ├── cli.py # CLI entry point
│ ├── orchestrator.py # Pipeline coordination
│ ├── config.py # Workflow defaults
│ ├── format_detector.py # Input detection
│ ├── ir/ # Intermediate representation
│ ├── parsers/ # PDF/DOCX parsing and reconciliation
│ ├── semantic.py # Semantic change-point scoring
│ ├── agents/ # Reviewer backends and scheduler
│ ├── boundary/ # Safe candidates and session planning
│ ├── writers/ # Markdown and PDF writers
│ ├── content/ # Analysis and repair workflow
│ ├── markdown_codec.py # Canonical protected rendering
│ ├── verifier.py # Content-derived integrity checks
│ └── index_generator.py # Index context and commit logic
└── tests/uv sync --frozen --extra dev --extra agents
uv run ruff check .
uv run ruff format --check .
uv run mypy src/doc_splitter
uv run pytest -q
npm ci
npm test
node --check server.js
uv buildRun the frozen golden-corpus audit:
PYTHONPATH=src python3 scripts/audit-golden-corpus.py \
--output docs/baseline/golden-results.jsonRun the MCP server directly:
node server.jsIt will wait for JSON-RPC messages over stdio.
The project was originally published as ducsplit with the CLI and Python distribution named doc-splitter.
The new public brand is VeriChunk. The migration is intentionally non-breaking:
Interface | Preferred | Compatibility status |
Project/repository name |
| Current public repository and product name. |
CLI |
|
|
MCP server registration |
| Existing |
Python distribution |
| Retained in the 0.5 series to avoid lockfile and package breakage. |
Python import |
| Retained to avoid breaking integrations. |
Environment variables |
| Retained for backward compatibility. |
A future major release can deprecate legacy identifiers through a documented migration rather than an abrupt rename.
Constrain model judgment. Agents choose among safe options; they do not invent parser state.
Make every decision auditable. Boundaries, evidence, reviewers, reasons, and revisions are persisted.
Verify content, not metadata. Output is reconstructed and compared with source-derived elements.
Prefer concepts over page counts. Size targets guide the process but do not override confirmed topic changes.
Fail loudly and specifically. Parser fallbacks, skipped content, conflicts, and integrity errors are reported.
Preserve unaffected work. Repair rewrites only changed ranges and retains exact unchanged chunks.
Keep model providers optional. Use host agents, external commands, OpenAI, Anthropic, or deterministic test backends.
MIT. See LICENSE.
Commit a conceptual boundary cut or window extension.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| reason | No | ||
| element_id | No | ||
| output_dir | No | Output directory (default: output) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, implying mutation, but the description does not disclose what 'commit' entails (e.g., saving, finalizing, or destructive actions). No additional behavioral context beyond the annotation is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise but vague. It sacrifices clarity for brevity, and the term 'conceptual boundary' is not well-defined.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters, 1 required, and no output schema, the description is insufficient. It does not explain the tool's overall behavior, return value, or how parameters interact, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (25%), with only output_dir described. The description mentions 'cut' and 'extend' but does not clarify how action, reason, or element_id are used. It fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a verb ('Commit') and a resource ('conceptual boundary cut or window extension'), but the resource is abstract and not clearly defined. It distinguishes from siblings by mentioning boundary operations, but lacks specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like commit_chunk_analysis or get_boundary_context. There is no mention of prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store bilingual topic, study focus, and coherence flag for a chunk.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | ||
| chunk_id | Yes | ||
| topic_en | Yes | ||
| topic_fa | Yes | ||
| coherence | Yes | ||
| output_dir | No | Output directory (default: output) | |
| study_focus_en | Yes | ||
| study_focus_fa | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, confirming mutation. The description adds the verb 'Store', which is consistent but does not disclose side effects such as whether existing data is overwritten or appended, nor does it mention any authentication or authorization requirements. Beyond the annotation signal, little behavioral context is added.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 12 words, achieving high conciseness. It is front-loaded and to the point. A slight improvement could be adding brief structure or clarifying the output, but it is already efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (8 parameters, 6 required, no output schema), the description is incomplete. It does not specify return behavior, error conditions, or how data is persisted. There is no mention of the relationship to sibling commit tools, leaving significant gaps for an agent to operate correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 13% (only output_dir has a description). The description groups parameters into 'bilingual topic, study focus, and coherence flag', which maps to six of the eight parameters, providing some semantic clarity. However, it does not explain the purpose of 'chunk_id', 'reason', or 'output_dir' beyond the schema's minimal info. It adds value but insufficiently compensates for low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool stores bilingual topic, study focus, and coherence flag for a chunk. It uses a specific verb ('Store') and identifies the resource (analysis data for a chunk). However, it does not differentiate from sibling tools like 'commit_boundary' or 'commit_study_index' which may have similar purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no discussion of prerequisites, expected context, or conditions that would make this tool appropriate. The description offers no usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store Persian and English study indexes authored by the host agent.
| Name | Required | Description | Default |
|---|---|---|---|
| index_en | Yes | ||
| index_fa | Yes | ||
| output_dir | No | Output directory (default: output) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate this is a write operation (readOnlyHint=false). Description adds no further detail on overwrite behavior, error conditions, or side effects. Does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise and front-loaded with purpose. Could be expanded with structure (e.g., bullet points) but no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and no description of return values or success/failure indicators. Lacks context on default output directory ('output') and behavior when directory exists. For a store action, this is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (33%). Description adds minimal meaning: implies index_en and index_fa are content strings but no format, constraints, or examples. output_dir schema has description; description adds nothing extra.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action ('store'), resource ('study indexes'), and scope ('Persian and English', 'authored by the host agent'). Distinguishes from sibling tools which operate on boundaries, chunks, and boundaries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use versus alternatives (e.g., write_chunks, get_study_index_context). No prerequisites, exclusion criteria, or related tool suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return content window and safe cut candidates for the host agent.
| Name | Required | Description | Default |
|---|---|---|---|
| output_dir | No | Output directory (default: output) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's 'Return' aligns with read-only behavior. The description adds minimal context ('for the host agent') but no new behavioral traits beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. It is front-loaded with the core function, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, read-only, no output schema), the description adequately states its purpose and return type. It is complete enough for an agent to understand the tool's role, though it could mention that output_dir is optional.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the single parameter (output_dir). The tool description does not add any additional meaning beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns 'content window and safe cut candidates' for the host agent. It uses a specific verb and resource, distinguishing it from siblings like get_chunk and get_chunk_analysis_context. However, it could be more explicit about what exactly constitutes a content window.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_chunk or get_chunk_analysis_context. There are no when-to-use or when-not-to-use indications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read chunk content by numeric id (Markdown or extracted PDF text).
| Name | Required | Description | Default |
|---|---|---|---|
| chunk_id | Yes | ||
| output_dir | No | Output directory (default: output) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, so the description adds value by specifying the content format (Markdown/PDF). However, it does not disclose return behavior, error handling, or how output_dir affects the result. With annotations covering safety, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 11 words, front-loaded with the core purpose. No redundant information; every word contributes to clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should clarify what the tool returns or saves. It mentions output_dir but not its role (save content vs. specify path). Missing error context and relationship to other tools. Adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (output_dir documented in schema). The tool description adds 'numeric id' for chunk_id, partially compensating for its missing schema description. Additional parameter details beyond the schema are minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read chunk content by numeric id', specifying the verb (Read) and resource (chunk content). It also adds the content type distinction ('Markdown or extracted PDF text'), which helps differentiate from sibling 'get' tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus siblings like get_boundary_context or get_chunk_analysis_context. The description lacks explicit alternatives or usage context, leaving the agent to infer from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return full chunk content for host-agent conceptual analysis.
| Name | Required | Description | Default |
|---|---|---|---|
| chunk_id | Yes | ||
| output_dir | No | Output directory (default: output) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint and openWorldHint, so safety and scope are clear. Description adds contextual purpose but no further behavioral traits like pagination or limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is efficient and front-loaded, but could include more detail without harming conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and only partial parameter descriptions, the tool lacks completeness for an agent to understand return format and usage fully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50% (output_dir described). Description does not explain chunk_id or add meaning beyond schema; required parameter is undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Return' and clear resource 'full chunk content' for conceptual analysis, distinguishing it from sibling tools like get_chunk or get_boundary_context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives; lacks when-not or context for selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return verified chunk metadata and analyses so the host agent can author the study indexes.
| Name | Required | Description | Default |
|---|---|---|---|
| output_dir | No | Output directory (default: output) | |
| reading_speed_wpm | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, suggesting possible side effects, but description says 'Return' implying read-only. This contradiction is not resolved. No disclosure of side effects, auth needs, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks structure. While not verbose, it fails to front-load key behavioral details or usage context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description does not explain return format, pagination, or error behavior. For a tool with two parameters and no output schema, the description is insufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%; only output_dir has a description. reading_speed_wpm lacks any description. The tool description does not add meaning for either parameter, failing to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns 'verified chunk metadata and analyses' for authoring study indexes. The verb 'Return' and specific resource help distinguish from sibling tools like 'get_chunk_analysis_context'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for authoring study indexes but does not specify when not to use or compare with siblings like get_boundary_context or get_chunk_analysis_context. No guidance on prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parse a PDF/DOCX and start the boundary planning session.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| max_pages | No | ||
| min_pages | No | ||
| output_dir | No | Output directory (default: output) | |
| output_format | No | ||
| overlap_pages | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate this is not read-only, and the description confirms it initiates a session. However, it provides no additional details about side effects, permissions, or rate limits beyond what annotations already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise but lacking essential details. It front-loads the action but ends with a vague phrase ('start the boundary planning session') that reduces clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters, low schema coverage, no output schema, and a complex ecosystem of sibling tools, the description is severely incomplete. It fails to explain the workflow, expected outcomes, or how this tool integrates with others.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17% (only output_dir has a description), and the tool description does not add any parameter-level context. The description fails to clarify the meaning or usage of parameters like max_pages, min_pages, or overlap_pages.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the action ('Parse a PDF/DOCX') and resource ('start the boundary planning session'), distinguishing it from sibling tools that focus on committing, getting context, or writing chunks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like commit_boundary or get_boundary_context. The description implies it is the first step but does not state preconditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run coverage, word-count, and table/image integrity checks.
| Name | Required | Description | Default |
|---|---|---|---|
| output_dir | No | Output directory (default: output) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true; description adds no behavioral details beyond what annotations provide, such as error behavior or non-destructive nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, efficient and to the point, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and description omits what results look like, how to interpret integrity outcomes, or any error handling, leaving the agent guessing about the tool's full behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with param description for 'output_dir'. Tool description does not add any additional semantic meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs coverage, word-count, and table/image integrity checks, which distinguishes it from sibling tools focused on committing, splitting, or analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, or any prerequisites or typical workflow context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write chunk markdown files and run verification after boundaries are complete.
| Name | Required | Description | Default |
|---|---|---|---|
| output_dir | No | Output directory (default: output) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only and non-open-world, so the write behavior is expected. The description adds that verification runs after boundaries are complete, which is behavioral context beyond what annotations provide. It doesn't detail what verification entails, but the added value lifts it above baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the primary action ('Write chunk markdown files') and then specifies the condition. Every word serves a purpose with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and no output schema, so a brief description might suffice. However, the description omits what the verification step does or what the tool returns. Given the lack of output schema, some additional context about return value or side effects would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage and only one parameter, the description adds no additional semantic value beyond the schema. The parameter 'output_dir' is self-explanatory with its schema description. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Write' and the resource 'chunk markdown files', distinguishing it from siblings like split_document (which splits) and commit_boundary (which finalizes boundaries). The specific action and condition are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: 'after boundaries are complete'. This helps the agent know when to invoke it, but it doesn't mention alternatives or when not to use it. Since the sibling tools are distinct, the guidance is adequate but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0commit_boundarycommit_chunk_analysiscommit_study_indexget_boundary_contextget_chunkget_chunk_analysis_contextget_study_index_contextsplit_documentverify_integritywrite_chunksScored across 10 tools
Tool purposes are mostly distinct, but there is some potential confusion between 'commit_boundary' and 'commit_chunk_analysis' (both commit operations) and between 'get_boundary_context' and 'get_chunk_analysis_context' (both get context). However, descriptions clearly differentiate them based on what is being committed or retrieved.
All tools follow a consistent verb_noun pattern using snake_case: commit_*, get_*, split_document, verify_integrity, write_chunks. The naming is predictable and clear.
With 10 tools, the server is well-scoped for a document splitting workflow. Each tool serves a distinct stage in the process, from parsing to writing chunks, without unnecessary overlap.
The tool set covers the full lifecycle of document splitting: parsing, boundary context, committing boundaries, chunk retrieval, analysis, writing, verification, and study indexing. No obvious gaps are present.
Extract PDFs to Markdown, RAG chunks and cited tables; publish tracked Doc Links with read stats.
Stateless agentic tools over MCP: concept extraction, long-context, knowledge graph, planning.
Parse PDF/Word/PPT/HTML to Markdown; tables as JSON, image extraction, RAG chunking, page ranges.
Parse, extract, split, and ask over digital PDFs (text layer, no OCR) from Cursor and Claude.
