Two well-named, appropriately scoped tools with complete input schemas and reasonable descriptions. Both tools follow verb_noun naming (convert_*) and have clear action semantics. Input parameters are properly typed using Zod with descriptions. However, output schemas are not formally documented in the code, responses return structured text wrapped in MCP ContentBlock format, but no explicit schema definition is visible. Error handling is basic (isError flag + error text) without recovery guidance or categorization. Parameter descriptions are adequate but lack detail about constraints (e.g., what makes a valid URL beyond format:url). No tool annotations present (readOnlyHint, destructiveHint, idempotentHint). Tool descriptions could be more explicit about when to use each vs. the other.

• Document output schemas explicitly. Add a comment in index.js describing the return structure: 'Returns {content: [{type: "text", text: string}], isError?: boolean}'. Consider adding a JSDoc block for each tool handler.
• Enhance error handling with recovery guidance. Example: if URL fetch fails due to timeout, return 'URL fetch timed out after 30s. Try a different URL or check network connectivity.' For HTML conversion errors, suggest 'Ensure HTML is valid. Check for unclosed tags or unusual encodings.'
• Add parameter constraint descriptions. Update 'url' description to: 'URL to fetch and convert (http:// or https://, under 5MB when fetched, max 30s timeout)'. Update 'html' description to: 'Raw HTML to convert (up to 10MB, must be valid HTML5).'
• Clarify tool differentiation in descriptions. Update convert_url_to_markdown: 'Use this when you need to fetch a live webpage. For raw HTML you already have, use convert_html_to_markdown.' Update convert_html_to_markdown: 'Use this when you already have raw HTML. For live URLs, use convert_url_to_markdown.'
• Add tool annotations. Update both tool registrations to include readOnlyHint annotation (requires future SDK support or manual metadata). Example: 'This is a read-only operation, safe to retry idempotently.'
• Validate input early with actionable errors. Wrap convertUrl/convertHtml calls with try-catch blocks that return specific error messages. Example: if (!url.match(/^https?:\/\//)) return 'URL must start with http:// or https://'. If HTML is empty: return 'HTML content cannot be empty'.