HellouOne

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. An account sees the calls of the features it has.

Input Schema

Name	Required	Description
`page`	No	Page number, from 1.
`since`	No	Calls created at or after this moment — an ISO 8601 timestamp, or a date (`YYYY-MM-DD`) for the start of that day.
`until`	No	Calls created at or before this moment — an ISO 8601 timestamp, or a date for the end of that day.
`cursor`	No	Sync mode. The `meta.next_cursor` from the previous response.
`fields`	No	Optional: return only these fields of each record.
`status`	No	One status, or several separated by commas.
`inbox_id`	No
`per_page`	No	Calls per page. Values above 100 are treated as 100.
`direction`	No	`incoming` or `outgoing` (`inbound` and `outbound` are accepted too).
`ai_handled`	No	`true` for only the calls an AI agent answered, `false` for only the others.
`contact_id`	No
`agent_bot_id`	No	Only the calls this AI agent answered.
`updated_since`	No	Sync mode. Only calls created or changed at or after this ISO 8601 timestamp, oldest change first.
`conversation_id`	No	The conversation's display ID, as in conversation paths.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedOct 20, 2026

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

First observedOct 11, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, yet the description adds substantial non-obvious behavior: default ordering (newest first) versus sync-mode ordering (oldest change first), the visibility model, and the feature gating (whatsapp_calling, voice_agents) that determines whether an account sees a given call.

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?

Front-loaded with the purpose, then layered constraints, filters, and sync mode in descending order of importance; nearly every sentence carries new information. Some sentences are long and pack multiple clauses, but there is little filler.

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 14-parameter, zero-required list tool with no output schema, the description covers ordering, pagination continuation via cursor, sync semantics, visibility, and feature gating. The only notable omission is the shape of a returned call record, which the absent output schema leaves undocumented.

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 86%, so the baseline is 3, and the description earns above it by explaining the two-parameter sync loop (updated_since combined with cursor until meta.next_cursor is null) and by tying contact_id/conversation_id to the 'customer call history' use case. It does not clarify status, direction, or fields semantics beyond the schema.

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 ('List calls') and immediately bounds the scope: WhatsApp calls plus AI-agent-answered calls on the account's phone lines, newest first. The list vs. single-record distinction against sibling get_call is clear from the verb and the ordering statement.

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 concrete when-to-use guidance: filter by contact or conversation to show a customer's history, pair with call_started/call_ended webhooks to keep another system in step, and pass updated_since plus meta.next_cursor to replicate every call into another system. It also states the visibility precondition (admin sees all, agent sees only permitted conversations).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All HellouOne tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?