The MarkItDown MCP server defines 3 tools with adequate naming conventions but significant gaps in parameter descriptions and output schemas. Tool names follow verb-noun patterns (convert_*, list_*), which is positive. However, parameter descriptions are minimal or missing entirely for many inputs, and output schemas are not documented anywhere in the visible code. The descriptions for tools themselves are present but brief (under 100 chars each). The server implements basic input validation and error handling via custom exceptions, but lacks comprehensive documentation of error recovery paths.

• Document output schemas for all three tools. Example for convert_file: 'Returns {content: string, format: string, metadata: {file_type: string, page_count?: number}}'. Make this explicit in the tool definition or in code comments that are visible during registration.
• Expand parameter descriptions to 50-150 characters each. For 'output_format': 'Output format for converted content. markdown: preserves structure and formatting; json: returns structured metadata; html: embeds formatting in HTML tags. Defaults to markdown.'
• Add error handling documentation: 'If the file cannot be converted, returns error code UNSUPPORTED_FORMAT with message "File type .xyz is not supported. Supported types: pdf, docx, pptx, xlsx, ..." Retry after checking file type or use list_supported_formats to see available formats.'
• Clarify directory behavior: 'If output_directory does not exist, it will be created. If a file in the directory cannot be converted, it is skipped and a summary of skipped files is returned. If recursive=true and a subdirectory contains no convertible files, the subdirectory is omitted from results.'
• For convert_directory, add a 'filter' parameter (optional, enum: 'all', 'errors_only', 'summary') to control verbosity of the response, matching agent needs to either see all conversions or just failures.
• Add explicit timeout and file size limits to descriptions: 'Single file conversion times out after 30 seconds. Files larger than 100 MB may be rejected. Use convert_file for large batches sequentially rather than convert_directory with recursive=true on large directory trees.'