whatsmcp

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

TableJSON 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

TableJSON 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.

Changed3 schema fields changedOct 14, 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"
+}

First observedSep 27, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes well beyond the readOnlyHint annotation by disclosing real side effects and costs: include_pictures performs external WhatsApp lookups, caps results at 10 per page, and can take half a minute. It also specifies matching scope (saved names, published name, business names, number).

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

Conciseness4/5

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

Front-loads the core purpose and then layers search behavior and the include_pictures caveat; every sentence carries information. The first sentence's em-dash aside is slightly dense, but there is no filler.

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?

With an output schema present, an accurate readOnlyHint annotation, and 100% schema coverage, the description need not explain return values. It supplies exactly the extra behavioral context an agent needs (search scope, performance tradeoff, downstream usage) to call it correctly.

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 description coverage is 100%, so the baseline is 3, but the description adds meaning not in the schema about what query actually matches against (saved names, contact-published names, business names, number) and reinforces the include_pictures cap. It adds value but does not fully restate cursor/limit semantics.

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 and resource with precise scope: the address book of one account, i.e. contacts saved on the linked phone. It also distinguishes the 'list everything' vs 'search' mode, making it clearly different from siblings like wa_list_accounts or wa_list_blocked.

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?

Gives clear context for both modes (pass query to search, omit to list) and even a downstream workflow (use returned numbers with wa_send_message), plus when to enable include_pictures. It stops short of naming alternatives or explicit exclusions (e.g. use wa_list_blocked for blocked contacts), so not a full 5.

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

All whatsmcp 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?