doc2md

convert_pdf_to_markdown

Read-onlyIdempotent

Convert a PDF document to clean Markdown, preserving headings, tables, lists, and reading order. Accepts a URL or base64, with options for page selection and large document handling.

Instructions

Convert a PDF document to clean Markdown, preserving headings, tables, lists and reading order. Use this whenever an agent needs to read a PDF: reports, papers, invoices, manuals, slide exports. Accepts a public URL or base64 content; no API key needed.

For large PDFs, convert selected pages ('pages': '1,3-5') or page through
the output with 'offset'/'max_chars'. Scanned PDFs are rejected with a
hint to use ocr_document instead.

Input Schema

TableJSON Schema

Name	Required	Description
`url`	No	Public http(s) URL of the document to fetch and convert. Leave empty when passing file_base64 instead.
`pages`	No	1-based page selection like '1,3-5'. Empty means all pages.
`offset`	No	Character offset to resume a truncated conversion (from a previous response footer).
`filename`	No	Original filename with extension (e.g. 'report.docx'). Used as a format hint when content type cannot be detected automatically.
`password`	No	Password for encrypted PDFs. Empty for normal files.
`max_chars`	No	Maximum characters to return (default 40000, max 200000).
`file_base64`	No	Base64-encoded file content (for documents not reachable by URL). Decoded size limit: 30 MB. Leave empty when passing url instead.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.0Sep 22, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds genuinely new behavioral context: no API key is needed, scanned PDFs fail and route to a sibling, and large outputs can be paged via offset/max_chars or limited via pages selection.

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?

Two tight paragraphs with the core purpose front-loaded in the first sentence. Every sentence carries information: input modes, auth status, paging strategy, and the scanned-PDF fallback. No filler or repetition of schema contents.

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 7 optional parameters, full schema coverage, and an output schema, the description covers everything an agent needs: purpose, when to use it, input formats, auth requirements, large-file strategy, and the failure mode with an alternative. The output schema handles return-value explanation, so no gap remains.

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% with detailed parameter descriptions (defaults, 200000 max chars, 30 MB base64 limit, 1-based page syntax), so the baseline is 3. The description adds value above that by linking parameters into a coherent strategy — passing 'pages': '1,3-5' for selective conversion and combining 'offset'/'max_chars' to page through output — which the bare schema entries do not convey.

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 ('Convert a PDF document to clean Markdown') with concrete output-quality guarantees (headings, tables, lists, reading order). It also carves out its niche among siblings by framing usage as 'whenever an agent needs to *read* a PDF' and explicitly routing scanned PDFs to ocr_document.

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?

Gives an explicit when-to-use rule ('Use this whenever an agent needs to *read* a PDF: reports, papers, invoices, manuals, slide exports') and an explicit exclusion with a named alternative ('Scanned PDFs are rejected with a hint to use ocr_document instead'). The paging guidance for large PDFs further clarifies how to use the tool under heavy load.

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

Deploy Server