Paperboy

Official

Overview Schema Source Related Servers Discussions Admin

pdf_to_markdown

Read-onlyIdempotent

Convert PDFs into structured Markdown, preserving headings, lists, tables, and reading order so models can reliably read and analyze document content.

Instructions

Read a PDF's text as Markdown, keeping its structure for a model to read: headings (#, ##, ### from font sizes larger than the body text; a short bold line on its own becomes the next level down), bulleted and numbered lists, paragraphs (lines joined, words hyphenated at line breaks mended), and tables as Markdown tables (unless include_tables=false). Text is read in reading order, following columns. On all pages or a page spec (e.g. "1-3,7"); page_markers adds "" before each page.

Text from the PDF is escaped, so it can't add hidden links, pictures, HTML or formatting (a web address written out in it stays as written, and some viewers show it as a link); only the unescaped "" lines are page markers, and invisible characters are removed. Structure is inferred from the layout, so check headings and lists that matter (with view_pages). Returns up to max_chars (1-1,000,000) characters, cut at the end of a block (or within one too long to fit); truncated means there is more (export_markdown saves up to 4 million characters). Pages with no text (e.g. scans; ocr_pdf makes them readable) are listed in pages_without_text; pages that can't be read safely in pages_skipped, with the reason; complete is false if the 60 s limit per call stopped it before every page was read. Needs the owner password if the PDF forbids copying.

Any password argument can be "ask": the user then types it on a local page, so it never passes through the chat.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "input_path": "<input_path>"
    },
    "name": "pdf_to_markdown"
  }
}

Input Schema

Name	Required	Description	Default
`pages`	No
`password`	No
`max_chars`	No
`input_path`	Yes
`page_markers`	No
`include_tables`	No

Output Schema

Name	Required	Description	Default
`path`	Yes
`tables`	Yes
`complete`	Yes
`headings`	Yes
`markdown`	Yes
`truncated`	Yes
`characters`	Yes
`pages_read`	Yes
`pages_skipped`	Yes
`pages_without_text`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.1.1Nov 12, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Beyond the readOnly/idempotent annotations, it discloses escaping behavior and its side effects, page-marker conventions, invisible-character removal, truncation semantics, a 60-second per-call limit with a 'complete' flag, owner-password requirements for copy-restricted PDFs, and the 'ask' password flow. These are exactly the operational traits an agent cannot infer from annotations or schema.

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

Conciseness3/5

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

Purpose is front-loaded and nearly every clause carries real information, but the body is a dense wall of nested parentheticals and semicolon-chained rules that is harder to scan than it needs to be. Splitting the return/limit/password material into short lines would cost no information.

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 six-parameter, behavior-heavy conversion tool, the description covers inputs, structural inference caveats, failure modes, truncation, timeouts, and security constraints. An output schema exists, and the description still names the key return fields (pages_without_text, pages_skipped, truncated, complete) so the agent knows what to check.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden and does: it gives a page-spec example ('1-3,7'), explains page_markers' emitted marker text, states the include_tables=false behavior, gives the max_chars range (1–1,000,000) and default truncation point, and explains the password and 'ask' semantics. Only input_path goes unmentioned, which is self-evident.

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 opening sentence gives a specific verb and resource ('Read a PDF's text as Markdown') and immediately scopes what is preserved — headings, lists, paragraphs, tables — so an agent can distinguish this from a plain text extractor. Later clauses reinforce the identity by naming related tools (view_pages, export_markdown, ocr_pdf) for adjacent jobs.

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?

The description clearly routes several cases: use view_pages to verify inferred structure, use ocr_pdf for scanned pages listed in pages_without_text, and use export_markdown when more than the max_chars ceiling is needed. It does not, however, explicitly contrast with extract_text or export_tables, so the alternative-selection guidance is strong but not exhaustive.

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