The iMessage MCP server has 13 tools with consistently defined schemas and descriptions. Naming follows verb_noun conventions well. However, several critical issues emerge: (1) Output schemas are not documented, no return type specifications visible in code, forcing LLMs to guess response structure. (2) Error handling is minimal, tools return generic error text without guidance for recovery or categorization (retryable vs. fatal). (3) Some tools lack actionable constraints, e.g., 'filePaths' in send-files has no guidance on absolute vs. relative paths, file size limits, or supported MIME types. (4) Parameter descriptions are present but sometimes generic: 'Filter by sender' doesn't specify expected format (phone, email, both?). (5) No documentation of tool composability, downstream tools don't clearly show what IDs they accept from upstream results. Tools are well-named and have basic structure, but lack the polish and completeness needed for production grade (70+).

• Document output schema for every tool. For example, get-messages should document: 'Returns {messages: [{id, sender, senderName, text, date, attachments: [{filename, mimeType, size, path, isImage}], isFromMe, service}], total: number}'. Include all fields the LLM might need for downstream operations.
• Add error classification and recovery guidance. Instead of 'Error: {message}', return structured errors like: {success: false, error: {code: 'NOT_FOUND', message: 'Contact not found', retryable: false, suggestion: 'Try search_messages() with a partial name.'}}
• Specify parameter format constraints in descriptions. For 'to' parameter: 'Recipient phone number in format +[country][number] (e.g., +1234567890) or email address (e.g., [email protected])'. For 'contact': 'Phone number in E.164 format (+[country][number]) or email address.'
• Document file handling constraints. For send-file and send-files: 'Max file size: 100 MB. Supported MIME types: [list]. Paths must be absolute or relative to current working directory. Returns error if file does not exist or is inaccessible.'
• Add tool annotations to tool definitions. Use readOnlyHint=true for get-*, list-*, search-*. Use destructiveHint=true for send-* operations. This enables agents to understand operation safety without parsing descriptions.
• Clarify tool composability. Add dependency note to send-message: 'If you only have a contact name, call find-contact() first to resolve it to a phone number or email.' Add to get-conversation: 'Accepts output from find-contact() directly.'

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

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