Skip to main content
Glama

Start capturing a chat's new messages

start_live_capture
Idempotent

Start capturing the new messages of WhatsApp chats from today on: today's messages from before the call are brought in too, as in Werify's "From today". It brings no earlier history; for that, use start_history_capture. Obtain the user's agreement first. A chat already capturing is left as it is; a stopped one resumes in its conversation. Pass a list of up to 100 chat_ids to start several. Name the chat with chat_id, contact_phone or chat_name from list_capturable_chats; phone may be omitted when the user has a single number. 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. 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

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": "start_live_capture"
  }
}

Input Schema

NameRequiredDescriptionDefault
phoneNoThe connected number, from list_connected_numbers. Omit it when the user has a single connected number.
chat_idNoThe chat, by the chat_id list_capturable_chats returns, or a list of 1–100 of them. Pass exactly one of chat_id, contact_phone and chat_name.
chat_nameNoThe chat, by its name exactly as list_capturable_chats returns it. Pass exactly one of chat_id, contact_phone and chat_name.
transcribeNoTranscribe the voice notes that arrive. Omitted: false on a new chat, unchanged on a resumed one.
contact_phoneNoThe chat, when it is a 1:1: the other party's number in E.164. Pass exactly one of chat_id, contact_phone and chat_name.

Output Schema

NameRequiredDescriptionDefault
resultsNoBatch only: one per distinct chat_id, in input order.
chat_nameNo
transcribeNoWhether arriving voice notes are transcribed.
captures_fromNoThe local day the capture starts from (YYYY-MM-DD); null for all history.
contact_phoneNoA 1:1's other party in E.164; null otherwise.
conversation_idNoThe conversation the capture feeds.
conversation_urlNo
already_capturingNoTrue when nothing changed.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior4/5

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

The annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=true, but the description adds real behavioral context beyond them: the exact backfill boundary (today's prior messages included, no earlier history), what happens to an already-capturing chat (left as is) and a stopped one (resumes in its conversation), and that starting a capture can incur cost. Pricing is described at a conceptual level (free capture for a new account, then balance or subscription) but defers specifics to list_connected_numbers' funding_note, which is reasonable delegation rather than omission.

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?

It is a single dense paragraph, but it is front-loaded: purpose and scope come first, then alternatives, then consent, idempotency, identifiers, billing and the error path. Every sentence carries information, though the run-on block of billing and error clauses makes it slower to scan than a segmented layout would.

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 tool with an output schema and full annotation coverage, this is complete: scope, alternatives, idempotency semantics, identifier sourcing, multi-chat batching, cost implications and a specific blocking error with its recovery procedure are all present. Nothing an agent needs in order to call it correctly is missing.

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, and the description mostly echoes the schema's identifier guidance (chat_id, contact_phone, chat_name). It does add meaning beyond the schema by stating the batch intent (pass a list of up to 100 chat_ids to start several), which frames the array form as a batching mechanism rather than incidental, and by pointing at list_capturable_chats as the value source. The transcribe parameter is not discussed at all, which is a gap, but the schema documents its defaults well.

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 opening sentence names a specific verb and resource (start capturing new messages of WhatsApp chats) and immediately delimits scope: today's messages from before the call are included, no earlier history. It explicitly names the sibling that handles the other case, start_history_capture, so an agent can route 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 Guidelines5/5

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

Explicit when-to-use (new messages from today), when-not (earlier history → start_history_capture), prerequisite (obtain the user's agreement first), and an error path: on currency_selection_required, show action_url and do not retry until the user confirms. It also explains how to name the chat via list_capturable_chats values, and states phone may be omitted with a single number.

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