SymptomAI MCP suffers from critical gaps across all definition quality dimensions. While the 4 tools are explicitly registered via @mcp.tool() decorators in server.py, their schemas, descriptions, and parameter documentation fall significantly short of production standards. Tool names lack clear action verbs (extract_symptoms, extract_details, match_diseases, get_advice are acceptable but generic). Descriptions exist but are minimal (10-40 chars) and fail to explain WHEN to use each tool or clarify dependencies between them. Input schemas are present but severely underdeveloped: parameters are typed as simple strings without enums, min/max bounds, or format guidance. Most critically, no output schemas are documented, LLMs cannot plan downstream tool chains when return types are unspecified. Error handling is absent: tools return raw text or exceptions with no recovery guidance. The sequential dependency chain (symptoms → details → diseases → advice) is implicit in client.py but entirely undocumented in tool definitions, forcing agents to infer the workflow rather than having it declared. This is a proof-of-concept implementation that requires substantial hardening before production use.

• Define output schemas for all 4 tools. Example for extract_symptoms: return { symptoms: string[], confidence: string[], source: string } instead of bare text. Document these in tool descriptions and via JSON Schema in server.py.
• Expand tool descriptions to 50-200 characters, explaining WHAT, WHEN, and WHY. Example: 'Extract distinct medical symptoms from user freetext. Call this first before match_diseases. Returns a list of symptom names (e.g., "fever, cough, fatigue").'
• Add enums and constraints to parameters. For match_diseases, specify: symptoms format as 'comma-separated lowercase phrases' and details as 'comma-separated contextual factors (e.g., travel, stress, medication)'. Add min/max examples (e.g., 1-20 symptoms per call).
• Implement explicit error handling with recovery guidance. Example: if search_tool.invoke() times out, return { error: 'Retrieval service unavailable', retry_after: 30, fallback: 'Using cached knowledge. May be incomplete.' }. Guide LLMs to retry or use fallback.
• Document the tool workflow in each tool's description. Add: 'Prerequisite: Call extract_symptoms and extract_details first. Pass their results to match_diseases. Then call get_advice with the disease list.' This makes multi-tool chaining explicit.
• Implement secure secret injection. Load GOOGLE_API_KEY and TAVILY_API_KEY from environment variables at startup, with clear error messages if missing. Never hardcode placeholder strings.
• Add pagination and limits. If match_diseases returns many diseases or get_advice returns lengthy guidance, cap at 5-10 results per tool and offer pagination. State limits in descriptions.