Loading ToolBench
MCP server for accessing macOS iMessage conversations, messages, contacts, and chat history
The iMessage MCP server demonstrates solid definition quality with consistent naming patterns, comprehensive parameter descriptions, and well-structured Zod schemas. All 6 tools follow verb_noun naming conventions (search_, get_) and include detailed descriptions with critical pagination warnings. However, output schemas are not explicitly documented in the tool definitions, and error handling lacks actionable recovery guidance. The server properly uses Zod for input validation and includes constraints (min/max on numeric params, datetime format for dates), but response structures are only visible through JSON serialization without formal schema documentation.
Get list of iMessage chats/conversations ordered by most recent activity. Returns chat GUIDs that can be used with 'get_messages_from_chat'. CRITICAL: Results are paginated - for complete chat listing or comprehensive conversation overview, you MUST paginate through ALL results by checking 'hasMore' field and using 'offset' parameter until hasMore=false.
Get list of all contacts/handles (phone numbers, email addresses) that have sent or received iMessages. Returns handle IDs that can be used with 'search_messages'. CRITICAL: Results are paginated - for complete contact listing or comprehensive handle overview, you MUST paginate through ALL results by checking 'hasMore' field and using 'offset' parameter until hasMore=false.
Get messages from a specific chat/conversation using the chat GUID (obtained from 'get_chats'). Returns messages ordered by date (newest first). CRITICAL: Results are paginated - for complete chat history, conversation analysis, or summaries, you MUST paginate through ALL results by checking 'hasMore' field and using 'offset' parameter until hasMore=false. Partial data will lead to incomplete analysis.
Get the most recent iMessages across all conversations, ordered by date (newest first). CRITICAL: Results are paginated - for comprehensive analysis or complete recent activity overview, you MUST paginate through ALL results by checking 'hasMore' field and using 'offset' parameter until hasMore=false.
Output schemas are not formally documented. While responses are returned as JSON via text content type, the server does not declare the structure, field types, or pagination metadata format (hasMore, offset, results array) in tool definitions. LLMs must infer response structure from examples rather than formal schema.
Error handling returns generic error text ('Error searching messages: {message}') without actionable recovery guidance. LLMs receive 'Error' but not what to do next, should specify: retry logic, alternative tools to try, or user-fixable issues.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | C | 68 | 2026-07-28+ | v2 |
| 2026-03-09 | D | 52 | - | v1 |
Search for contacts by first name and optional last name. Use this FIRST when searching for messages from a specific person - it returns the phone number that can be used as the 'handle' parameter in 'search_messages'. Example: search for firstName='John' lastName='Smith' to get his phone number, then use that phone number in search_messages. If lastName is omitted, searches across all name fields. CRITICAL: Results are paginated - for complete contact search results, check 'hasMore' field and use 'offset' parameter until hasMore=false.
Search iMessage messages with various filters. Use 'search_contacts' first to get handle IDs for specific contacts. Handle parameter accepts phone numbers like '+15551234' or email addresses, NOT contact names. CRITICAL: Results are paginated - for summaries, analysis, or complete conversation history, you MUST paginate through ALL results by checking 'hasMore' field and using 'offset' parameter until hasMore=false. Partial data will lead to incomplete analysis.
Parameter 'handle' in search_messages accepts phone numbers or email addresses but lacks format constraints (regex pattern or enum examples). Description says 'e.g., +15551234' but LLMs may hallucinate invalid formats like 'John Smith' despite the warning.
No tool-level result limits enforced for list operations (get_chats, get_handles). While limit params are bounded (max 200), the schema does not cap total results or explain why pagination is CRITICAL in all-caps. Agents may assume first page is sufficient.
Tool descriptions repeat 'CRITICAL: Results are paginated' verbatim 6 times. While pagination guidance is essential, repetitive boilerplate wastes tokens and reduces signal. Consolidate into a server-level pattern note or single parameterization.