Skip to main content
Glama

Capture a chat's earlier history

start_history_capture

Capture a WhatsApp chat's earlier history, after the user picked an option start_history_preview served for that chat: pass that option's from_date, or "all". A date is accepted only if start_history_preview served it for this chat, at the quote it served; if the window moved since, the call is refused with the option as it stands now, to show the user and ask again. "all" over a measure that has not finished, or a chat never measured, brings all the history the phone has with no quote: on a number the wallet pays for it consumes the balance as it arrives and pauses when it runs out, so tell the user that first. Works on a chat not captured yet, one capturing, or one stopped. Without with_live_capture, new messages are left as they are: a chat not captured yet gets only its history. transcribe applies to this history and becomes the chat's voice-note choice, as on the web. 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. 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": {
      "from_date": "<from_date>"
    },
    "name": "start_history_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. 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.
from_dateYesThe option's from_date (YYYY-MM-DD) as start_history_preview served it, or "all".
transcribeNoTranscribe this history's voice notes; default false.
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.
with_live_captureNoAlso capture the chat's new messages from now on, as start_live_capture; default false.

Output Schema

NameRequiredDescriptionDefault
noteNoWhat happens next, to tell the user.
declinedNoTrue when the confirmation form came back declined; nothing was captured.
chat_nameNo
from_dateNoThe day the history brought in starts (YYYY-MM-DD); null for all history with no quote, and under free capture.
funded_byNosubscription | free_capture | wallet
transcribeNoThe chat's voice-note choice after this call, for this history and the new messages.
audio_countNoVoice notes this history transcribes.
message_countNoMessages in the window; null when unmeasured.
conversation_idNo
conversation_urlNo
free_capture_sampleNoUnder free capture: the sample that arrives instead of the window.
capturing_new_messagesNoWhether the chat's new messages are captured after this call.

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?

With only generic annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), the description carries real burden and delivers: quote invalidation causes refusal with the current option to show the user, 'all' on an unfinished or never-measured chat consumes paid balance and pauses when it runs out, and free capture yields only a sample sized by history_hint. It does not state whether a started capture is resumable after refusal or how long it runs, which keeps it from a 5.

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?

Nearly every sentence carries non-redundant information, but the whole thing is a single dense block of long comma-chained clauses mixing quoting rules, billing, transcription, chat naming, and error handling. Front-loading is fine, yet structure (grouping or breaks between the rules) would materially improve scannability without cutting content.

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 7-parameter, non-idempotent, billable capture operation with an output schema present, the description covers preconditions, all chat-identifier options, the transcribe and live-capture side effects, billing consequences, and the one documented error path. Nothing an agent needs in order to call it correctly appears to be 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, but the description genuinely adds semantics: from_date is not a free date but one previously served for this chat at the served quote, 'all' behaves differently by finished/unfinished measure and by subscription vs free capture, and transcribe becomes the chat's voice-note choice. These distinctions are not visible in the schema's 'default false' wording.

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 description opens with a specific verb and resource — 'Capture a WhatsApp chat's earlier history' — and immediately positions it relative to start_history_preview, whose served option it consumes. An agent can distinguish it from start_capture/start_live_capture without reading 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?

It states the precondition (the user picked an option that start_history_preview served for that chat), what values are admissible (that option's from_date, or 'all'), and which chat states it works on (not captured yet, capturing, stopped). It also routes with_live_capture to start_live_capture behavior and gives an explicit do-not-retry rule for the currency_selection_required error.

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