WhatsApp MCP has 5 tools with basic schemas and descriptions, but significant gaps prevent higher scores. All tools have descriptions (10 - 200 chars, within baseline range), and input schemas are present with type definitions. However, parameter descriptions are sparse or missing context. get_status and get_health lack parameters entirely (minimal complexity). send_whatsapp_message and get_messages have required params but descriptions lack format constraints, validation rules, and error recovery guidance. Output schemas are not documented, LLMs cannot infer response structure. No tool annotations (readOnlyHint/destructiveHint) despite clear risk profiles. Error handling is minimal: tools return generic 503/400 responses without actionable recovery steps. Naming is verb-first and clear (get_, send_), but descriptions do not explain WHEN to use each tool or dependencies (e.g., get_chats before get_messages). No pagination guidance despite limit params. Composition is reasonable (5 focused tools), but missing idempotency guarantees and output field documentation.

• Add formal output schema documentation for each tool. Example: get_chats returns {success: boolean, tool: string, count: number, data: [{id: string, name: string, isGroup: boolean, unreadCount: number, timestamp: string|null, lastMessage: string|null}]}. Include this in tool description or as a separate schema field.
• Enhance parameter descriptions with format constraints and examples. For 'to' in send_whatsapp_message: 'Phone number with country code, no + sign (e.g., 919876543210 for India, 1-10 digits after country code). Or group ID ending in @g.us (e.g., [email protected]).' For 'chatId': 'Chat ID in format [email protected] (individual) or [email protected] (group).'
• Add tool annotations to all tools. Mark send_whatsapp_message with destructiveHint=true. Mark get_* tools with readOnlyHint=true. Mark all tools with idempotentHint=true if they are safe to retry (get_* are; send_* is not).
• Improve error messages with actionable recovery steps. Instead of '503 WhatsApp client is not ready', return 'WhatsApp client not ready. Call get_status to check connection, or scan QR code at /auth/qr if needed.' For invalid 'to' format: 'Invalid phone number format. Expected: country code + number (e.g., 919876543210) or group ID (e.g., [email protected]).'
• Add pagination metadata to list responses. Include 'total_count' or 'has_more' in get_chats and get_messages responses. Document in descriptions: 'Returns up to [limit] chats. Use limit and offset for pagination.' Provide next_cursor if using cursor-based pagination.