Skip to main content
Glama

Start capturing a chat

start_capture
Idempotent

Deprecated: start_live_capture starts a chat's new messages from today and replaces this tool when no history is asked for. Start capturing one chat from a connected WhatsApp number. By default it starts from today, exactly as before. After start_history_preview returns ready, it can instead include one history option only when you echo that estimate's id, date, transcription choice and exact price after showing them to the user and getting explicit agreement. A user who will not wait for an estimate can instead ask for the chat's earlier history with all_history, which takes no quote. On a number the wallet funds, that is the chat's whole available history, billed as it arrives until the wallet runs out, at which point capture pauses until funds are added. New messages land in a Werify conversation as they arrive and are metered against the user's wallet. A positive balance is enough; auto-topup with a card is the other funding option. One chat per call, named as list_capturable_chats returns it: by its chat_id, its contact_phone or its name as chat_name. A new account starts with free capture: its first chats on one number capture at no charge, for a limited time. Every other capture, and every capture once free capture ends, is paid from the account's balance or by that number's subscription. list_connected_numbers says what funds each number, and what to tell the user, in its funding_note. On a number with a subscription, all_history brings the chat's whole available history too, included in the subscription. Under free capture it brings a sample of the chat's history rather than all of it, and history_hint says how much. If this tool answers an error whose code is currency_selection_required, the user has not confirmed the account's currency: show them the action_url and do not retry until they say it is done.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "phone": "<phone>"
    },
    "name": "start_capture"
  }
}

Input Schema

NameRequiredDescriptionDefault
phoneYesThe connected number, from list_connected_numbers.
chat_idNoThe chat to capture, by the chat_id list_capturable_chats returns for it. Pass exactly one of chat_id, contact_phone and chat_name.
chat_jidNoDeprecated and removed in a later version: name the chat by chat_id, contact_phone or chat_name instead.
chat_nameNoThe chat to capture, by its name exactly as list_capturable_chats returns it. When two chats share the name, the call is refused with both and their chat_ids. Pass exactly one of chat_id, contact_phone and chat_name.
transcribeNoTranscribe voice notes (default false), including selected history when requested. Billed per audio minute.
all_historyNoDefault false. Brings this chat's earlier history with no quote. How much arrives depends on what funds the number, as this tool's description says. On a number the wallet funds it is the chat's whole available history, billed to the wallet as it arrives until the balance runs out — capture on the number then pauses until funds are added, so suggest auto-topup. Set it true only after the user explicitly agreed to what it brings and what it draws on. Cannot be combined with include_history.
estimate_idNoRequired when include_history is true: the id returned by start_history_preview.
contact_phoneNoThe chat to capture, when it is a 1:1: the other party's number in E.164, as list_capturable_chats returns it. Pass exactly one of chat_id, contact_phone and chat_name.
include_historyNoDefault false. Set true only after showing one ready estimate history option and getting explicit agreement.
history_from_dateNoWhen include_history is true: the selected option's exact YYYY-MM-DD. Omit/null only for all available measured history.
quoted_history_centsNoRequired when include_history is true: echo the exact cents price shown for the same date and transcription choice.

Output Schema

NameRequiredDescriptionDefault
chat_nameNoThe chat's name; null when the phone sent none.
transcribeNoWhether voice notes arriving from now on are transcribed.
all_historyNoTrue when this call started an all-history capture with no quote (all_history: true).
history_hintNoWhat to do next about the chat's earlier history.
captures_fromNoThe local day the capture starts from (YYYY-MM-DD). For an all-history capture this is today: how far back it reaches is the phone's to decide.
contact_phoneNoThe 1:1's other party in E.164; null for a chat with no number, as a group.
conversation_idNoThe conversation the capture feeds — the id the read tools take.
conversation_urlNo
history_includedNoTrue only when this call started capture with the explicitly agreed history option.
already_capturingNoTrue when this chat was already being captured; nothing changed.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Well beyond the annotations: discloses that capture is metered against the wallet, that `all_history` bills as data arrives and pauses capture when funds run out, that free capture gives only a sample, and that subscriptions change what `all_history` brings. With idempotentHint=true already declared, the description correctly does not re-explain idempotency. It stops short of describing the response payload, but an output schema exists.

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

Conciseness3/5

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

Front-loaded with the deprecation, which is the right choice, but the body is long and loops back over funding and `all_history` behavior twice ('On a number the wallet funds...' and again later for subscriptions and free capture). Several clauses, such as the `all_history` explanation, are largely duplicated in the parameter schema, costing the reader without adding new information.

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 an 11-parameter, billing-sensitive, deprecated-but-live tool, the description covers funding sources, free-capture limits, history options, chat identification, and the currency-confirmation error, and it points to `list_connected_numbers`/`funding_note` and `list_capturable_chats` for the surrounding state. An output schema exists, so return values need not be described.

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 real cross-parameter meaning: `all_history` vs `include_history` is mutually exclusive, the estimate path requires echoing id, date, transcription choice and exact price, and what `all_history` actually yields depends on the number's funding (wallet vs subscription vs free capture, with `history_hint`). That is semantics the schema alone does not express.

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?

Opens with a precise deprecation statement naming the replacement (`start_live_capture`) and the condition ('when no history is asked for'), then states the specific action: 'Start capturing one chat from a connected WhatsApp number.' An agent can distinguish this from start_live_capture, start_history_preview and start_history_capture without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing: use start_live_capture when no history is needed; use the estimate path only after `start_history_preview` returns `ready` and the user agrees; use `all_history` when the user will not wait for an estimate. It also gives an error-handling rule (`currency_selection_required` -> show `action_url`, do not retry), which is when-to-use guidance at the failure boundary.

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