mcp-discovery defines 4 tools with reasonable action-verb naming and descriptions. However, there are significant structural issues: (1) two tools (discover_mcp_server and mcp_discovery) appear to be near-duplicates with different parameter names ('need' vs 'query'), creating ambiguity for LLMs; (2) parameter schemas are present and well-typed, but descriptions lack depth on when/why to use each tool and what downstream composition looks like; (3) output structure is inferred from code but not formally documented in schemas; (4) error handling exists (timeout/exception catching in Python tool) but lacks actionable recovery guidance; (5) the get_server_metrics and compare_servers tools lack detailed descriptions of their return structures. Overall, the server shows competent tool design but falls short of production-grade clarity on tool composition, error recovery, and output contracts.

• Consolidate discover_mcp_server and mcp_discovery into a single tool with a canonical name (e.g., discover_mcp_servers) and parameter name (query). Remove the duplicate.
• Formally document the output schema for all tools. For discover_mcp_servers, document that results are an array of {name, description, trust_score, install_command, category, metrics: {uptime_pct, avg_latency_ms}, github_url, is_verified}. Include limits (max 20 results) in the schema.
• Expand get_server_metrics and compare_servers descriptions to explain when to call them (after discovery to evaluate options) and what structure they return (e.g., time-series metrics, comparison matrix). Link them to discover_mcp_servers.
• Add error recovery guidance: 'If no servers found, try: (1) broader search terms (e.g., "database" instead of "PostgreSQL"), (2) force_refresh=true to get latest index, or (3) compare_servers() on known alternatives.'
• Document the cost/benefit of force_refresh: 'Set to true to fetch latest results (~500ms latency). Use false (default) for faster, cached responses unless you need real-time availability data.'
• Add a parameter dependency note in compare_servers: 'server_ids should come from a prior discover_mcp_servers call; passing invalid IDs will return no comparisons.'
• Consider adding a list_available_metrics tool that documents what metrics are tracked (uptime_pct, avg_latency_ms, etc.) and their definitions, reducing ambiguity in filter/compare operations.