agentmd-mcp

Convert a local file to markdown

convert_file_to_markdown

Read-only

Convert a local document (PDF, DOCX, HTML, Markdown, or text) into clean, LLM-ready Markdown by providing its absolute file path. Extract text, preserve tables, and get optional page/section selection for large files.

Instructions

Reads a document from the local filesystem by absolute path and converts it to clean, LLM-ready markdown. Use this instead of convert_url_to_markdown when the document is already saved on disk, and instead of convert_document_to_markdown when you have a path and would otherwise have to read and base64-encode the bytes yourself — this tool does that reading and encoding for you. Returns one markdown text block: the detected title as a leading # <title> line when one is found, a > Warnings: ... blockquote line when the converter reports warnings, and tables preserved as GFM. Supported formats are PDF, DOCX, HTML, Markdown, and plain text, up to 25 MB per document; PDFs are text-extraction only, so scanned or image-only PDFs yield little or no text (OCR is not available yet). Requires AGENTMD_API_KEY; on a missing or unreadable file, a 401, a network failure, or an unsupported format it returns an isError result whose text explains what went wrong. Each successful call consumes one conversion from the account quota. To read only part of a large document, use the optional pages (PDF page ranges), mode: 'outline' then section, and maxTokens parameters instead of pulling the whole thing into context.

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.
`path`	Yes	Absolute path to the document on the filesystem of the machine running this MCP server, not the client machine (e.g. /home/me/docs/report.pdf or C:\\docs\\report.pdf). The file is read locally and its bytes are sent to the AgentMD API; the basename is used for format detection, so keep the file extension.
`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.
`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'.
`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 changedv0.1.4Sep 17, 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 observedv0.1.0Sep 15, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description goes well beyond that: it discloses the AGENTMD_API_KEY requirement, error behaviors (missing file, 401, network failure, unsupported format returning an isError result), quota consumption per call, the 25 MB size limit, and the PDF text-extraction-only limitation with no OCR. This is exactly the kind of behavioral context annotations cannot carry.

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?

The description is long, but nearly every clause earns its place — the information density is high and there is minimal fluff. Core purpose and sibling routing are front-loaded before constraints, error handling, and optimization guidance. It could arguably be split, but as a single block it reads logically and never repeats what the schema already states.

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?

For a tool with 5 parameters, an output schema that does not exist, error handling, format constraints, and partial-read options, this description is essentially complete. It explains the return format (title line, warnings blockquote, GFM tables, truncation header), supported formats, size limit, OCR limitation, auth requirement, quota impact, and error semantics — nothing an agent needs to call it correctly is missing.

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 real meaning beyond the schema: it explains that pages is 'Ignored with a warning for non-PDF formats,' that maxTokens truncation adds a '> Truncated: ~X of ~Y tokens' header line and cuts at paragraph boundaries, and that mode: 'outline' produces a token-estimated heading tree for navigation. These behavioral nuances are not in the schema properties.

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 opens with a specific verb and resource — 'Reads a document from the local filesystem by absolute path and converts it to clean, LLM-ready markdown.' It immediately distinguishes itself from both siblings by naming convert_url_to_markdown and convert_document_to_markdown with the exact conditions that select each. An agent can tell this tool apart without opening any 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?

Explicit routing guidance: 'Use this instead of convert_url_to_markdown when the document is already saved on disk, and instead of convert_document_to_markdown when you have a path and would otherwise have to read and base64-encode the bytes yourself.' It also advises when NOT to pull a whole document into context, directing agents to pages, mode: 'outline', and section for partial reads. This is model-grade usage direction.

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

Deploy Server

Convert a local file to markdown

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools