The server implements three tools with complete JSON Schema validation via Zod. Tool naming follows verb_noun convention (convert_*, capture_*) appropriately. All tools have descriptions and comprehensive parameter schemas with type definitions, enums, and defaults. However, descriptions are generic and lack LLM-optimized guidance on WHEN to use each tool and WHAT differentiates them. Output schemas are not documented in the code. Error handling exists at the validation layer but recovery guidance is minimal. The tools themselves are well-structured and compose logically, but descriptions miss opportunities to guide agent decision-making per pattern:tool-description and pattern:response-shaper.
Tool descriptions lack LLM-optimized guidance on WHEN to use each tool and how they differ. 'Convert HTML file to image' is passive and does not explain prerequisites, use cases, or constraints that guide agent selection. Per pattern:tool-description, descriptions should state WHAT, WHEN, and WHY.
Output schemas are not documented in tool definitions or code comments. LLMs cannot plan downstream actions or extract correct fields without knowing the response structure. Per pattern:response-shaper, tool responses should be documented with field types and meanings.
Three tools (convert_html_file, convert_html_content, capture_screenshot) share nearly identical parameter sets, making it ambiguous which tool an agent should select. Per pattern:tool, each tool should do exactly one thing with a clear, distinguishing purpose. The distinction between 'convert from file' vs 'convert from string' vs 'capture from URL' needs explicit guidance.
Recommendations
Rewrite tool descriptions to follow the pattern:tool-description format: (1) what does it do in one sentence, (2) when should the agent use THIS tool instead of the other two, (3) what does it return, (4) any prerequisites or side effects. Example: 'Convert an HTML file on disk to a PNG/JPEG/WebP image. Use this when you have a .html file path (e.g., from file upload or local filesystem). Returns the file path and dimensions of the saved image. Note: requires file read permission and Puppeteer browser access.'
Document output schemas for all three tools. Include a comment block or inline JSDoc showing the return type structure. Example: 'Returns { success: boolean, outputPath: string (absolute file path), size: number (bytes), format: string, fileUri: string (file:// URI for MCP clients) }'.
Add parameter descriptions that explain conditional behavior. Example for 'quality': 'Image quality 0-100. Only applies to JPEG format (PNG and WebP ignore this parameter). Default: 80 for JPEG; omitted for other formats.'
Add guidance to distinguish the three tools. Create a summary comment at the top of the tool definitions explaining: convert_html_file handles local .html files; convert_html_content handles inline HTML strings (for dynamic content); capture_screenshot handles live URLs and supports auth/headers. This guides agent selection.
Remove 'auth.username' and 'auth.password' parameters and replace with a server-side environment variable or vault-based approach. Document in the README how to configure HTTP Basic Auth credentials without passing them as tool parameters.
Error handling returns Zod validation errors but does not provide recovery guidance. Per pattern:recovery-guide, errors should tell the LLM what to do next (e.g., 'HTML path must be an absolute path to an existing file. Did you mean /home/user/index.html?'). Raw validation errors are not actionable.
Parameter descriptions are technical but lack context. E.g., 'Image quality 0-100 (default: 80)' does not explain when quality matters (JPEG) vs when it is ignored (PNG). Per pattern:tool-description, parameter descriptions should include constraints, format hints, and conditional applicability.
The 'headers' and 'auth' parameters in capture_screenshot are not validated or sanitized. Per pattern:secret-injection, credentials must never be exposed in tool parameters, use server-side secret injection instead. Passing auth.username and auth.password as parameters risks logging them in agent traces.
capture_screenshot
Enhance error messages with recovery hints. When htmlPath is invalid, return: 'HTML file not found at /path/to/file.html. Verify the path exists and is readable. Available files in ./generated-images: [list]'.
Add per-tool use-case examples in descriptions (without literal example values). Example: 'Use convert_html_file to render a locally stored invoice template. Use convert_html_content when an agent dynamically generates HTML from template data. Use capture_screenshot for live web pages that require JavaScript execution.'
Document timeout and resource limits in tool descriptions. Example: 'Rendering times out after 30 seconds if the page does not reach the specified wait condition (load, networkidle2, etc.). Pages exceeding 10MB size are rejected. Set width/height to constrain viewport size.'
Add 'fullPage' parameter documentation clarifying the impact: 'When true, captures the entire page height even if it exceeds the viewport. Can produce very tall images if the page is long, consider setting a reasonable viewport height to avoid excessive file sizes.'
Standardize enum descriptions. Example: 'waitUntil: Wait condition before capturing. load = page.onload event fired; domcontentloaded = DOM fully parsed; networkidle0 = no network activity for 500ms; networkidle2 = at most 2 active connections. Default: networkidle2 (safest for dynamic pages).'
Add a 'dry-run' or 'validate-only' mode so agents can test rendering without writing files, reducing side effects and enabling safer planning per pattern:confirmation-request.