Single tool with acceptable naming and basic schema, but critical deficiencies in description completeness, parameter documentation, and error handling. The tool description mentions 'AI sampling' but the implementation uses pymupdf4llm directly, not MCP sampling. Missing output schema documentation, no parameter descriptions, no error recovery guidance. Per-tool analysis: convert_pdf_to_markdown scores 38/100 overall due to incomplete parameter annotations and vague descriptions that don't guide LLM behavior.
Tools (1)
convert_pdf_to_markdownwritesource verified38/100
Convert a PDF file to Markdown format using AI sampling.
Args:
file_path: Local file path or URL to the PDF file
output_dir: Optional output directory. Defaults to same directory as input file
(for local files) or current working directory (for URLs)
Returns:
Dictionary containing:
- output_file: Path to the generated markdown file
- summary: Summary of the conversion task
- pages_processed: Number of pages processed
Output schema undocumented. Tool returns Dict[str, Any] with fields 'output_file', 'summary', 'pages_processed', but no formal schema definition. LLMs cannot plan downstream tool calls or extract data reliably from unstructured returns.
Parameter 'output_dir' lacks description. Docstring mentions it's optional with defaults, but the formal parameter schema has no description field to guide LLM.
Error handling is reactive, not prescriptive. Tool returns error dict with 'error', 'output_file', 'summary', 'pages_processed' fields on failure, but provides no recovery guidance. E.g., 'File not found: /path/to/file' does not tell the LLM what to do next (ask user for valid path? search for file?).
convert_pdf_to_markdown
Recommendations
Add formal output schema: document that the return is a dict with keys output_file (string), summary (string), pages_processed (int), and error (optional string). Example: {"output_file": "...", "summary": "...", "pages_processed": 10}. This enables LLMs to plan extraction of fields.
Expand parameter descriptions in the fastmcp tool decorator. For 'file_path', add: 'Local file path (e.g. /home/user/doc.pdf) or HTTP(S) URL (e.g. https://example.com/doc.pdf). Must be a valid PDF file.' For 'output_dir', add: 'Directory to write the markdown file. Defaults to the same directory as the input PDF for local files, or current working directory for URLs. Must be writable.'
Add error recovery guidance in the tool description. Change 'Convert a PDF file to Markdown' to 'Convert a PDF file to Markdown format. On success, returns the path to the generated markdown file. If the file is not found, ask the user to verify the path. If the PDF is corrupted or unsupported, suggest trying a different file or checking that the PDF is valid.'
Correct the misleading claim about 'AI sampling'. The tool does not use MCP sampling; it uses pymupdf4llm's built-in extraction. Update description to: 'Convert a PDF file to Markdown format using pymupdf4llm. Supports local files and URLs. Returns the path to the generated markdown file, a summary of the conversion, and the number of pages processed.'
Implement path validation: use pathlib.Path.resolve() to normalize paths and check for traversal attempts. Reject paths outside a safe base directory. Example: if output_dir is provided, verify it's a subdirectory of a safe base (e.g. /tmp/pdf2md/), or reject with a clear error.
Tool description claims 'using AI sampling' but implementation directly calls pymupdf4llm.to_markdown(), not MCP sampling. Description is misleading about internal behavior. State WHAT the tool does, WHEN to use it, and any prerequisites.'
File path traversal and injection risk. Tool accepts 'file_path' and 'output_dir' with no validation. An LLM could be tricked into writing to or reading from arbitrary paths. No sanitization against path traversal attacks like '../../../etc/passwd'. Sanitize against SQL injection, command injection, and path traversal.'
No timeout protection. Tool downloads PDFs from URLs and extracts markdown without explicit timeout. An agent could get stuck on slow/hung responses. An agent stuck waiting on a hung API call blocks the entire plan.'
Parameter 'file_path' description is inline in docstring but missing from schema. Schema shows only type and description text, but 'file_path' parameter has no formal description field in the JSON input definition. LLMs will not see guidance about valid formats (local vs URL).
convert_pdf_to_markdown
Add explicit timeout to httpx.AsyncClient().get(url) call. Set timeout=30 seconds. On timeout, return error: 'Download timed out after 30 seconds. The URL may be slow or unreachable. Please check the URL and try again, or use a local PDF file.'
Implement pagination for large PDFs. Add optional parameters: page_start (default 1) and page_end (default all). Document in the tool description: 'For large PDFs, process a page range by setting page_start and page_end. E.g., page_start=1, page_end=10 processes only the first 10 pages. Returns pages_processed count in response.'
Wrap the pymupdf4llm extraction in a try-except with specific error types. For each error (file not found, corrupted PDF, unsupported format), return a targeted error message with recovery steps. Example: 'PDF is corrupted. The file may be damaged or encrypted. Try re-downloading the file or using a different PDF.'
Add dry-run or preview mode. Since the tool has a WRITE risk, add an optional 'dry_run' parameter (default false). If true, return what would be written without creating the file. This lets agents preview changes before committing.