mcp-architect provides well-intentioned tooling for code analysis with generally clear descriptions and reasonable parameter schemas. However, there are systematic gaps in schema completeness, output documentation, and error handling patterns. All 5 tools are explicitly registered with @mcp.tool() decorators and have docstrings. Tool naming is verb-forward and clear (architecture_overview, dependency_graph, impact_analysis, hotspots, explain). Descriptions range from 104-174 characters, which is within the production baseline (p10=34, p90=392). All parameters have descriptions. The critical weakness: NO input schemas are visible in the source code, only docstring arg documentation. Tools return free-form markdown strings rather than structured JSON. Error responses are minimal (e.g., '❌ Not a directory: {root}') and do not guide recovery. No output schemas are documented. Per-tool scores: architecture_overview 65, dependency_graph 68, impact_analysis 70, hotspots 66, explain 69.

• Convert all tools to return structured JSON objects instead of markdown strings. Example: architecture_overview should return {total_files: int, total_code_loc: int, languages: [{language: string, files: int, loc: int}], ecosystems: [string], frameworks: [string], top_level_dirs: [string], entry_points: [string]} instead of a formatted markdown blob.
• Add explicit JSON Schema definitions via @mcp.tool() decorator or register_tool_schema(). Verify that FastMCP is auto-generating schemas from type hints (if so, document this assumption; if not, add explicit schemas).
• Document output schemas for each tool in the tool description or via a separate schema registry. Pattern:tool requires documented return types.
• Improve error handling with actionable guidance. Replace '❌ Couldn't find `target` in the import graph.' with 'Module or file not found: {target}. Call dependency_graph() to see available modules, or check that the path is correct (e.g., app/core/db.py or app.core.db).' Reference pattern:recovery-guide.
• Add enum constraints to the 'language' parameter in dependency_graph and impact_analysis. Change from free-form string default='auto' to explicit enum: ['auto', 'python', 'js', 'ts'].
• Add pagination parameters (limit, offset or cursor) to tools that return lists (dependency_graph, impact_analysis). Include total_count or next_cursor in responses. Cap default results at a reasonable limit (e.g., 50 modules, 30 importers).
• Enhance parameter descriptions with format constraints: 'path: Directory path to analyze (must exist, relative or absolute). Defaults to current working directory.' Instead of: 'Repo path to analyze.'