Send an iMessage from the user's Mac. Creates a draft that the user's Mac agent picks up and dispatches via Messages.app. Returns the draft id; use get_draft_status to confirm delivery. The recipient must be a valid phone number in E.164 format (+14155551234) or an email address that the recipient uses for iMessage. If the user's new-outreach limit is reached (N unreplied conversations messaged in a rolling 24-hour window), the message is STILL ACCEPTED and queued: the response carries meta.queued (reason, limit, used, resumesAt = earliest moment a slot frees) and the draft's status is "held" until earlier sends age out of the window or the user raises the limit in Settings — tell the user it is queued, not failed. A 403 recipient_opted_out means the recipient texted STOP: do not retry.

Find the user's iMessage conversations, ordered by most recently active. Each has a GUID you pass to other tools. To find conversations with a phone number, use participant (matches 1:1 AND group chats; loosely-formatted numbers are normalized). Use name to search by contact/group name. Pass at most ONE of participant, handle, name, group, or unread; all accept active_since/active_before, limit, and cursor.

Return the message history of a single conversation, ordered newest first. Useful for catching up on a thread, summarizing, or extracting context before drafting a reply.

Most recent messages ACROSS ALL conversations, newest first — ideal for "catch me up" or "what did I miss today". Filter by direction and time window; paginate with cursor.

List outbound drafts. Useful for checking what's queued for the Mac agent, what is held by the new-outreach limit, what was recently sent, or what failed. By default returns drafts in any state; filter with status (preferred), or sent / send_error.

Read a single draft. Use this after send_imessage to confirm the message was delivered. The response includes status — queued (waiting for the Mac), sending, held (parked by the new-outreach limit — rolling 24h window; resumes automatically as earlier sends age out or when the user raises the limit — NOT a failure), blocked (hold.reason: subscription_required or recipient_opted_out; never auto-retried), sent, cancelled, failed — plus hold (reason/since/message), sent, sendError (failed/cancelled only), and sentMessage (Firestore doc path of the dispatched message).

Soft-cancel a pending draft before the Mac agent dispatches it. Only works while the draft is still sent: false. Once sent, this returns 409 Conflict.

List the user's saved iMessage contacts. Contacts are auto-populated by the Mac agent from macOS Contacts as the user messages people, plus any manual additions. Useful for resolving "Sarah" to a phone number before sending.

Search the user's contacts by display name, phone, or email. Returns the closest matches by case-insensitive substring. Use this when the user references someone by name to resolve them to a sendable phone/email handle.

Create or upsert a contact. Use when the user asks to "save" a new person to their address book. Requires at least one of phone_number or email. Note: this is a one-way edit — changes here do not propagate to the user's native macOS/iOS Contacts.

Check whether the user's Mac agent is currently running and able to dispatch iMessages. If online: false, any send_imessage call will queue the draft but it won't dispatch until the Mac comes back online.