Two tools with clear, domain-specific descriptions (audit_mcp_repository: 227 chars, audit_local_directory: 108 chars). Both have input schemas with type definitions and descriptions. However, output schemas are not documented in the source code, the tools return Dict[str, Any] with no structured schema visible. Error handling returns status/message but lacks actionable recovery guidance. Parameter descriptions are adequate but minimal. No tool annotations (readOnlyHint, destructiveHint) despite both being read-only operations.

• Document output schema explicitly. Define the structure of scan_result.to_dict(), include fields like trust_score (int 0-100), grade (str A-F), findings (list of {rule_id, title, severity, cwe_id, file_path, line_number, snippet, description, remediation, confidence}), and markdown_report (str). This enables LLMs to extract and reason about findings.
• Enhance error responses with recovery guidance. Instead of {'status': 'error', 'message': str(e)}, return {'status': 'error', 'message': '...', 'recovery': 'Verify repository URL is public and accessible. Try a different repo or check network connectivity.'}. Categorize as retryable vs fatal.
• Add readOnlyHint annotation to both tools. Register with @server.tool(..., readOnlyHint=True) to signal these are safe to retry and cache. Helps agents optimize execution.
• Clarify sub_directory parameter format. Update description to: 'Optional subdirectory within the repository to audit (relative path, e.g. "src/mcp_server"). If omitted, audits repository root.'
• Add result limits and filtering. Document: 'Returns up to 100 findings. High-severity findings listed first. Use markdown_report field for human-readable summary.' Consider adding a max_findings parameter to cap results.