MCP server for reading PDFs as LLM-friendly markdown
Server has 5 well-named tools with complete input schemas and mostly good descriptions. Naming follows verb_noun conventions (read_pdf, get_pdf_metadata, extract_images, create_pdf, detect_pdf_type). All tools have descriptions in the 68-200 character range. However, descriptions lack actionable guidance (when to use each tool, dependencies between them, what to expect in output). No output schemas are documented, LLMs cannot know what fields to expect in responses. Error handling exists but is generic ('Error: {str(e)}') without recovery guidance. Most critically, no tool annotations (readOnlyHint/destructiveHint) despite clear read/write semantics, create_pdf is destructive but unmarked. The tools lack composition guidance (e.g., detect_pdf_type should suggest calling read_pdf afterward for text-based PDFs). Parameter descriptions are present but could be more specific about constraints (e.g., page_chunks default behavior, max_images reasoning).
Creates a PDF document from HTML content using WeasyPrint. Supports custom CSS styling. Use this for generating reports or documents.
Analyzes a PDF to determine if it's text-based, scanned, or mixed. Returns the text ratio and whether images are present. Use this to understand the PDF content structure.
Extracts images embedded in a PDF document as base64-encoded strings. Use this when you need to analyze or save images from a PDF.
Returns detailed metadata about a PDF file including page count, word count, file size, author, and whether it contains text or images. Use this to understand a PDF before processing.
Extracts text content from a text-based PDF document and returns it as markdown. Use this tool when the PDF contains selectable text (not scanned images). Supports page filtering and chunked output for large documents.
No documented output schemas. LLMs cannot see what fields the tools return (e.g., what structure does read_pdf output? What fields are in get_pdf_metadata's response?). Forces LLMs to guess at response structure and plan downstream calls blindly.
Missing tool annotations (readOnlyHint, destructiveHint). create_pdf is a write operation but not marked; read_pdf is read-only but not annotated. Without these, agents cannot distinguish safe vs. unsafe tools and may misplan retry logic.
Error handling is generic ('Error: {str(e)}') with no recovery guidance. When a PDF file is not found, the LLM gets no suggestion to check paths or list available files. When create_pdf fails due to invalid HTML, no hint about what went wrong.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 57 | <=2025-11-25 | v2 |
| 2026-03-09 | F | 47 | - | v1 |
Descriptions lack WHEN-to-use guidance and composition hints. E.g., 'detect_pdf_type' does not suggest 'Call this first to determine if read_pdf or extract_images is appropriate.' LLMs must infer the workflow rather than follow explicit direction.
Parameter 'pages' in read_pdf and extract_images accepts an array of integers (0-indexed) but lacks min/max constraints. Can an agent pass pages=[0, 1, 1000000]? Unbounded numeric arrays risk out-of-range errors with no validation message.
create_pdf's 'output_path' parameter is optional with a default behavior ('returns base64-encoded PDF') but the description does not clearly state what happens if output_path is omitted. Does the base64 get returned as the response text? Is it truncated? Unclear.