Allows reading and sending WhatsApp messages through a hosted bridge, including searching contacts, listing chats and messages, retrieving message context and last interactions, sending text messages, files and audio messages, downloading media, and syncing history.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@wa-bridge-mcp send a WhatsApp to Mom saying I'll be home by 7"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A small Model Context Protocol (MCP) server that lets an AI assistant (Claude Desktop, Claude Code, etc.) read and send WhatsApp messages through the api-supp WhatsApp bridge.
It's an HTTP client only — every operation goes through the bridge's REST API, so there's no local database, no QR pairing here, and nothing sensitive stored on your machine. You authenticate with a tenant token that scopes the MCP to your own WhatsApp account.
This is a fork of lharries/whatsapp-mcp (MIT), re-worked to talk to a hosted bridge over HTTP. See
NOTICE.
Python 3.11+ (and uv recommended)
Your bridge URL (default https://api.api-supp.com/v1) and a tenant token
(wat_…) — provided to you during onboarding.
Related MCP server: WSAPI WhatsApp MCP Server
git clone https://github.com/yehudashtein/wa-bridge-mcp.git
cd wa-bridge-mcp
uv sync # or: pip install -e .The MCP reads its settings from environment variables:
Variable | Required | Default | Notes |
| ✅ | — | Your tenant bearer ( |
| — |
| Bridge base URL (include |
| — |
| Per-request timeout (seconds) |
Copy .env.example → .env for local runs, or set them in your MCP client config.
Add to your MCP config (e.g. claude_desktop_config.json or .claude.json):
{
"mcpServers": {
"whatsapp": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/wa-bridge-mcp", "run", "main.py"],
"env": {
"WHATSAPP_BRIDGE_URL": "https://api.api-supp.com/v1",
"WHATSAPP_BRIDGE_TOKEN": "wat_your_tenant_token_here"
}
}
}
}Restart the client and the WhatsApp tools appear.
Tool | What it does |
| Search your contacts by name or number |
| List chats (with last message) |
| Look up chats |
| Read messages with filters (chat, time, sender, media, …) |
| Messages around a specific one |
| Most recent message with a contact |
| Send a text message |
| Send media / voice notes |
| Download media from a message |
| Ask the bridge to re-sync history |
The token scopes you to your own WhatsApp account; it can't see other users' data.
Non-ASCII text (Hebrew/Arabic/emoji) sends fine — the bridge handles encoding.
Nothing is stored locally; the MCP is a thin HTTP client.
MIT — see LICENSE and NOTICE (derivative of
lharries/whatsapp-mcp).
Download media from a WhatsApp message and get the local file path.
Args:
message_id: The ID of the message containing the media
chat_jid: The JID of the chat containing the message
Returns:
A dictionary containing success status, a status message, and the file path if successful
| Name | Required | Description | Default |
|---|---|---|---|
| chat_jid | Yes | ||
| message_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses only the return dictionary shape; it says nothing about where files are written, overwrite behavior, size/time limits, or what happens when the message has no media — all material for a download operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded purpose sentence followed by a clean Args/Returns block, with no filler. Slightly formulaic but efficient and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description covers the essentials (what it does, params, return shape). It falls short on failure modes and file-path semantics, which an agent would need before relying on it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does provide a one-line gloss per parameter, but these mostly restate the names ('The ID of the message containing the media'), adding only the minimal hint that the message must contain media.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Download media from a WhatsApp message') plus the concrete outcome ('get the local file path'). It is unambiguous what the tool does, though it never distinguishes itself from siblings like get_message_context or send_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance is given — nothing about needing to resolve a message_id first (e.g., via list_messages or get_message_context), and no alternatives or exclusions are named. The agent must infer the workflow entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get WhatsApp chat metadata by JID.
Args:
chat_jid: The JID of the chat to retrieve
include_last_message: Whether to include the last message (default True)
| Name | Required | Description | Default |
|---|---|---|---|
| chat_jid | Yes | ||
| include_last_message | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full behavioral burden. It implies a read via "Get" but does not state permissions, rate limits, return shape, or what metadata is included beyond the last message option.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded, with the core action stated first and parameter details immediately after. Every sentence contributes directly to understanding the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read tool, the description covers purpose and parameters adequately. However, with no annotations or output schema, it leaves return-value shape and permissive context unstated, which would help an agent invoke it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must document the parameters, and it does: it explains chat_jid as the JID of the chat and include_last_message as whether to include the last message, including its default. It could go further by explaining JID format or where to obtain it, but both parameters are semantically covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: "Get WhatsApp chat metadata by JID." This clearly distinguishes it from bulk listers like list_chats, though it does not explicitly name which sibling to use for other retrieval cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase "by JID" implies this tool is for retrieving a single known chat, which is useful context. However, it gives no explicit when-to-use guidance versus list_chats, get_direct_chat_by_contact, or get_contact_chats.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all WhatsApp chats involving the contact.
Args:
jid: The contact's JID to search for
limit: Maximum number of chats to return (default 20)
page: Page number for pagination (default 0)
| Name | Required | Description | Default |
|---|---|---|---|
| jid | Yes | ||
| page | No | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It indicates a read-style operation and documents pagination defaults, but it does not disclose return shape, ordering, permissions, or whether it includes group and direct chats.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the core action, followed by a compact Args section. Every sentence and parameter entry adds useful information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter read tool with no annotations and no output schema, the description covers purpose and parameters but leaves return structure and behavioral edge cases unspecified. It is minimally adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains all three parameters: jid as the contact JID to search for, limit as the maximum chats to return with default 20, and page for pagination with default 0.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get all WhatsApp chats involving the contact.' This is clear enough for an agent to understand the operation, but it does not distinguish this tool from siblings such as get_direct_chat_by_contact or list_chats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives like get_direct_chat_by_contact or list_chats. It implies retrieving chats for a contact but provides no exclusions or routing conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get WhatsApp chat metadata by sender phone number.
Args:
sender_phone_number: The phone number to search for
| Name | Required | Description | Default |
|---|---|---|---|
| sender_phone_number | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. 'Get' implies a read operation, but the description does not state permissions, side effects, not-found behavior, or what 'metadata' includes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded, with the core purpose in the first sentence and the parameter listed immediately after. There is little waste, though the Args formatting is somewhat mechanical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no annotations and no output schema, so the description should explain more about the return value and edge cases. It does not describe what chat metadata is returned or how missing contacts are handled.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only says the parameter is 'The phone number to search for.' It does not specify expected format, country code handling, or matching behavior, so it does not compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: get WhatsApp chat metadata by sender phone number. It is clear what the tool does, but it does not explicitly distinguish itself from similar siblings such as get_chat or get_contact_chats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives. The phrase 'by sender phone number' implies the lookup key, but the description does not name sibling tools or state exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get most recent WhatsApp message involving the contact.
Args:
jid: The JID of the contact to search for
| Name | Required | Description | Default |
|---|---|---|---|
| jid | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It doesn't say what happens when the contact has no messages (null, error, empty object), whether 'involving' includes group chats where the contact merely appears, or whether the read is scoped to synced history.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core sentence is front-loaded and appropriately short. The leftover Python docstring 'Args:' block is minor noise but not harmful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A read tool with no annotations and no output schema needs the description to explain the return shape, and it never does. An agent cannot tell whether it receives a message object, a list, or null when nothing is found.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description only restates the parameter name as 'the JID of the contact to search for', with no JID format (e.g. user@s.whatsapp.net) or example. It adds almost nothing an agent could not infer from the schema title 'Jid'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource: 'Get most recent WhatsApp message involving the contact.' An agent can tell it apart from list_messages or get_message_context by the 'most recent single' framing, though the sibling distinction is only implied, never stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to prefer this over list_messages, get_message_context, or get_contact_chats, all of which could plausibly surface messages for a contact. Nothing about prerequisites or exclusion cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get context around a specific WhatsApp message.
Args:
message_id: The ID of the message to get context for
before: Number of messages to include before the target message (default 5)
after: Number of messages to include after the target message (default 5)
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | ||
| before | No | ||
| message_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations and no output schema, so the description carries the full burden. It does convey the core behavior — returning messages before and after a target message with defaults of 5 each — but says nothing about ordering, whether media is included, permission/auth requirements, or what happens with an invalid or deleted message_id.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Short and front-loaded: a single summary sentence followed by a compact Args block. No padding, though the defaults in the Args section duplicate what the schema already declares.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only retrieval tool this covers the essentials, but with no annotations and no output schema the definition should say more about the returned shape (e.g., ordering, inclusion of target message, media handling) and edge cases like an unknown message_id.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description is the only source of parameter meaning, and it documents all three params: message_id as the target and before/after as counts of surrounding messages. It effectively compensates for the empty schema, though it repeats the defaults already declared in the schema and omits any bounds or limits.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Get context around a specific WhatsApp message'), which is clearly distinct from siblings like list_messages or get_last_interaction. It doesn't explicitly name an alternative, but the resource is specific enough for an agent to place it in the chat-reading family.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The use case (fetch surrounding messages around a known message_id) is implied by the purpose and the before/after parameters, but there is no explicit when/when-not guidance and no mention of alternatives such as list_messages or get_last_interaction. The agent must infer when this is preferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get WhatsApp chats matching specified criteria.
Args:
query: Optional search term to filter chats by name or JID
limit: Maximum number of chats to return (default 20)
page: Page number for pagination (default 0)
include_last_message: Whether to include the last message in each chat (default True)
sort_by: Field to sort results by, either "last_active" or "name" (default "last_active")
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| limit | No | ||
| query | No | ||
| sort_by | No | last_active | |
| include_last_message | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It usefully discloses pagination defaults (page 0, limit 20) and the sort fields, but never states that this is a read-only operation, what a chat record contains, or any auth/rate-limit behavior. Partial disclosure for a zero-annotation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose sentence is front-loaded and the Args block is scannable. The argument list largely mirrors schema defaults, so some lines are near-redundant, but nothing is bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should hint at the shape of a returned chat; it only implies this indirectly via include_last_message. For a 5-parameter listing tool with no annotations and no output schema, the definition is adequate but leaves return-value expectations unset.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% (params have only titles and defaults), so the description must compensate, and it does: it explains query matches by name OR JID, and pins sort_by to the two legal values ('last_active', 'name'), which the schema does not constrain. Only the page/limit semantics beyond defaults are left implicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get WhatsApp chats') plus a filtering scope ('matching specified criteria'), which is enough to separate it from get_chat (single chat) and list_messages. It never names those siblings, so differentiation is inferred rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'matching specified criteria' implies the tool is for filtered listing, and the pagination/sorting params imply long result sets. There is no explicit when-to-use guidance, no exclusion of alternatives like get_direct_chat_by_contact or get_contact_chats, and nothing about prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get WhatsApp messages matching specified criteria with optional context.
Args:
after: Optional ISO-8601 formatted string to only return messages after this date
before: Optional ISO-8601 formatted string to only return messages before this date
sender_phone_number: Optional phone number to filter messages by sender
chat_jid: Optional chat JID to filter messages by chat
query: Optional search term to filter messages by content
limit: Maximum number of messages to return (default 20)
page: Page number for pagination (default 0)
include_context: Whether to include messages before and after matches (default True)
context_before: Number of messages to include before each match (default 1)
context_after: Number of messages to include after each match (default 1)
include_groups: Whether to include group chat messages (default False)
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| after | No | ||
| limit | No | ||
| query | No | ||
| before | No | ||
| chat_jid | No | ||
| context_after | No | ||
| context_before | No | ||
| include_groups | No | ||
| include_context | No | ||
| sender_phone_number | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it discloses only the context-window behavior (include_context with before/after counts) and the include_groups default. It says nothing about read-only semantics, ordering of results, pagination behavior beyond default values, or whether data is local-cached versus live, all of which matter for an 11-parameter query tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose sentence is front-loaded and the Args enumeration is dense but earns its space given zero schema descriptions. There is minor redundancy in restating defaults that already exist in the schema, but no filler prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter tool with no annotations and no output schema, the description covers inputs adequately but never indicates what a returned message looks like, how context messages are flagged or ordered relative to matches, or what an empty result means. It is usable as-is but leaves the agent guessing about the response shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the Args block is the only documentation for all 11 parameters, and it does the job: it gives format hints (ISO-8601), meaning (sender vs chat vs content filters), and defaults. It falls short of 5 because 'page' semantics (offset vs page index, interaction with limit) remain ambiguous and context_before/context_after applicability is not tied explicitly to include_context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific verb (Get) and resource (WhatsApp messages) plus the scoping notion of matching criteria with optional surrounding context. It is clear what the tool does, but it does not distinguish itself from siblings like get_message_context or list_chats, which an agent must differentiate on name alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Nothing states when to use this versus get_message_context, list_chats, or get_last_interaction, nor are there any exclusions or prerequisites. Usage is only inferable from the parameter list (filters imply search-style retrieval), which is guidance by implication rather than statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search WhatsApp contacts by name or phone number.
Args:
query: Search term to match against contact names or phone numbers
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It doesn't disclose matching semantics (partial vs exact, case sensitivity), result shape (does it return one contact or many?), or whether a phone number requires a country code — meaningful gaps for a lookup tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded one-sentence purpose followed by an Args block. Brief and readable, though the Args restatement partially duplicates the only schema property and adds little.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with no output schema and no annotations, the basics are covered but the agent still can't predict result shape (single vs list), match granularity, or how phone-number queries are normalized.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does say the single 'query' parameter matches contact names OR phone numbers, adding meaning beyond the bare string type, but it gives no format guidance for phone numbers or expected match behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Search WhatsApp contacts') plus the two dimensions searchable (name or phone number). It's clearly distinct from sibling like get_direct_chat_by_contact or list_chats, though it doesn't explicitly name those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description never says when to reach for this tool versus get_direct_chat_by_contact (which also resolves a contact) or list_chats. Usage is only implied by 'search by name or phone number' with no exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send any audio file as a WhatsApp audio message to the specified recipient. For group messages use the JID. If it errors due to ffmpeg not being installed, use send_file instead.
Args:
recipient: The recipient - either a phone number with country code but no + or other symbols,
or a JID (e.g., "123456789@s.whatsapp.net" or a group JID like "123456789@g.us")
media_path: The absolute path to the audio file to send (will be converted to Opus .ogg if it's not a .ogg file)
Returns:
A dictionary containing success status and a status message
| Name | Required | Description | Default |
|---|---|---|---|
| recipient | Yes | ||
| media_path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses important behavior: conversion to Opus .ogg when needed, dependency on ffmpeg, fallback to send_file on ffmpeg error, and a success/status return shape. It stops short of covering permissions, size limits, or idempotency, but is substantially transparent for a send operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action and then uses a readable Args/Returns structure. It is appropriately sized for the tool, though the Args formatting repeats parameter names already in the schema, making it slightly less tight than it could be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description covers the action, both parameter formats, conversion behavior, an important failure mode with a fallback, and the return shape. It leaves only minor gaps such as authentication or file-size constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate and does: recipient is explained as a phone number without symbols or a JID with concrete examples, and media_path is explained as an absolute path with a note that non-.ogg files are converted. Both required parameters gain essential meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a specific verb and resource: send any audio file as a WhatsApp audio message to a recipient. It is immediately distinguishable from send_file (binary file) and send_message (text), and the explicit fallback to send_file when audio conversion fails further clarifies its role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states a clear operational context (use JID for groups) and an explicit alternative for the ffmpeg-missing error case. It does not provide general when-not-to-use guidance versus send_file or send_message, but the intended usage is strongly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a file such as a picture, raw audio, video or document via WhatsApp to the specified recipient. For group messages use the JID.
Args:
recipient: The recipient - either a phone number with country code but no + or other symbols,
or a JID (e.g., "123456789@s.whatsapp.net" or a group JID like "123456789@g.us")
media_path: The absolute path to the media file to send (image, video, document)
Returns:
A dictionary containing success status and a status message
| Name | Required | Description | Default |
|---|---|---|---|
| recipient | Yes | ||
| media_path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the return shape and media types, but omits important operational details such as permissions, external side effects, file-size limits, recipient validation, or failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action, followed by structured Args and Returns sections. Every part contributes to invocation understanding without unnecessary repetition or bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description explains parameters and return shape reasonably well. However, it leaves out behavioral prerequisites and constraints that matter for a send operation, such as authentication, file limits, and error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: recipient is explained as either a phone number without symbols or a JID, including group JID examples, and media_path is described as an absolute path with file types. It could add whether media_path must already exist or whether URLs are accepted, but the parameter meaning is substantially clarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: send a file via WhatsApp to a specified recipient. It also names supported media types and group JID behavior. It is clear but does not explicitly distinguish this from the overlapping sibling send_audio_message, which also handles audio media.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives useful context that group messages require a JID, but it does not explain when to use send_file instead of send_message or send_audio_message. The usage is implied rather than explicitly guided with alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a WhatsApp message to a person or group. For group chats use the JID.
Args:
recipient: The recipient - either a phone number with country code but no + or other symbols,
or a JID (e.g., "123456789@s.whatsapp.net" or a group JID like "123456789@g.us")
message: The message text to send
Returns:
A dictionary containing success status and a status message
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | ||
| recipient | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. It does disclose the return shape (a dictionary with success status and status message), but says nothing about side effects beyond the obvious send, authentication/connection requirements, rate limits, or what happens with an invalid recipient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in the first sentence, followed by the group-chat caveat and a compact Args/Returns block. Every line adds information and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only two required parameters and no output schema, the description covers the essentials of calling the tool and the return value. It is still thin on the operational context an unannotated write-style tool needs, such as authentication state and delivery/error outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate, and it does: 'recipient' is documented with the phone-number format (country code, no + or symbols) and two concrete JID examples, including a group JID; 'message' is defined as the message text. The only gap is behavior on malformed input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Send a WhatsApp message to a person or group'), which an agent can distinguish from send_audio_message and send_file by the message type. It does not explicitly name those siblings or draw the boundary, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The line 'For group chats use the JID' gives a concrete condition for choosing the recipient format, which is real usage guidance. However, there is no guidance on when to prefer this over send_audio_message/send_file, no preconditions such as an authenticated session, and no failure handling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trigger a WhatsApp history sync to fetch missed messages from the server. Use this when messages appear to be missing or after a bridge restart.
Returns:
A dictionary containing success status and a status message
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses that the tool returns a dictionary with success status and a message, but omits whether the sync is read-only, whether it has side effects, or how long it might take. Adequate but incomplete for a tool that triggers a server-side action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences, front-loaded with the core action, followed by usage guidance and return info. Every sentence earns its place and there is no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, parameterless tool with no output schema, the description covers what it does, when to use it, and what it returns. It lacks deeper behavioral context (e.g., safety, side effects) that would be needed if annotations were present, but overall it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no parameter semantics to explain; the baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Trigger') and resource ('WhatsApp history sync') and clarifies its purpose ('fetch missed messages from the server'). It does not explicitly differentiate from siblings like list_messages, but the name and phrasing make the distinct function clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use conditions: 'when messages appear to be missing or after a bridge restart.' However, it does not mention when not to use it or name alternatives for other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0download_mediaget_chatget_contact_chatsget_direct_chat_by_contactget_last_interactionget_message_contextlist_chatslist_messagessearch_contactssend_audio_messagesend_filesend_messagesync_historyScored across 13 tools
Most tools are distinct, but the read side has several overlapping lookups: get_chat vs. get_direct_chat_by_contact, get_last_interaction vs. list_messages (limit 1 filtered by contact), and get_message_context vs. list_messages with include_context all return similar data via different entry points. send_audio_message vs. send_file also overlap, though the description explicitly disambiguates them.
All tools use snake_case with a verb_noun structure (search_contacts, list_messages, send_file, get_message_context), which is predictable and readable. Minor irregularity from compound names like get_direct_chat_by_contact, but the convention holds throughout.
13 tools is a well-scoped count for a WhatsApp bridge covering read, send, media, and sync workflows. Slightly lean toward redundant read helpers (get_direct_chat_by_contact could fold into get_chat), but nothing is gratuitous.
Core lifecycle is covered: contacts, chats, messages, context, media download, history sync, and sending text/file/audio. Gaps exist for message deletion, forwarding, reactions, and read receipts, which agents may need but can work around.
Read, search and reply to your WhatsApp chats from your AI, using your own number.
WhatsApp for Claude, ChatGPT or any AI agent: search, reply and send. Personal or Business API.
WhatsApp CRM for AI agents: search contacts, read chats, manage the sales pipeline, send messages.
Your business WhatsApp for any AI: read and search chats, digests, team stats, sends you approve.