Tool reference

account_status

account_status() → object

Diagnostics for the linked account. Use it first when something returns nothing: an account that was never linked, or one that logged out, shows up here rather than as an empty chat list.

{
  "store_dir": "/srv/stores/<account>",
  "authenticated": true,
  "linked_jid": "[email protected]",
  "lock_held": true,
  "messages": 48213
}

A lock_held of true is normal: the sync daemon holds the store lock while it runs.

list_chats

list_chats(limit?, query?, unread?) → array

Chats of the linked account, most recent activity first. This is the usual way to turn a name into a JID.

[
  {
    "jid": "[email protected]",
    "name": "Apartment 4B",
    "kind": "group",
    "unread": true,
    "unread_count": 14,
    "last_message_ts": 1789412044,
    "pinned": false,
    "archived": false
  }
]

list_messages

list_messages(chat?, limit?, from_me?, after?, before?) → array

Messages newest first. Without chat it spans every conversation, which is how “what came in today” questions get answered.

// "what did the landlord write this week?"
{
  "name": "list_messages",
  "arguments": {
    "chat": "[email protected]",
    "after": "2026-09-14",
    "from_me": false,
    "limit": 50
  }
}

search_messages

search_messages(query, limit?, chat?, after?, before?) → array

Full-text search across the synced history, backed by SQLite FTS5 where the store supports it and a LIKE scan otherwise. This is the tool that makes two years of chat useful.

// "find the IBAN someone sent me"
{ "name": "search_messages",
  "arguments": { "query": "IBAN DE", "limit": 10 } }

search_contacts

search_contacts(query, limit?) → array

Resolve a name or number to a contact and its JID, from the synced contact metadata. Cheaper than listing chats when you already know who you mean.

get_chat

get_chat(chat) → object

One chat in detail: name, kind, unread count, mute and pin state. Useful when a client already holds a JID and does not want to page through a chat list to check one thing.

get_message_context

get_message_context(chat, message_id, before?, after?) → object

The messages around one message. A search hit on its own is often meaningless — “yes, fine” answers something, and this is how a model finds out what.

// search first, then read around the hit
{ "name": "get_message_context",
  "arguments": { "chat": "[email protected]",
                   "message_id": "3EB0…", "before": 8, "after": 4 } }

list_starred

list_starred(limit?, chat?) → array

Messages the account owner starred. A hand-curated set of the things they thought mattered — often the fastest path to an address, a code or a document.

list_calls

list_calls(limit?, chat?, after?, before?) → array

Call events with time, peer and whether the call was answered. Answers “did they ever actually call me back” without reading a single message.

list_groups

list_groups(limit?, query?) → array

Groups the account belongs to, optionally filtered by name. Groups also appear in list_chats; this returns the group-level record instead of the chat record.

get_group

get_group(group) → object

Subject, description, participant list and admins of one group. The tool that answers “who is even in this group” and “who can add people”.

history_coverage

history_coverage(limit?, query?, chat?) → object

How far back synced history actually reaches, per chat. Worth calling before concluding that something was never said: an empty search can mean “not in this account's synced window” rather than “never happened”.

get_media

get_media(chat, message_id) → image | object

Downloads the attachment of one message on demand. Images up to 5 MB come back as image content, so a model can look at the photo of the parking permit instead of guessing from the filename. Other types return their media type and size.

Media is fetched per call and the temporary copy is deleted immediately afterwards. Nothing is bulk-downloaded in the background.

send_message write access

send_message(to, message) → object

Sends a text message from the linked account. The tool is not registered at all for accounts without write access — a client cannot list it, let alone call it. Where it is enabled, the write path runs without the CLI's read-only guard, and the result contains the message id that WhatsApp assigned.

A phone number that has never been messaged works: WhatsApp starts a new conversation, exactly as it would if you typed the number into the app. Check the number exists first.