Skip to main content
Glama

Turbo Notify: WhatsApp for AI agents

List the contacts of a WhatsApp number

list_contacts
Read-onlyIdempotent

List the people this number has exchanged messages with.

Filter by phone or by name. They are separate filters, not one search box: name matches the contact's name, phone matches the number.

source restricts to how the contact first appeared: inbound (they messaged this number), outbound (this number messaged them), mention (named in a group message) or self (the number's own contact card).

contacted_in_cycle=true narrows the list to exactly the people counting against this number's contact quota this billing cycle: those messaged through Turbo Notify inside the cycle, whether newly or again. Use it to see what the quota gauge is actually counting.

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_contacts"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNoOnly contacts whose name matches.
limitNoHow many items to return, 1-200. Defaults to 50.
phoneNoOnly contacts whose phone number matches.
cursorNoOpaque cursor for the next page. Pass back the `cursor` from the previous response, with the same filters; omit it for the first page.
sourceNoOnly contacts that first appeared this way: `inbound` (they messaged this number), `outbound` (this number messaged them), `mention` (named in a group message) or `self` (the number's own contact card).
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
contacted_in_cycleNoWhen true, return only the people who count against this number's contact quota in the current billing cycle: those messaged through Turbo Notify inside the cycle, new or returning. Use it to see exactly what the quota figure is counting.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds genuine behavioral nuance beyond that: the filters compose as independent constraints rather than a single search box, and contacted_in_cycle is scoped to 'this billing cycle' and 'messaged through Turbo Notify', which explains a non-obvious filtering rule. It leaves pagination/return shape unexplained, but the output schema covers that.

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 purpose, then organized into one paragraph per filter family, which mirrors how an agent would think about the parameters. Some passages restate the schema's own enum descriptions for source and contacted_in_cycle nearly verbatim, which is modest redundancy rather than harmful padding.

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 zero-required-parameter, read-only listing tool with an output schema and rich annotations, the description covers the non-obvious parts an agent needs: filter composition, source semantics, and quota-cycle scoping. Return values and pagination are delegated appropriately to the output schema and the cursor param description.

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 earns credit by disambiguating the semantics that the schema documents only superficially: 'They are separate filters, not one search box: name matches the contact's name, phone matches the number.' It also expands on what contacted_in_cycle actually includes (new or returning contacts inside the cycle). It does not touch number_alias, which the schema already explains.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'List the people this number has exchanged messages with', which is clearly a contact-enumeration read and is distinguishable from message-listing siblings by the resource noun. It never explicitly names a sibling (e.g. get_contact or list_messages) to sharpen the boundary, so it falls short of a 5.

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 concrete usage context for two filters — 'Use it to see what the quota gauge is actually counting' for contacted_in_cycle — which tells the agent when that flag matters. It does not say when to prefer a sibling such as get_contact for a single person, so there are no explicit exclusions or alternatives.

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.