AgentMD

Convert document to markdown

convert_document_to_markdown

Convert a document you already have (PDF, DOCX, HTML, plain text) to clean, LLM-ready markdown. Pass the file contents as base64. Supports reading only part of a large document: PDF page ranges, a heading outline, a single section, or a token cap.

Input Schema

TableJSON Schema

Name	Required	Description
`mode`	No	"full" (default) returns the document body. "outline" returns just the heading tree — each line is `- [#3] Heading text (~120 tokens)`. For a long document, call with mode: 'outline' first, then fetch only what you need with section: '#3' or a heading title.
`pages`	No	PDFs only: 1-indexed, inclusive page ranges to convert, e.g. "1-3,5,8-" (an open-ended range runs to the last page). Ignored with a warning for non-PDF formats.
`base64`	Yes	Base64-encoded file contents
`section`	No	Return only one section: either "#<n>" using the index from a mode: 'outline' call (e.g. '#3'), or the heading text itself (case-insensitive; exact match wins, then prefix, then substring). Ignored when mode is 'outline'.
`filename`	No	Original filename, e.g. report.pdf — helps format detection
`maxTokens`	No	Cap the returned markdown at roughly this many tokens, cutting at a paragraph boundary. When the output is cut, the result starts with a `> Truncated: ~X of ~Y tokens` line — narrow with pages or section rather than raising this.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedSep 16, 2026

addedInput schema / properties / maxTokens

Added value: +{
+  "description": "Cap the returned markdown at roughly this many tokens, cutting at a paragraph boundary. When the output is cut, the result starts with a `> Truncated: ~X of ~Y tokens` line — narrow with pages or section rather than raising this.",
+  "exclusiveMinimum": 0,
+  "maximum": 9007199254740991,
+  "type": "integer"
+}

addedInput schema / properties / mode

Added value: +{
+  "description": "\"full\" (default) returns the document body. \"outline\" returns just the heading tree — each line is `- [#3] Heading text (~120 tokens)`. For a long document, call with mode: 'outline' first, then fetch only what you need with section: '#3' or a heading title.",
+  "enum": [
+    "full",
+    "outline"
+  ],
+  "type": "string"
+}

addedInput schema / properties / pages

Added value: +{
+  "description": "PDFs only: 1-indexed, inclusive page ranges to convert, e.g. \"1-3,5,8-\" (an open-ended range runs to the last page). Ignored with a warning for non-PDF formats.",
+  "type": "string"
+}

addedInput schema / properties / section

Added value: +{
+  "description": "Return only one section: either \"#<n>\" using the index from a mode: 'outline' call (e.g. '#3'), or the heading text itself (case-insensitive; exact match wins, then prefix, then substring). Ignored when mode is 'outline'.",
+  "type": "string"
+}

First observedSep 1, 2026

TDQS

A4.6/5.0

Behavior4/5

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

No annotations are provided, so the description carries the full burden. It discloses several behavioral traits: supports reading only part of a large document, PDF page ranges, heading outline, single section, token cap; pages are ignored with a warning for non-PDF formats; section matching is case-insensitive with exact/prefix/substring precedence; truncated output starts with a '> Truncated: ~X of ~Y tokens' line. This is rich behavioral disclosure. It doesn't mention error handling for invalid base64 or unsupported formats, but the disclosed behaviors are substantial.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core purpose and input method, then a compact list of partial-read capabilities. Every sentence earns its place. The schema's parameter descriptions carry the detailed semantics, keeping the main description lean. No fluff or repetition.

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 6-parameter tool with no output schema and no annotations, the description plus schema covers the key usage workflow, partial-read modes, and truncation behavior. The main gap is that the description doesn't state what the output looks like for a successful full conversion (e.g., does it return just markdown or a wrapper object?), and there's no mention of error cases like invalid base64 or unsupported file types. However, the schema's mode description gives a concrete example of the outline output format, and the truncation line is documented. This is nearly complete for an agent to call the tool correctly.

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 description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the overall workflow (outline first, then section fetch) and by clarifying the truncation behavior and the 'narrow with pages or section' guidance. The schema already documents each parameter well, including the outline format and section matching precedence. The description's added value is moderate but meaningful, so a 4 is appropriate.

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?

The description states a specific verb ('Convert'), the resource ('a document you already have'), the input formats (PDF, DOCX, HTML, plain text), and the output ('clean, LLM-ready markdown'). It also distinguishes itself from the sibling convert_url_to_markdown by emphasizing 'you already have' (local file contents passed as base64) rather than a URL. This is a clear, specific purpose statement.

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?

The description explicitly says to pass file contents as base64 and gives concrete usage guidance for large documents: call with mode 'outline' first, then fetch only what you need with section '#3' or a heading title. The schema's mode parameter description reinforces this workflow. It also tells users to narrow with pages or section rather than raising maxTokens. This is explicit when-to-use guidance with a clear strategy.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All AgentMD tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Convert document to markdown

Input Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources