Return current WhatsApp connection status (connected, retention, transcription, cache size, idle seconds, etc).

List WhatsApp chats from the local cache, sorted by most recent activity. Each chat has both name (human-friendly, e.g. "XPENG MALAYSIA OWNER CLUB" or "Steve") and id (raw WhatsApp JID like "1234@g.us"). ALWAYS refer to chats by name when talking to the user - the id is only for follow-up tool calls and should never be shown to the user.

Get messages from the last N hours from the local cache. Optionally filter to one chatId or exclude groups. Each message includes chat (the chat's human-friendly name) and from (sender's name). NEVER show the raw chatId, msgId, or sender JID to the user - always speak in names. The IDs are only for follow-up tool calls (e.g. get_image needs chatId+msgId).

Case-insensitive substring search across cached messages. Looks back hours hours (default 720 = 30 days). Returns chat and from as human-friendly names. NEVER show raw chat IDs or message IDs to the user.

Return the most recently generated brief from data/brief.json, or null if none exists.

Write a JSON brief object to data/brief.json. Called by Claude after analyzing messages, so the WhatsApp Brief artifact can render it.

Delete stale credentials and start a fresh QR pair. Returns the raw QR data string in qr; render it as a scannable QR image and ask the user to scan it from their phone (WhatsApp → Settings → Linked Devices → Link a Device). Cache is preserved.

Block until WhatsApp connection.open fires or timeout. Use after relink_whatsapp to confirm the user scanned successfully.

Reconnect the WhatsApp socket. Use only when chats look stale; normally the bridge keeps itself connected.

Download a specific cached image from WhatsApp and return its bytes inline as image content so Claude can see and describe it natively (Opus vision is sharper than gpt-4o-mini). Pass the msgId and chatId from a get_recent_messages result that has hasMedia=true and type=imageMessage. Fails gracefully if media keys are missing (message cached before key tracking was added) or expired (>~14 days old).

After viewing an image via get_image, save your description back to the cache. Future briefs reuse it without re-asking Claude (so each image only costs vision tokens once). Pass chatId + msgId + description (1-2 sentences ideally).

VOICE-ONLY enrichment for the last N hours. Downloads voice notes and transcribes them via OpenAI Whisper. Idempotent (skips already-transcribed). IMPORTANT: this tool no longer touches images - image analysis is done by Claude (you) via the get_image tool, using the Cowork subscription instead of OpenAI Vision. To produce a full brief with both voice transcripts and image descriptions: (1) call enrich_window for voice, (2) call get_image one-by-one for each image in the window and call set_description to cache your description, (3) then call get_recent_messages to read the enriched text and write the brief.

Save a single WhatsApp image to disk. Pass the chatId + msgId from a get_recent_messages result. Default folder: /data/media//, named __.jpg. Returns the absolute path as a resource_link. On failure returns {ok:false, code, error} where code is one of: not_found, not_image, no_keys, media_expired, download_failed, disk_error, permission_denied, disk_full, timeout. The MCP response sets isError:true on failure.

Save a single voice note (.ogg) to disk. Same parameter contract as save_image. Optionally pass transcribe:true to also run Whisper transcription on the saved file (requires OpenAI API key in api-key.txt). Returns transcript inline when transcribed successfully. Same error-code set as save_image, plus: transcribe_failed, no_api_key.

Generic save-to-disk for any media kind (image / audio / video / document). Use save_image or save_voice when you know the type - they're clearer to read. Use this when you have a mixed list of msgIds and don't want to branch.

Preview which media items would be saved by save_media_window. Read-only - does NOT download or write anything. Returns per-item entries with chatId, msgId, kind, sender, chat, timestampISO, sizeBytes, mimeType, and likelyExpired (true when the media-key is older than ~13 days and the CDN may have garbage-collected the blob). Use this BEFORE save_media_window so you can tell the user 'I would save 14 images and 6 voice notes, but 3 are likely expired - proceed?'

Bulk-save WhatsApp media from the last N hours to disk. Downloads with bounded concurrency (default 3) and returns PER-ITEM results - items that fail (expired, no keys, network) are reported in items[].ok=false with a code, but the overall call still succeeds with ok:true. The errors array rolls up failure codes ({code, count}) for quick summarization. Default folder: /data/media//. Each item in the result has the absolute saved path. The call ABORTS the remaining work only on disk_full or disconnected - never on individual download failures.

Return the default folder save_image / save_voice / save_media_window write to (today's folder under /data/media/YYYY-MM-DD), plus how many files are already in it. Useful for answering 'where did you save them?' without filesystem access.

Try to recover WhatsApp messages missed while the bridge was offline (e.g. you didn't open Cowork for a few days, leaving a gap in the history). For each of the most recently active chats it asks WhatsApp's on-demand history sync (Baileys fetchMessageHistory) for older messages, anchored at the newest cached message in that chat. Results arrive asynchronously and are cached. IMPORTANT: how far back WhatsApp actually serves is decided by WhatsApp, not us - run this to find out empirically for this account. Returns cacheBefore/cacheAfter (messagesAdded) and per-chat request info. If messagesAdded is ~0, WhatsApp didn't serve more for those anchors; a fresh re-link (relink_whatsapp) is the fuller-history fallback.