Skip to main content
Glama

List calls

list_calls
Read-onlyIdempotent

List calls. Call history, newest first: WhatsApp calls and the calls AI agents answered on the account's phone lines. A call is visible exactly when its conversation is: an administrator sees every call in the account, an agent only the calls of conversations their visibility setting lets them open. Filter by contact or conversation to show a customer's call history; pair with the call_started and call_ended webhooks to keep another system in step. To copy every call into another system, pass updated_since and then each response's meta.next_cursor as cursor until it is null: you get every call created or changed since, oldest change first. Requires feature: whatsapp_calling for WhatsApp calls, voice_agents for AI calls, voice_integrations for calls imported from your own voice workspace. An account sees the calls of the features it has.

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

Input Schema

NameRequiredDescriptionDefault
pageNoPage number, from 1.
sinceNoCalls created at or after this moment — an ISO 8601 timestamp, or a date (`YYYY-MM-DD`) for the start of that day.
untilNoCalls created at or before this moment — an ISO 8601 timestamp, or a date for the end of that day.
cursorNoSync mode. The `meta.next_cursor` from the previous response.
fieldsNoOptional: return only these fields of each record.
statusNoOne status, or several separated by commas.
inbox_idNo
per_pageNoCalls per page. Values above 100 are treated as 100.
directionNo`incoming` or `outgoing` (`inbound` and `outbound` are accepted too).
ai_handledNo`true` for only the calls an AI agent answered, `false` for only the others.
contact_idNo
agent_bot_idNoOnly the calls this AI agent answered.
evaluation_idNoAn objective of the AI agents (its `id` in the AI call report's `options.evaluation_criteria`). Send it together with `evaluation_result`.
updated_sinceNoSync mode. Only calls created or changed at or after this ISO 8601 timestamp, oldest change first.
conversation_idNoThe conversation's display ID, as in conversation paths.
evaluation_resultNoOnly AI calls where the objective had this result. Send it together with `evaluation_id`; one without the other is refused with `invalid_evaluation`.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedInput schema / properties / evaluation_id
      Added value: +{
      +  "description": "An objective of the AI agents (its `id` in the AI call report's `options.evaluation_criteria`). Send it together with `evaluation_result`.",
      +  "pattern": "^[a-zA-Z0-9_-]{1,80}$",
      +  "type": "string"
      +}
    • addedInput schema / properties / evaluation_result
      Added value: +{
      +  "description": "Only AI calls where the objective had this result. Send it together with `evaluation_id`; one without the other is refused with `invalid_evaluation`.",
      +  "enum": [
      +    "success",
      +    "failure",
      +    "uncertain",
      +    "unknown"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / properties / fields / items / enum
      Previous value: -[
      -  "id",
      -  "provider",
      -  "direction",
      -  "status",
      -  "end_reason",
      -  "duration_seconds",
      -  "created_at",
      -  "started_at",
      -  "ended_at",
      -  "from_number",
      -  "to_number",
      -  "inbox",
      -  "contact",
      -  "conversation_id",
      -  "message_id",
      -  "accepted_by_agent",
      -  "recording_url",
      -  "recording_duration_s",
      -  "ai_handled",
      -  "engine",
      -  "agent_bot",
      -  "voice_line_id",
      -  "sentiment",
      -  "call_outcome",
      -  "dial_cause",
      -  "campaign_id",
      -  "campaign_contact_id",
      -  "updated_at"
      -]New value: +[
      +  "id",
      +  "provider",
      +  "direction",
      +  "status",
      +  "end_reason",
      +  "duration_seconds",
      +  "created_at",
      +  "started_at",
      +  "ended_at",
      +  "from_number",
      +  "to_number",
      +  "inbox",
      +  "contact",
      +  "conversation_id",
      +  "message_id",
      +  "accepted_by_agent",
      +  "recording_url",
      +  "recording_duration_s",
      +  "ai_handled",
      +  "engine",
      +  "agent_bot",
      +  "voice_line_id",
      +  "parent_call_id",
      +  "ai_transfer_hop",
      +  "sentiment",
      +  "call_outcome",
      +  "dial_cause",
      +  "disposition_gap",
      +  "campaign_id",
      +  "campaign_contact_id",
      +  "campaign_interest",
      +  "updated_at"
      +]
  2. Changed5 schema fields changed
    • addedInput schema / properties / agent_bot_id
      Added value: +{
      +  "description": "Only the calls this AI agent answered.",
      +  "type": "integer"
      +}
    • addedInput schema / properties / ai_handled
      Added value: +{
      +  "description": "`true` for only the calls an AI agent answered, `false` for only the others.",
      +  "enum": [
      +    "true",
      +    "false"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / cursor
      Added value: +{
      +  "description": "Sync mode. The `meta.next_cursor` from the previous response.",
      +  "type": "string"
      +}
    • changedInput schema / properties / fields / items / enum
      Previous value: -[
      -  "id",
      -  "provider",
      -  "direction",
      -  "status",
      -  "end_reason",
      -  "duration_seconds",
      -  "created_at",
      -  "started_at",
      -  "ended_at",
      -  "from_number",
      -  "to_number",
      -  "inbox",
      -  "contact",
      -  "conversation_id",
      -  "message_id",
      -  "accepted_by_agent",
      -  "recording_url"
      -]New value: +[
      +  "id",
      +  "provider",
      +  "direction",
      +  "status",
      +  "end_reason",
      +  "duration_seconds",
      +  "created_at",
      +  "started_at",
      +  "ended_at",
      +  "from_number",
      +  "to_number",
      +  "inbox",
      +  "contact",
      +  "conversation_id",
      +  "message_id",
      +  "accepted_by_agent",
      +  "recording_url",
      +  "recording_duration_s",
      +  "ai_handled",
      +  "engine",
      +  "agent_bot",
      +  "voice_line_id",
      +  "sentiment",
      +  "call_outcome",
      +  "dial_cause",
      +  "campaign_id",
      +  "campaign_contact_id",
      +  "updated_at"
      +]
    • addedInput schema / properties / updated_since
      Added value: +{
      +  "description": "Sync mode. Only calls created or changed at or after this ISO 8601 timestamp, oldest change first.",
      +  "format": "date-time",
      +  "type": "string"
      +}
  3. First observed

TDQS

A4.2/5.0
Behavior5/5

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

The annotations already declare this a read-only, idempotent, non-destructive operation, so the bar is low, and the description clears it by disclosing the visibility model (admins see all calls, agents only those their setting permits), ordering rules (newest first for browsing, oldest change first for sync), the cursor-until-null loop, and per-feature gating (`whatsapp_calling`, `voice_agents`, `voice_integrations`). These are permission and sequencing facts an agent cannot get from the annotations.

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?

The purpose is front-loaded in the first clause, followed by visibility, usage, sync mechanics, and feature requirements in a logical order. It is dense but nearly every sentence carries operational information; only the feature-gate sentence is somewhat tangential to invocation.

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 a 16-parameter read tool with no output schema, the description covers the hard parts: two distinct paging modes, visibility scoping, filtering intent, and feature prerequisites. It never addresses how `page` behaves once a `cursor` is supplied, which is the one ambiguity a caller could hit.

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 already 88%, so the schema carries most parameter meaning. The description still adds value by explaining that `updated_since` and `cursor` together form a distinct sync mode with its own ordering, and by framing `contact_id`/`conversation_id` as the intended way to pull one customer's history rather than just listing field names.

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?

The description names a specific verb and resource and pins down scope precisely: WhatsApp calls plus calls AI agents answered on the account's phone lines, returned newest first. It never distinguishes itself from the similarly named `list_call_history` sibling, so an agent choosing between the two still has to guess.

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?

It gives concrete usage scenarios: filter by contact or conversation for a customer's call history, pair with the `call_started`/`call_ended` webhooks to keep another system in step, and use `updated_since` plus `meta.next_cursor` to bulk-copy calls. It stops short of explicit when-not guidance or routing away from an alternative tool.

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