Skip to main content
Glama

Turbo Notify: WhatsApp for AI agents

List the messages of a WhatsApp number

list_messages
Read-onlyIdempotent

List messages for one number, newest first, received and sent.

Each item says who it is from and to, which number it belongs to, its direction, content_type, origin, a short preview, at, status and content_expired. Mentions, transcription and full media detail are only on get_message, so fetch the one message you care about rather than paging for detail.

To read a group, find its grp_ id with list_groups and pass it as group_id. contact_id returns what that contact sent or received, which in a group includes what they said there. direction keeps only inbound or outbound. Filters combine: group_id with contact_id answers what one person said in one group.

Ids belong to one number, so use the same number_alias you got them from: an id from another number answers not found. For the next page, pass back the cursor from the previous response together with the same filters.

Content older than the plan's retention window comes back with preview empty and content_expired true. The message, its sender and its group stay listed for 12 months.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_messages"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoHow many items to return, 1-200. Defaults to 50.
cursorNoOpaque cursor for the next page. Pass back the `cursor` from the previous response, with the same filters; omit it for the first page.
group_idNoOnly the messages of one group (`grp_…`, from `list_groups`). The group must be one of this number's: an id from another number answers not found. Can be combined with `contact_id`.
directionNoOnly messages the number received (`inbound`) or sent (`outbound`). Absent means both.
contact_idNoOnly the messages this contact sent or received (`ct_…`, from `list_contacts`). In a group that includes what the contact said there. The contact must be one of this number's: an id from another number answers not found. With `group_id` too, you get what that contact said in that group.
number_aliasNoWhich of the organization's WhatsApp numbers this acts on: `main`, the alias of an extra number, or the number's `id` (`num_…`), which stays the same when the alias is renamed. Call `list_numbers` to see them. Defaults to the main number.main

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.2/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered structurally. The description contributes real behavioral context: retention windows producing empty `preview` with `content_expired` true, ids from another number returning not found, and sender/group staying listed for 12 months. Those are useful additions, but the per-item field list largely restates what the output schema already exposes.

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-loaded with the core action and result shape, then filters, then pagination and retention in a logical order; every paragraph carries information. Mild redundancy between the field enumeration and the detail-pointer sentence, and the retention caveat is elaborated a bit more than needed.

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 filtered, paginated list tool with a full output schema and rich annotations, nothing an agent needs to call it correctly is missing: id provenance, filter combination semantics, alias scoping, cursor round-tripping and expired-content behavior are all covered.

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 baseline is 3; the description still adds cross-parameter meaning the schema only partly captures, notably that `group_id` plus `contact_id` answers "what one person said in one group" and that the same `number_alias` must be reused for ids to resolve. It also restates cursor pagination with matching filters. Marginal but genuine value above the schema.

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 messages for one number") plus ordering and scope ("newest first, received and sent"). The distinction from `get_message` is made explicit, so an agent can separate list-level from detail-level retrieval without opening either schema.

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 explicit routing to `get_message` for mentions/transcription/media detail and to `list_groups`/`list_contacts` for obtaining ids, plus how `direction`, `group_id` and `contact_id` combine. Strong contextual guidance, though it does not explicitly state when *not* to page at all (e.g., when a single known message id exists, `get_message` alone suffices) beyond the detail caveat.

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.