CustomMCP has 9 tools with basic naming and descriptions, but critical gaps in schema documentation, parameter descriptions, and error handling. Tool names follow verb_noun convention (search_gmail, get_email_content), which is good. However, input schemas are inferred from the provided metadata rather than visible in actual code, no explicit JSON Schema definitions found in src/services/agent.py or src/api/mcp.py. Descriptions are present but generic (e.g., 'Search for emails in Gmail' is 26 chars, below the 50-200 char LLM-optimized baseline). Parameter descriptions exist but lack constraints: 'max_results' has no min/max bounds, 'state' in get_repo_issues lacks an enum, 'path' in get_repo_contents lacks format guidance. No output schemas documented. Error handling and recovery guidance absent. The process_query tool is particularly problematic, it conflates multiple concerns (understanding, routing, execution) into one tool, violating single-responsibility principle.

• Add explicit JSON Schema definitions to all tools in the MCP server registration. Include type, description, and constraints for every parameter. Example: 'max_results': {type: 'integer', description: 'Maximum results (1 - 100, default 10)', minimum: 1, maximum: 100}.
• Expand tool descriptions to 50 - 200 characters. Include WHAT the tool does, WHEN to use it, and any prerequisites. Example: 'Search Gmail for emails matching a query. Use this to find messages by sender, subject, or date. Returns email IDs and metadata; call get_email_content to retrieve full body.'
• Document output schemas for all tools. Specify field names, types, and which fields are required for chaining. Example: search_gmail returns [{email_id: string, from: string, subject: string, date: ISO8601}].
• Split process_query into separate tools: one for routing/understanding (optional, if needed), and rely on individual service tools (search_gmail, search_github_repos) for execution. This enables agents to compose and retry individual steps.
• Add error handling guidance to all tools. Return actionable errors: 'Gmail authentication failed. Check GMAIL_TOKEN env var.' instead of raw 500 errors. Include recovery suggestions and retryability classification.

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry