Single tool with well-structured schema and comprehensive description. Tool name 'convert_to_markdown' follows verb_noun pattern. Input schema properly typed with descriptions. Output schema (ConvertResult) is fully documented with 10 typed fields. Description is detailed (450+ chars) and explains token-thrift design, caching behavior, and usage patterns. Tool annotations present (read_only_hint, idempotent_hint, open_world_hint). Main gaps: no enum constraints on 'source' parameter (accepts any string), no explicit error recovery guidance in description, and parameter descriptions could be more prescriptive about format/constraints.

• Add format constraints to 'source' parameter: 'Local file path (absolute or ~-relative, max 4096 chars) or http(s) URL (RFC 3986, max 2048 chars). Paths are checked for existence and allowed directories; URLs are fetched with standard HTTP client.'
• Expand error handling in description: 'Raises ToolError if: file not found, not a file, path outside allowed directories, unsupported format, network timeout (>30s), or conversion fails. Check the error message for recovery hints (e.g., try force=true to bypass cache).'
• Document outline truncation limit: 'The outline list is capped at 100 headings for large documents. If outline_truncated is true, use grep or read specific line ranges to find additional sections.'
• Add dependency hint for multi-step workflows: 'After conversion, use your file-reading tool to fetch specific sections by line number from the returned path. This avoids loading the entire document into context.'
• Clarify cache behavior: 'Repeated calls with the same source return cached results instantly (no reconversion cost). Pass force=true to ignore cache and reconvert. Cache is stored in ~/.cache/mdconvertor/ by default.'