whatsapp-tools

Overview Schema Source Related Servers Discussions Admin

Send a message

whatsapp_message_send

Send a single text message to a WhatsApp person or group using a chat JID. Optionally quote an existing message; the result confirms WhatsApp accepted it, not delivery.

Instructions

Sends one text to a person or a group; channels, broadcast lists and the status feed are refused. chat is a JID from whatsapp_chat_read list, or for someone new the chat that whatsapp_contact_read check gives (the tool asks WhatsApp whether the number has an account first), never a name or a number. It needs the account's sync service running. text is sent exactly as given, surrounding blank space trimmed, at most 4000 characters; it is never split or shortened without the user's agreement, and no link preview is fetched. reply_to quotes a message of the same chat by its id. The result means WhatsApp accepted the message, not that it was delivered or read. A failure uncertain means the message may have gone out: read the chat with whatsapp_chat_read and ask the user before sending it again, never send it again blindly. The chat's unread count in the local mirror drops, as when the user writes in it, and no read receipt is sent. errors.record says when the message was sent but could not be written to the mirror.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "chat": "<chat>",
      "text": "<text>"
    },
    "name": "whatsapp_message_send"
  }
}

Input Schema

Name	Required	Description
`chat`	Yes	The chat to send to: a person's or a group's JID (…@s.whatsapp.net, …@lid or …@g.us), never a name or a number. Find it with whatsapp_chat_read list; for someone new, the `chat` that whatsapp_contact_read check gives.
`text`	Yes	The text exactly as it should arrive; surrounding blank space is trimmed, and what is left is 1 to 4000 characters.
`account`	No	The account label; may be left out when only one account is paired.
`reply_to`	No	The id of a message of that chat to quote, as whatsapp_chat_read gives it.

Output Schema

Name	Required	Description
`id`	Yes	The sent message's id.
`chat`	Yes	The chat's JID.
`note`	Yes	Says that accepted is not delivered or read, and that the text sent is the user's.
`time`	Yes	When the send was confirmed as accepted by WhatsApp, in local time with offset.
`errors`	No	Set when the message was sent but could not be written to the mirror; `record` says why.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 12, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations by explaining that success means WhatsApp accepted the message, not that it was delivered or read, and by spelling out the `uncertain` failure mode and the risk of duplicate sends given idempotentHint=false. It also discloses side effects the agent could not otherwise predict: the local unread count drops, no read receipt is sent, no link preview is fetched, and `errors.record` captures a mirror write failure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action and the refusal list, then ordered by what the agent needs next: required inputs, preconditions, text handling, result meaning, failure handling. It is dense and long, and a few clauses restate schema detail (JID formats, character cap), but for a non-idempotent send tool almost every sentence carries operational weight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a non-idempotent outbound-message tool with an output schema, the description covers the residual risk areas: precondition failure, ambiguous send outcome, duplicate-send hazard, and mirror-side inconsistency. Nothing an agent needs in order to call this safely is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds constraints not present in the schema: `text` is never split or shortened without the user's agreement, and `reply_to` must quote a message of the same chat. It does repeat schema content about JIDs, trimming and the 4000-character limit, which keeps it from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ('Sends one text to a person or a group') and immediately delimits scope by naming what is refused: channels, broadcast lists and the status feed. Combined with the sibling read-tools in the catalog, an agent can tell this is the sole write path here without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent to alternatives for prerequisites ('a JID from whatsapp_chat_read list, or for someone new the `chat` that whatsapp_contact_read check gives') and states the runtime condition ('needs the account's sync service running'). It also gives conditional recovery guidance: on an `uncertain` failure, read the chat and ask the user before resending.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server