KolmoPDF MCP server has well-structured tool definitions with complete input schemas and descriptions. All 6 tools are explicitly registered with Zod schemas and descriptions. However, descriptions are generic and lack LLM-optimized guidance on WHEN to use each tool vs alternatives. Parameter descriptions exist but are minimal (avg ~40 chars vs baseline 72). Output schemas are not documented, LLMs cannot infer what fields to expect from responses. Error handling is present but generic. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite all tools being read-only. Missing guidance on multi-step workflows (e.g., parse → convert → check_balance chain).

• Add output schema documentation to each tool. Example for parse_pdf: 'Returns {task_id: string, status: "queued"|"processing"|"completed", markdown?: string, images?: {url: string, alt: string}[], tables?: {format: string, content: string}[]}'. This enables agents to plan downstream calls.
• Expand tool descriptions to 100-150 chars with WHEN guidance. E.g., 'Parse a PDF to extract text, tables, and images as Markdown. Use this first to understand document structure before translating or converting. Returns a task_id, call get_task_status to retrieve results.'
• Add readOnlyHint: true to all tool definitions in index.ts. Update registerTool calls to include annotations: {readOnlyHint: true} in the tool metadata.
• Document language code format in translate_pdf and estimate_cost descriptions. Specify: 'Target language code (ISO 639-1, e.g., "en", "fr", "de") or full name (e.g., "English", "French").'
• Add a 'Workflow' section to the README explaining the async pattern: 'Call parse_pdf → receive task_id → poll get_task_status until status=completed → retrieve markdown/images.' Include example task_id format and typical polling intervals.