Architecture Drift MCP demonstrates solid tool design with consistent naming (verb_noun pattern), comprehensive parameter descriptions, and proper JSON Schema definitions. All 10 tools have clear, actionable descriptions (avg ~120 chars). Parameters are well-typed with constraints (minLength, arrays). Tool annotations (readOnlyHint/destructiveHint) are correctly applied. However, output schemas lack explicit documentation in descriptions, error handling is minimal (no recovery guidance or categorization), and some parameter relationships (e.g., use_sampling dependency on extract_claims) could be clearer. No security concerns detected (no secrets in params, proper path validation via ensure_project_root). Composition is sound, tools form a logical workflow (discover → extract → compare → adjudicate → report).

• Add explicit output schema documentation to each tool description. Example: 'Returns {audit_id: string, sources: [{path: string, kind: string, size_bytes: int}], ...}' so LLMs know what fields to expect.
• Wrap ValueError exceptions in try-catch blocks and return structured error responses with actionable recovery hints. E.g., '{"error": "No sources discovered", "next_step": "Call discover_sources(audit_id) first to scan the project."}' instead of raising.
• Document the use_sampling parameter dependency: 'Set to true only if the MCP host supports sampling; requires a live LLM connection. Defaults to false for deterministic extraction.'
• Add optional limit and offset parameters to discover_sources, extract_claims, and extract_facts. Return a total_count and next_offset to enable pagination for large projects.
• Implement a dry_run parameter (default false) for adjudicate_drift and propose_patches. When true, return proposed changes without persisting them, allowing the LLM to review before committing.