Skip to main content
Glama

List campaign recipients

list_whatsapp_campaign_recipients
Read-onlyIdempotent

List campaign recipients. The campaign's recipients in the order they were added, with their delivery state. Paginated: 100 per page by default, at most 500. Recipients exist once the campaign has been materialized or a CSV has been imported. To follow delivery and replies from another system, pass updated_since and then each response's meta.next_cursor as cursor until it is null: you get every recipient whose state changed, oldest change first. replied=true keeps only the recipients who answered; conversation_display_id opens their conversation. Administrators only. Requires feature: whatsapp_campaigns.

Input Schema

NameRequiredDescriptionDefault
idYesID of the campaign
pageNoPage number, from 1.
cursorNoSync mode. The `meta.next_cursor` from the previous response.
fieldsNoOptional: return only these fields of each record.
repliedNo`true` for only the recipients who replied.
stage__NoOnly recipients whose reply is in these lead stages (campaign reply qualification). `unscored` also matches replies not assessed yet. Unknown values are ignored.
per_pageNoRecipients per page. Values above 500 are capped at 500.
status__NoOnly recipients in these statuses. Unknown values are ignored.
updated_sinceNoSync mode. Only recipients created or changed at or after this ISO 8601 timestamp, oldest change first.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial context beyond them: pagination defaults and caps (100 default, max 500), the materialization/CSV precondition for recipients existing, the admin-only restriction, the `whatsapp_campaigns` feature requirement, and the ordering guarantee of sync mode ('oldest change first').

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?

Front-loaded with the core purpose, then ordered from preconditions to paging to sync mode to permissions. Every sentence carries operational information; nothing is padding.

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?

With no output schema, the description does much of the return-value work by naming `meta.next_cursor` and describing per-recipient delivery state and change ordering. It stops short of enumerating what a recipient record contains, which is the remaining gap for a read tool whose schema exposes no response shape.

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 the baseline is 3, but the description adds genuine meaning: `cursor` is explained as part of a loop driven by the previous response's `meta.next_cursor` (beyond the schema's terse one-liner), and `replied`/`conversation_display_id` are given intent. It still omits the multi-value filters (`status__`, `stage__`) and field selection behavior.

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 ('List campaign recipients') and immediately scopes what is returned: 'the campaign's recipients in the order they were added, with their delivery state.' The recipient-level granularity distinguishes it from sibling tools like list_whatsapp_campaigns and get_whatsapp_campaign, which operate on campaigns themselves.

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 strong conditional guidance: recipients only exist 'once the campaign has been materialized or a CSV has been imported,' and it explains the incremental-sync pattern (pass `updated_since`, then loop `meta.next_cursor` as `cursor` until `null`). It never names an alternative tool to use instead, so it falls short of the explicit when-not/alternatives bar for a 5.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources