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

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.

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.4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true and idempotentHint=false, so the safety profile is covered. The description adds valuable behavioral detail beyond annotations: include_pictures triggers a WhatsApp lookup that caps the page at 10 and slows performance, affecting pagination and latency. This is extra context that helps the agent anticipate side effects.

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

Conciseness5/5

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

The description is tight, with four sentences each carrying distinct information. It front-loads the core purpose, then covers query behavior, output usage, and the include_pictures caveat in order of importance. No filler or redundancy.

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

Completeness4/5

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

For a list tool with an output schema, the description covers the essential operational aspects: what it returns, how to filter, and a key performance tradeoff. It doesn't need to spell out return fields since the output schema exists. It could mention cursor pagination, but that is documented in the schema, so the context is complete for practical use.

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 all parameters are described. The description adds meaning beyond the schema by explaining that query matching checks saved names, published names, business names, and numbers—going deeper than the schema's 'name or number' phrasing. It also explains the tradeoff of include_pictures, which the schema only states as a cap and speed note. This adds genuine value.

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?

The description clearly states the verb and resource: 'List or search the address book of one of your WhatsApp accounts'. It distinguishes this from other list tools (wa_list_calls, wa_list_messages) by focusing specifically on contacts saved on the phone. It also ties the output to a concrete next step with wa_send_message, reinforcing the tool's purpose.

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?

It provides clear context about what the tool operates on—contacts saved on the linked phone—and mentions using the returned numbers with wa_send_message. However, it does not explicitly contrast with sibling tools like wa_list_group_members or wa_list_blocked, nor does it state when not to use it. Still, the usage context is clear enough for an agent to know when to pick this tool.

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?