Skip to main content
Glama

Measure a chat's earlier history

start_history_preview
Idempotent

Measure how much earlier history a WhatsApp chat has — before or after it is captured — and get the options to capture it. Measuring is free and reads metadata only, but takes minutes: the first call starts it and answers measuring; call again in 1–3 minutes to read progress, never in a loop. Once a day is counted in full, options appear, each with how many messages, media, bytes and voice-note minutes it brings and its price; all history is on offer once the status is ready. Pass from_date to also get one exact day. A stopped, canceled, failed or unanswered measure stays as it is: continue or retry it only when the user asks, with continue: true. Pass a list of up to 100 chat_ids for a metadata-only batch of chats not captured yet. 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. 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_history_preview"
  }
}

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 for a batch. Pass exactly one of chat_id, contact_phone and chat_name.
continueNoContinue a stopped measure, or retry a failed or unanswered one. Only when the user asks; default false.
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_dateNoOptional YYYY-MM-DD: also answer the option starting on this day.
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
statusNoqueued | measuring | stopped | not_measured | phone_unanswered | failed | nothing_earlier | ready | limit_reached | captured
optionsNo
resultsNoBatch only: one per distinct chat_id, in input order, metadata only.
currencyNoThe currency of every price below.
help_urlNoHow earlier history and its cost work, for the user. Only for a captured chat.
next_stepNoWhat to tell the user, and do, for this status.
estimate_idNoWhen the chat is not captured: its measure.
measured_atNoReady: when the measure finished (ISO 8601).
current_fromNoWhen the chat is captured: the local day its capture starts from.
messages_seenNoMessages examined so far while measuring; not messages captured.
available_fromNoReady: the earliest day WhatsApp served.
estimates_usedNo
failure_reasonNorequest_failed | phone_unanswered.
conversation_idNoWhen the chat is captured: the conversation the read tools take.
counted_back_toNoBefore ready: the earliest local day counted in full; no option goes earlier.
reached_back_toNoEarliest local day examined so far.
available_throughNoReady: the newest day measured.
estimates_remainingNoRemaining measure allowance; null when measures are not limited.
estimate_queue_positionNo1-based position while queued.
included_in_subscriptionNoTrue when this number's subscription covers the history: nothing is charged.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.4/5.0
Behavior4/5

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=true; the description explains why it isn't read-only by disclosing that the first call starts a minutes-long measure, and adds cost/latency ('measuring is free, reads metadata only, takes minutes'), the cadence for polling, and what a stopped/canceled/failed measure retains. It also documents a specific error path (currency_selection_required) with a required user-confirmation gate. Minor gap: no rate-limit or concurrency note for parallel measures.

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-loads purpose well and every clause carries real information, but it is a single dense paragraph of long run-on sentences mixing polling cadence, pricing, batch mode, and error handling. Splitting into short lines or bullets would make the operational rules far easier to scan without losing content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an async, stateful measure tool with an output schema, the description covers the job lifecycle (start, poll, stopped/canceled/failed), what returned options contain, batch mode, and the currency error recovery path. The output schema handles return-value detail, so this is nearly complete; only concurrency behavior for multiple simultaneous measures is unaddressed.

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; the description earns above that by clarifying from_date ('also get one exact day'), continue ('only when the user asks'), the mutual-exclusivity of chat_id/contact_phone/chat_name, and that phone may be omitted for a single-number user. The chat_id batch limit of 100 is repeated rather than added, but the interaction semantics are genuinely enriched.

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 ('measure how much earlier history a WhatsApp chat has') and adds scope ('before or after it is captured') plus what it returns ('the options to capture it'). This clearly separates it from start_history_capture or stop_history_preview, which an agent can now infer do the actual capturing/stopping rather than measuring.

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?

Gives explicit when/when-not: first call starts the measure, call again in 1–3 minutes for progress, never in a loop; continue/retry only when the user asks. Also names the prerequisite tool for chat identification (list_capturable_chats) and the batch-mode condition (up to 100 chat_ids not yet captured).

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