mcp-pdf demonstrates solid tool design with 8 well-named, verb-prefixed tools (pdf_info, pdf_merge, pdf_split, pdf_rotate, pdf_reorder, pdf_stamp, pdf_text, pdf_history). All tools have clear, substantive descriptions (100-200 chars typical) explaining what they do and when to use them. Input schemas are present and typed for all tools. However, output schemas are not documented, LLMs cannot predict return structure. Error handling is present but generic (fail() helper returns plain text errors without recovery guidance). Parameter descriptions are good but lack explicit constraints (e.g., pdf_stamp's font_size is clamped 1 - 1600 but not stated in the description; degrees param in pdf_rotate lacks enum constraint). The tool set is well-composed (each does one thing) and idempotent (safe to retry). Free-tier limits are documented in descriptions, which is helpful for agent planning.

• Document output schemas for all tools. E.g., pdf_info should return {page_count: number, page_sizes: [{width: number, height: number, unit: string}], metadata: {title?: string, author?: string, ...}, encrypted: boolean}. This enables LLMs to chain tools and extract the right fields.
• Add enum constraints to parameter descriptions. For pdf_rotate, change 'Rotation in degrees: 90, 180, 270, or -90, -180, -270' to explicitly state 'Must be one of: 90, 180, 270, -90, -180, -270'. For pdf_stamp color, list all valid names: 'One of: red, green, blue, black, gray, orange, purple, white, or a hex code (#1b7f3b or #f00).'
• Enhance error messages with recovery guidance. Instead of fail('File not found'), return fail('File not found at "<path>". Check the path or call pdf_info to verify the file exists.'). This guides agents to self-correct.
• Clarify page range syntax in descriptions. Add: 'Page ranges use 1-based indexing. Examples: "1" (page 1), "1-3" (pages 1 - 3), "1-3,5,7-" (pages 1 - 3, 5, 7 to end), "-4" (first 4 pages).'
• Add a discovery tool or enhance pdf_history. Consider a pdf_list tool that returns available PDFs in the working directory with file sizes and page counts. This helps agents discover files without trial-and-error.