PDF Card MCP has three well-named tools with complete input schemas and generally clear descriptions. Tool names follow verb_noun convention (convert_*, validate_*, publish_*) which is excellent. However, descriptions vary in quality: convert_pdf_to_card_html has a verbose, complex description (~420 chars) that buries key details; validate_reader_annotations and publish_reader_bundle have minimal descriptions (<80 chars each). All three tools have comprehensive input schemas with types, enums, and descriptions for most parameters. Output schema documentation is entirely missing, no tool documents what fields the response contains. Error handling guidance is absent; tools provide no recovery hints or categorization. Security considerations are present (file paths validated internally) but not explicitly documented. The server implements optional LLM sampling for style and post-processing but does not expose sampling as a formal MCP Sampling feature.

• Add explicit 'Returns' section to every tool docstring. For convert_pdf_to_card_html: specify that it returns {manifest: ConversionManifest, output_path: str, warnings: list[str], ...}. For validate_reader_annotations and publish_reader_bundle: document the response structure.
• Expand validate_reader_annotations description from 75 chars to 150-200 chars. Include: 'Validate that a JSON annotation sidecar (notes, highlights) matches a generated reader HTML file. Returns per-annotation validation results and highlights mismatches. Use this before publishing to catch annotation drift.'
• Expand publish_reader_bundle description similarly. Include: 'Bundle a reader with selected annotations into a static, distributable HTML file. Optionally redact source PDF paths and disable editing. Returns the path to the published bundle and a manifest of included annotations.'
• Refactor convert_pdf_to_card_html description: (1) Move 'the caveat about sampling constraints to the CONSTRAINTS subsection. (2) Replace prose with structured bullet points: '• WHAT: Converts local PDF to standalone HTML reader with embedded assets. • WHEN: Use to create portable, searchable documents with source verification. • OUTPUT: Standalone HTML file + manifest. • LIMITS: Tables/figures become images; sampling locked to validated tokens.'
• Add parameter-level error hints. For pdf_path, add: 'Path to input PDF (absolute or relative). If file not found or corrupted, check path and PDF validity before retrying.' For output_path, add: 'Directory must exist or parent directory must be writable; will error if write-protected.'