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., "@whatsapp-business-mcp Send welcome template to +1234567890"
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.
MCP server for the WhatsApp Business / Meta Graph API. List business accounts and phone numbers, manage message templates, send template messages, and look up message status.
Supports two transports:
stdio — default; for local Claude Desktop / Claude Code / Cursor.
HTTP (Streamable / SSE) — for remote deployment (Railway, Fly.io, Render, your own container).
Tool | Read-only | Description |
| yes | Discovery — start here. List WABAs owned by a Meta Business. |
| yes | List phone numbers on a WABA (returns |
| yes | List templates with filters (status, language, name) and pagination. |
| no | Create a new message template (goes through Meta review). |
| destructive | Delete a template by name (all languages). |
| no | Send an approved template message. Validates phone (E.164), template name, locale. |
| yes | Look up a message by |
| restricted | Escape hatch — only whitelisted WhatsApp Business paths. |
Related MCP server: bach-whatsapp_number_validators
The server also exposes the same inventory as MCP resources so the host can cache them:
whatsapp://business-accounts/{business_id}
whatsapp://phone-numbers/{waba_id}
whatsapp://templates/{waba_id}
Variable | Required | Default | Description |
| yes | — | Meta Graph API access token (system user token recommended). |
| no |
| Graph API version. |
| no |
|
|
| no |
| HTTP transport port. |
| no |
| HTTP transport bind address. |
| no |
| HTTP transport endpoint path. |
| no | — | If set, HTTP requests must send |
npm install
npm testWHATSAPP_TOKEN=... npm startWHATSAPP_TOKEN=... MCP_BEARER_TOKEN=... npm run start:http
# → MCP listening on http://0.0.0.0:3000/mcp
# → Health check at GET /healthOnce published to npm:
{
"mcpServers": {
"whatsapp-business": {
"command": "npx",
"args": ["-y", "whatsapp-business-mcp-server"],
"env": { "WHATSAPP_TOKEN": "your-token-here" }
}
}
}Or from a local checkout:
{
"mcpServers": {
"whatsapp-business": {
"command": "node",
"args": ["/absolute/path/to/whatsapp-business-mcp/src/server.mjs"],
"env": { "WHATSAPP_TOKEN": "your-token-here" }
}
}
}{
"mcpServers": {
"whatsapp-business": {
"url": "https://your-host.example.com/mcp",
"headers": { "Authorization": "Bearer your-bearer-token" }
}
}
}docker build -t whatsapp-business-mcp .
docker run --rm -p 3000:3000 \
-e WHATSAPP_TOKEN=... \
-e MCP_BEARER_TOKEN=... \
whatsapp-business-mcpNew project → Deploy from GitHub.
Railway detects the Dockerfile. Set service variables:
WHATSAPP_TOKEN
MCP_BEARER_TOKEN (shared secret for the HTTP endpoint)
PORT is provided automatically by Railway; the server respects it.
Public URL → https://<service>.up.railway.app/mcp.
fly launch --no-deploy
fly secrets set WHATSAPP_TOKEN=... MCP_BEARER_TOKEN=...
fly deployEnsure the [http_service] block in fly.toml uses internal_port = 3000.
New → Web Service → connect repo. Render detects the Dockerfile.
Add environment variables WHATSAPP_TOKEN and MCP_BEARER_TOKEN.
Health check path: /health.
Always set MCP_BEARER_TOKEN when exposing the HTTP transport publicly. Without it,
anyone who reaches the endpoint can use your WhatsApp Business token.
The token is read from the server's environment, never accepted from MCP clients.
wa_api_call is restricted to a whitelist of WhatsApp Business paths; arbitrary Graph
endpoints are rejected.
Inputs are validated before requests reach Meta: phone numbers must be E.164, template
names match [a-z0-9_]+, locales match xx or xx_YY.
The server classifies Graph API failures and returns structured hints to the LLM:
token_expired / token_invalid (HTTP 401, code 190) — refresh credentials.
permission_denied (HTTP 403, code 10/200) — scopes/asset access missing.
rate_limited (HTTP 429, code 4) — back off and retry.
not_found (HTTP 404).
upstream_error (5xx).
network_error — fetch failed before reaching Meta.
Escape hatch for WhatsApp Business / Meta Graph endpoints that don't have a dedicated tool yet.
Restricted: only paths matching a curated allowlist of WhatsApp Business resources are accepted (message_templates, phone_numbers, messages, media, business_profile, analytics, subscribed_apps, owned_whatsapp_business_accounts, single-ID reads, wamid lookups). Anything else is rejected.
Prefer the typed tools when one matches — they validate inputs and surface clearer errors.
Inputs:
path: starts with /, e.g. /{waba_id}/subscribed_apps
query_params: raw query string without leading ? (will be appended)
body_json: JSON string of the request body, used with POST/DELETE
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Graph API path starting with /, e.g. /{waba_id}/subscribed_apps | |
| method | Yes | HTTP method | |
| body_json | No | JSON string of request body for POST/DELETE | |
| query_params | No | Query string params (without leading ?), e.g. fields=id,name&limit=100 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the allowlist restriction and input formatting behavior (query appended, body used for POST/DELETE). However, it does not mention response shape, error behavior, or authentication side effects, which are relevant for a generic API passthrough.
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 well-structured with sections for purpose, restrictions, usage, and inputs. It is slightly long but every sentence adds value, and the front-loaded purpose and restriction are effective.
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 complex generic API tool with 4 parameters and no output schema, the description covers purpose, restrictions, usage guidance, and parameter formats. It lacks explicit statement about return values or error handling, which would make it more 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 100%, so baseline is 3. The description mostly repeats schema descriptions but adds minor context like 'will be appended' for query_params. It does not significantly enhance parameter understanding beyond the 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 description clearly states the tool is an 'escape hatch' for WhatsApp Business endpoints lacking dedicated tools, distinguishing it from typed siblings. It lists specific resource categories it covers, making the purpose unambiguous.
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?
Explicitly instructs to 'prefer the typed tools when one matches' and explains why (validation, clearer errors). Also specifies allowed path patterns and rejection of non-allowlisted paths, providing clear when-to-use/when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new message template in a WABA. Templates go through Meta review before they can be sent.
When to use: setting up a new outbound notification, marketing or authentication message type.
Inputs:
name: lowercase letters, digits, underscores only.
language: locale code matching Meta's list (en, pt_PT, es_ES, ...).
category: UTILITY | MARKETING | AUTHENTICATION. Affects pricing and review rules.
components_json: JSON array following Meta's component schema. Common types:
[{"type":"HEADER","format":"TEXT","text":"Hello"},
{"type":"BODY","text":"Hi {{1}}, your code is {{2}}.","example":{"body_text":[["Alice","123"]]}},
{"type":"FOOTER","text":"Reply STOP to opt out"}]
Returns: the new template's ID. Status starts as PENDING; poll wa_get_templates for review result.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Template name: lowercase letters, digits, underscores only | |
| waba_id | Yes | WhatsApp Business Account ID (numeric) | |
| category | Yes | Template category | |
| language | Yes | Language/locale code, e.g. en, pt_PT, es_ES | |
| components_json | Yes | JSON array of components (HEADER, BODY, FOOTER, BUTTONS) following Meta API schema |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With empty annotations, the description carries the full burden. It discloses that templates undergo Meta review, start with PENDING status, and advises polling wa_get_templates for the result. This is valuable behavioral context beyond the schema, even though details like error handling or authentication requirements are not covered.
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 well-organized with clear sections for purpose, usage, and inputs. It includes a detailed example for components_json, which adds length but is highly informative. Every sentence serves a purpose, and information is front-loaded with the core purpose and usage.
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 the tool's complexity (5 required parameters, no output schema, no annotations), the description covers all essential aspects: purpose, usage, parameter details, return value, and follow-up action (polling). It does not explain error handling or request-specific edge cases, but provides sufficient context for typical use.
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 100%, but the description adds value by elaborating on each parameter: naming constraints, language examples, category meaning (affects pricing and review rules), and a concrete components_json example. This goes well beyond the schema's basic descriptions, providing practical guidance for constructing valid 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?
The description begins with 'Create a new message template in a WABA,' a specific verb and resource that clearly distinguishes this tool from siblings like wa_get_templates (list), wa_delete_template (delete), and wa_send_template (send). It also clarifies the Meta review process, leaving no ambiguity about the tool's function.
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 includes an explicit 'When to use' line, stating it is for 'setting up a new outbound notification, marketing or authentication message type.' This provides clear context for when to invoke the tool, though it does not explicitly mention exclusions or alternative tools for similar circumstances.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a message template from a WABA by name. WARNING: deletes ALL languages of that template.
When to use: removing obsolete or rejected templates. Cannot be undone.
Note: deletion is irreversible. Confirm with the user before invoking.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Exact template name to delete (all languages will be removed) | |
| waba_id | Yes | WhatsApp Business Account ID (numeric) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite empty annotations, the description discloses all critical behavioral traits: irreversible deletion, removal of all languages, and the need for user confirmation. This fully compensates for the lack of structured metadata.
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 extremely concise, with a clear warning upfront, a short 'When to use' section, and a final irreversibility note. Every sentence adds value, and nothing is redundant.
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 fully covers the necessary context for a destructive delete operation: what gets deleted, that it is irreversible, and that user confirmation is required before invoking. It is complete for a simple two-parameter tool.
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 100%, and each parameter already has a clear description including the 'all languages' note for 'name'. The description adds no new semantic detail beyond the schema, so the baseline 3 is appropriate.
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 clearly states the action ('Delete a message template') and scope ('from a WABA by name'), and explicitly warns that ALL languages are deleted. It is well differentiated from siblings like wa_create_template and wa_get_templates.
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?
Provides a clear 'When to use' statement ('removing obsolete or rejected templates') and emphasizes irreversibility with a user-confirmation requirement. However, it does not explicitly mention when not to use or suggest alternatives, so it misses the full 5 criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
DISCOVERY — START HERE.
List all WhatsApp Business Accounts (WABAs) owned by a Meta Business. This is the entry
point for almost every other tool: most calls take a waba_id returned here.
Typical flow:
wa_get_business_accounts (this tool) → pick a waba_id
wa_get_phone_numbers(waba_id) → pick a phone_number_id for sending
wa_get_templates(waba_id) → pick an APPROVED template
wa_send_template(phone_number_id, to, template_name, language_code, ...)
Resources whatsapp://business-accounts/{business_id} provide the same data and can be
cached by the host.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | Comma-separated fields to return (default: id,name,status) | id,name,status |
| business_id | Yes | Meta Business ID (numeric) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It clearly discloses a read-only listing behavior, states that the returned waba_id is used by downstream calls, and notes that the data is cacheable. It does not cover pagination or authentication, but the core behavior is transparent.
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 'DISCOVERY — START HERE' and a clear statement of purpose. The numbered flow and cacheability note are concise and every sentence earns its place by providing operational guidance.
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 list tool with no output schema, the description provides sufficient context: it explains the entry-point role, the returned waba_id, and the next steps in the workflow. It could add pagination or auth details, but the flow guidance makes it complete for the intended discovery use.
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 input schema already documents both parameters with 100% coverage, so the baseline is 3. The description reinforces that business_id identifies the Meta Business and that waba_id is the key output, but it does not add meaning beyond what the schema already provides.
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 uses a specific verb+resource ('List all WhatsApp Business Accounts owned by a Meta Business') and clearly marks it as the discovery entry point. It distinguishes itself from siblings by explaining that most other tools require the waba_id returned here.
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 explicitly says 'DISCOVERY — START HERE' and provides a numbered typical flow showing exactly when to call this tool before wa_get_phone_numbers, wa_get_templates, and wa_send_template. It also mentions that REST resources provide the same data and can be cached, giving practical usage alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up information about a previously sent WhatsApp message by its ID.
Use this after wa_send_template to confirm Graph API received the message. Note that WhatsApp delivery/read status (sent → delivered → read) is pushed asynchronously via webhooks; the Graph API does not expose a polling endpoint for those transitions. This tool retrieves the message resource directly and surfaces whatever Meta returns.
Inputs: the wamid returned by wa_send_template.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | Comma-separated fields to request | id,status,recipient_id,timestamp,errors |
| message_id | Yes | The wamid returned when the message was sent (e.g. wamid.XXXX...) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite having empty annotations, the description discloses a key behavioral limitation: the Graph API does not expose a polling endpoint for delivery/read transitions. It also clarifies that the tool simply 'retrieves the message resource directly and surfaces whatever Meta returns.' It doesn't mention error handling or authentication, but the most important caveat is covered.
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 concise, purposeful sentences. Each sentence earns its place: the first states the core purpose, the second provides usage context and the webhook caveat, and the third identifies the required input. There is no fluff or redundancy.
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 lookup tool, the description is highly complete: it defines the operation, specifies the triggering event (after wa_send_template), explains the limitation of status polling, and identifies the key input. The absence of an output schema is partially mitigated by the 'fields' parameter and the phrase 'surfaces whatever Meta returns.'
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 schema already provides full description coverage for both parameters (100%). The description's line 'Inputs: the wamid returned by wa_send_template' reinforces the message_id parameter but adds no new semantic meaning beyond the schema. Baseline 3 is appropriate.
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 opens with a specific verb and resource: 'Look up information about a previously sent WhatsApp message by its ID.' This clearly distinguishes it from siblings like wa_send_template or wa_get_templates, which have different purposes.
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 explicitly states when to use the tool: 'Use this after wa_send_template to confirm Graph API received the message.' It also provides a when-not by explaining that delivery/read status is pushed asynchronously via webhooks and no polling endpoint exists, so the tool is not for real-time status transitions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List phone numbers registered to a WhatsApp Business Account (WABA).
Use this to discover the phone_number_id required by wa_send_template. display_phone_number
is the human-readable number (e.g. +351 91 234 5678); id is the numeric resource ID you pass
as phone_number_id to send.
Also returns quality_rating (GREEN/YELLOW/RED) and messaging status, useful for diagnosing delivery problems.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | Fields to return | id,display_phone_number,verified_name,quality_rating,status |
| waba_id | Yes | WhatsApp Business Account ID (numeric) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It correctly implies a read-only listing operation ('List') and adds useful context about returned fields (quality_rating, status) and their diagnostic value. It does not mention permissions or pagination, but for a read-only list tool this is adequate.
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 concise and well-structured: a one-sentence summary, a usage paragraph explaining the connection to wa_send_template, and a final note on additional fields. No wasted words; each sentence contributes meaning.
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 output schema, the description adequately explains the key return fields (display_phone_number, id, quality_rating, status) and their usage. It does not mention verified_name or potential pagination, but the tool is simple enough that this is not a major gap. Overall, it gives an agent enough context to invoke the tool and interpret results.
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 100% with both parameters (waba_id and fields) already described in the input schema. The description adds minimal parameter-specific detail beyond the schema, primarily clarifying the role of the return value 'id' as phone_number_id. This meets the baseline but does not exceed it.
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 clearly states the tool lists phone numbers for a WABA, with a specific verb ('List') and resource. It also differentiates from siblings by linking to wa_send_template and explaining how to obtain phone_number_id.
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 explicitly says 'Use this to discover the phone_number_id required by wa_send_template', giving a clear when-to-use. It also mentions using quality_rating/status for diagnosing delivery problems. However, it does not explicitly name alternative tools for when not to use it, though sibling names like wa_get_business_accounts provide implicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List message templates for a WhatsApp Business Account (WABA), with optional filters.
When to use: discovery before sending (wa_send_template requires an APPROVED template), auditing template inventory, or verifying review status after wa_create_template.
Filters are applied server-side (status, name) or client-side (language). Use pagination
via after when has_more is true in the response.
Returns: { count, templates[], has_more, next_cursor? } where each template includes name, language, status, category and component definitions.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Filter by exact template name | |
| after | No | Pagination cursor from a previous response's next_cursor | |
| limit | No | Max templates to return (1-1000, default 50) | |
| status | No | Filter by Meta review status | |
| waba_id | Yes | WhatsApp Business Account ID (numeric) | |
| language | No | Filter by language code (e.g. en, pt_PT, es). Applied client-side. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral details: filters are applied server-side versus client-side, pagination is managed via `after` and `has_more`, and the return structure includes count, templates, and cursor. Since annotations are empty, this description fully carries the burden and does so thoroughly.
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 concise yet well-structured, with a clear opening statement, a 'When to use' section, filter behavior notes, and a return format summary. Every sentence provides useful information without redundancy.
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 6 parameters, no output schema, and no annotations, the description is highly complete. It covers usage scenarios, filter behavior, pagination, and the return shape, giving an agent everything needed to invoke the tool correctly.
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?
All 6 parameters have descriptions in the schema (100% coverage), so baseline is 3. The description adds extra semantics by explaining which filters are server-side vs client-side and the role of `after` in pagination, going beyond the schema. However, it doesn't elaborate on all parameters individually.
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 clearly states the tool 'List message templates for a WhatsApp Business Account (WABA), with optional filters.' It uses a specific verb and resource, and differentiates from sibling tools like wa_create_template, wa_delete_template, and wa_send_template by focusing on listing and discovery.
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 provides explicit usage guidance under 'When to use,' including discovery before sending, auditing, and verifying review status after creation. It also references wa_send_template's requirement for an APPROVED template, offering clear context for when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a pre-approved template message to a recipient on WhatsApp.
When to use: outbound notifications, marketing or utility messages where the recipient is outside the 24-hour customer service window, or any first-contact message.
Requirements:
The template must already exist and be in APPROVED status (use wa_get_templates to verify).
phone_number_id is the numeric ID of YOUR sending number (from wa_get_phone_numbers),
NOT the destination phone.
to must be E.164 (digits only, country code first), e.g. 351912345678.
components_json is required when the template has variables ({{1}}, header media, buttons).
Returns: the WhatsApp message ID (wamid) on success, which can be used with wa_get_message_status.
Limitations: templates with header media require uploaded media handles; delivery/read status is delivered asynchronously via webhooks — this tool returns only the accepted message ID.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Recipient phone number in E.164 format (digits, country code first), e.g. 351912345678 | |
| language_code | Yes | Language/locale code of the template, e.g. en, pt_PT, es_ES | |
| template_name | Yes | Approved template name (lowercase, digits, underscores only) | |
| components_json | No | JSON array of components with parameter values, e.g. [{"type":"body","parameters":[{"type":"text","text":"Alice"}]}] | |
| phone_number_id | Yes | Numeric ID of the sending WhatsApp phone number (from wa_get_phone_numbers) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With empty annotations, the description carries full burden. It discloses the async nature (returns only accepted message ID, status via webhooks), the requirement for APPROVED template, the distinction that phone_number_id is the sender not destination, and the limitation about header media requiring uploaded media handles. This is comprehensive 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 well-organized into 'When to use,' 'Requirements,' 'Returns,' and 'Limitations' sections. Each sentence provides necessary operational information without redundancy. It is concise given the complexity of the tool and the need to clarify common pitfalls (e.g., sender vs recipient ID).
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 5 parameters, no output schema, and empty annotations, the description fully equips an agent: purpose, usage scenarios, prerequisites, parameter clarifications, return value, and limitations. It even addresses asynchronous delivery behavior. No critical information is missing for correct invocation.
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 100%, so the baseline is 3. The description adds extra value by clarifying that phone_number_id is the sender ID 'NOT the destination phone,' and by giving a concrete JSON example for components_json with body parameters. It also notes when components_json is required (variables, header media, buttons), which goes beyond the schema's generic description.
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 opens with a specific verb+resource: 'Send a pre-approved template message to a recipient on WhatsApp.' It clearly distinguishes from siblings like wa_create_template (creation), wa_get_templates (retrieval), and wa_get_message_status (status) by focusing on outbound message delivery.
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 'When to use' section explicitly lists scenarios (outbound notifications, marketing, utility, first-contact) and provides a clear boundary with the 24-hour customer service window. It also references wa_get_templates as a prerequisite verification step. It doesn't name direct sibling alternatives for sending, but the context is strong enough for an agent to decide when to invoke it.
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.
v1.1.0wa_api_callwa_create_templatewa_delete_templatewa_get_business_accountswa_get_message_statuswa_get_phone_numberswa_get_templateswa_send_templateScored across 8 tools
Each tool targets a distinct resource and action: discovery (business accounts, phone numbers, templates), mutation (create/delete/send), and status lookup. No two tools overlap in purpose; wa_api_call is clearly an escape hatch for uncovered endpoints.
All tool names follow a consistent 'wa_verb_noun' pattern (e.g., wa_get_templates, wa_create_template, wa_send_template). The only outlier, wa_api_call, still fits the verb_noun style with 'call' as the verb. Naming is uniform and predictable.
8 tools is a well-scoped number for a WhatsApp Business server. Each tool earns its place in the primary workflow—discovery, template management, sending, and status checking—without unnecessary bloat or obvious missing essentials.
The server covers the core lifecycle: discover accounts/numbers/templates, create/delete templates, send messages, and check message status. Missing an update-template operation, but the wa_api_call escape hatch provides a workaround, so the gap is minor.
WhatsApp (Web + Business API), SMS, contacts, and call records via 2Chat's MCP server.
Unified messaging MCP server: WhatsApp, Instagram, Telegram, SMS, Messenger & email support inbox
Hosted MCP server for the Wavix telecom platform: SMS, voice, 2FA, SIP, numbers, 10DLC, CDRs.
Drive WhatsApp from any MCP client: pair devices, send text and media, manage contacts and groups.
