mdview MCP has 5 well-defined tools with complete input schemas and clear descriptions. All tools are read-only and low-risk. Naming follows verb_noun convention (render, export, convert, list, extract). Descriptions are substantive (100-200 chars), explaining what each tool does and when to use it. Input schemas include proper types, enums, and defaults. However, output schemas are not documented, LLMs cannot see what fields to expect from responses. Parameter descriptions are present but could be more prescriptive about constraints. No error handling guidance or recovery paths documented. Tool composition is sound (each does one thing), but lack of output documentation limits downstream chaining.

• Document output schemas for all 5 tools. Specify the structure of render() response (e.g., {html: string, metadata: object, headings: array}), export_mdv_html() response (e.g., {html: string, size: number}), convert_form() response, list_themes() response (e.g., {themes: [{id: string, name: string, description: string}]}), and extract_text() response. This enables LLMs to plan downstream calls and extract the right fields.
• Add error handling guidance to each tool description. E.g., render(): 'If markdown is malformed, returns an error with the line number and suggestion. If theme is invalid, returns available theme IDs.' This guides agent recovery without requiring trial-and-error.
• Tighten parameter constraints. For 'extensions' in render(), specify: 'Array of extension IDs. Built-in: mdv:color, mdv:callout, mdv:math, mdv:mermaid. Unknown extensions are silently ignored.' For 'html' in convert_form(), add: 'Must be a valid .mdv.html file with embedded markdown source. Returns error if markdown is missing or corrupted.'
• Expand list_themes() description to ~100 chars. E.g., 'List all available mdview themes. Returns theme ID, display name, and description for each. Use this to discover valid theme IDs before calling render() or export_mdv_html().'
• Consider adding a 'validate_markdown' tool that checks syntax without rendering, returning line-by-line error reports. This would help agents catch malformed input early and guide users toward valid markdown before expensive render calls.