Compai MCP server has 11 tools with basic schemas and descriptions, but significant gaps prevent production readiness. Tool names lack consistent verb-noun structure (brain_query, brain_read, brain_write are good; status, me_read, me_write are weak). Descriptions are present but brief (avg ~60 chars, below 194-char baseline). Parameter descriptions are sparse or missing entirely. No output schemas documented. Error handling and recovery guidance absent. Security-critical tools (brain_write, slack_send_message) lack explicit permission documentation. No evidence of input validation or actionable error messages.

• Add output schemas to all tools. Document the structure of brain_query results (e.g., [{id, path, score, content}, ...]), status response (e.g., {ok, integrations, services, brain_stats}), and integration query results. This enables LLMs to plan multi-step workflows.
• Expand parameter descriptions with constraints and examples. E.g., 'max_results: integer, 1 - 100, default 10. Limits the number of search results returned.' For shopify_query, explain the resource format: 'Shopify Admin API resource path, e.g., orders.json?status=any&limit=5'.
• Rename weak tools: 'status' → 'get_health_status', 'me_read' → 'read_profile', 'me_write' → 'write_profile'. Use consistent verb_noun naming across all 11 tools.
• Add error handling guidance to tool descriptions. E.g., brain_write: 'Returns 403 if caller lacks admin role. Retry with a team-role account or request admin elevation.' slack_send_message: 'Returns 400 if channel not found. Call list_channels first to verify the channel exists.'
• Document permission requirements explicitly. Add a 'permissions' field or note to brain_write, me_write, and slack_send_message: 'Requires: admin role' or 'Requires: write:slack scope'. This clarifies least-privilege configuration.