This MCP server has a single tool 'write_documentation' with severe quality gaps. The tool has a name that follows verb_noun convention (positive), but the description is superficial (only 82 characters, below the 10-1024 baseline), the input schema is missing critical context and constraints, and there is no documented output schema. The source code shows a naive regex-based parser with no error handling, validation, or recovery guidance. The implementation lacks any of the 54 production patterns and does not align with MCP best practices.

• Document the complete output schema. Define the structure of the returned markdown: e.g., { type: 'object', properties: { markdown: { type: 'string', description: 'Formatted markdown documentation' }, parsed_classes: { type: 'array', items: { type: 'string' } }, parsed_methods: { type: 'array', items: { type: 'string' } }, errors: { type: 'array' } } }.
• Expand the tool description to 150-250 characters. Include: (1) What it does: 'Generates API reference markdown by parsing Python source code for classes and methods.'; (2) When to use it: 'Call this to auto-generate documentation from unformatted Python source files.'; (3) What it returns: 'Structured markdown with class definitions, method signatures, and extracted docstrings.'; (4) Constraints: 'Requires valid or near-valid Python syntax; handles common patterns but not advanced metaprogramming.'
• Add validation constraints to the 'source_code' parameter schema: { type: 'string', minLength: 10, maxLength: 100000, description: 'Python source code to parse. Should contain valid or near-valid Python syntax with class and function definitions. Does not require full module imports or executability.' }.
• Implement proper Python AST parsing instead of regex. Use the ast module to safely and accurately parse classes, functions, parameters, return types, and docstrings. Graceful fallback to regex if AST parsing fails.
• Add error handling with recovery guidance. Return errors like: { error: 'SyntaxError in source_code at line 5', suggestion: 'Check for unclosed strings, brackets, or invalid indentation. The parser expects valid Python syntax.', fallback: 'Try simplifying the code by removing advanced features like decorators or type hints.' }.