The open-code-review MCP server provides 4 tools with clear names and reasonable descriptions, but suffers from incomplete input schemas, missing output schema documentation, and insufficient parameter descriptions. Tool names follow verb-noun conventions (scan_*, explain_*, heal_*), which is good. However, parameter documentation is sparse, many parameters lack descriptions or have generic/incomplete guidance. The schema visibility is partial: input schemas are shown for some tools but output schemas are not documented anywhere in the provided source. Error handling and recovery guidance are absent. The tooling is domain-specific (code review) and well-motivated, but the interface lacks the rigor expected of production-grade agent tools.

• Document output schemas for all four tools. Specify field names, types, and structure. Example for scan_directory: {type: 'object', properties: {issues: [issue_object], stats: {total_issues, critical_count, ...}, scanned_files: number}}
• Convert free-form 'severity' in explain_issue to an enum: ['critical', 'high', 'medium', 'low', 'info']. Add validation on the server side and return 'Invalid severity' error with allowed values.
• Clarify the 'level' parameter across scan_* tools with detailed descriptions: 'L1: Fast structural checks only (no network calls). L2: Local AST + AI embeddings (may call local Ollama). L3: Deep analysis with remote API calls (slower, higher cost).'
• Add pagination or result limits to scan_directory and scan_diff. Document: 'Returns up to 100 issues. Use cursor-based pagination for large scans.' Include a next_cursor or has_more field in output.
• For heal_code, clarify the contract: Does it only load the file and return content + repair context, or does it actually apply the fix? If the latter, add an 'apply_fix' boolean parameter. Update description to be action-focused: 'Load a file and return its content with contextual repair guidance' or 'Apply a suggested fix to a file and return the updated content.'
• Add error handling guidance: Document what errors can occur (FileNotFound, PermissionDenied, InvalidBranchReference, SyntaxError) and whether they are retryable. Return structured errors with a 'code' and 'next_step' field: {code: 'INVALID_BRANCH', message: 'Branch origin/main not found', next_step: 'Check branch names with list_branches or verify remote is set up.'}