WhatsMCP: MCP for WhatsApp

List Contacts

wa_list_contacts

Read-only

List or search the address book of one of your WhatsApp accounts — the contacts saved on the phone this account is linked to. Pass query to find someone by name or number; matching looks at saved names, the name the contact publishes, business names and the number. Use the returned phone numbers with wa_send_message. Set include_pictures to also get each contact's profile picture URL; that looks the contacts up on WhatsApp, so it returns at most 10 per page and is slower.

Input Schema

Name	Required	Description
`limit`	No	how many to return (default 500, max 2000; max 10 with include_pictures)
`query`	No	optional: only contacts whose name or number contains this; case-insensitive and ignores punctuation in numbers, so '+44 7700 900111' finds 447700900111. Omit to list everything
`account_id`	Yes	which of your accounts to read, from wa_list_accounts
`after_cursor`	No	return contacts after this cursor; omit to start from the beginning
`include_pictures`	No	also return each contact's profile picture URL. This looks every contact on the page up on WhatsApp, so the page is capped at 10 and can take half a minute; leave it off for a fast listing

Output Schema

Name	Required	Description
`note`	No
`total`	Yes	how many contacts matched in total, before the limit was applied
`refusal`	No	present only when the request was declined
`contacts`	Yes
`has_more`	No	true when more contacts remain after this page
`truncated`	No	true when more contacts exist than were returned
`next_cursor`	No	pass this as after_cursor to continue; page until has_more is false to read the whole address book

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 26, 2026

addedOutput schema / properties / refusal / properties / candidates

Added value: +{
+  "description": "on an account_ambiguous refusal: the accounts to choose from — retry with one of these as account_id",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "account_id": {
+        "description": "the id to retry with as account_id",
+        "type": "string"
+      },
+      "name": {
+        "description": "the account's WhatsApp display name",
+        "type": "string"
+      },
+      "phone": {
+        "description": "the account's phone number, E.164",
+        "type": "string"
+      },
+      "status": {
+        "description": "whether the number works right now — live, connecting, or why not, as wa_list_accounts reports it",
+        "type": "string"
+      }
+    },
+    "required": [
+      "account_id"
+    ],
+    "type": "object"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

Changed3 schema fields changedOct 11, 2026

addedOutput schema / properties / refusal / properties / account_status

Added value: +{
+  "description": "when the number is not working: its status — starting, not_running, whatsapp_down, suspended, pairing, unlinked or locked",
+  "type": "string"
+}

addedOutput schema / properties / refusal / properties / account_status_reason

Added value: +{
+  "description": "the detail of account_status, e.g. no_egress, stopped, no_plan",
+  "type": "string"
+}

addedOutput schema / properties / refusal / properties / since

Added value: +{
+  "description": "when the number stopped working, RFC3339, when known",
+  "type": "string"
+}

Changed1 schema field changedSep 22, 2026

addedInput schema / properties / query

Added value: +{
+  "description": "optional: only contacts whose name or number contains this; case-insensitive and ignores punctuation in numbers, so '+44 7700 900111' finds 447700900111. Omit to list everything",
+  "type": "string"
+}

First observedSep 17, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only cover the read-only safety profile, and the description adds genuinely non-obvious behavior: include_pictures triggers live WhatsApp lookups per contact, caps the page at 10, and 'can take half a minute.' That latency/cap tradeoff is exactly the kind of operational trait an agent cannot infer from readOnlyHint.

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?

Four sentences, front-loaded with the core action, then query semantics, then the forward reference, then the costly optional flag. Every sentence carries information, though the include_pictures explanation overlaps heavily with the schema's own description of that parameter.

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 read-only list tool with an output schema, 100% parameter coverage, and 5 params, the description covers purpose, matching semantics, the performance trap, and the downstream use of results. Nothing needed to call it correctly 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 baseline is 3; the description earns above that by disclosing match fields the schema omits — 'saved names, the name the contact publishes, business names and the number.' It restates include_pictures and cursor behavior already well documented in the schema, so it doesn't reach 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?

States a specific verb+resource with scope: 'List or search the address book of one of your WhatsApp accounts — the contacts saved on the phone this account is linked to.' That scoping sentence alone separates it from wa_list_blocked, wa_list_group_members, and wa_get_profile, so an agent can pick the right tool without opening schemas.

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

Usage Guidelines4/5

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

Explicitly tells the agent when to pass query ('to find someone by name or number; omit to list everything') and when to set include_pictures (only when picture URLs are needed, at a page/latency cost). It also routes forward with wa_send_message. It stops short of naming competing tools (wa_list_blocked, wa_get_chat) or stating when this tool is the wrong choice.

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

All WhatsMCP: MCP for WhatsApp tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?