Skip to main content
Glama
pghdma

CallRail MCP

by pghdma
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

list_calls

List calls. Paginated. Filterable by company, date window, and answer status.

Instructions

List calls. Paginated. Filterable by company, date window, and answer status.

Args: account_id: Auto-resolves if omitted. company_id: Filter to one company. Omit for all companies. days: Lookback in days (default 7). Ignored if start_date provided. start_date: 'YYYY-MM-DD'. end_date: 'YYYY-MM-DD' (defaults to today). answer_status: Server-side filter. One of 'answered', 'missed', 'voicemail'. This is CallRail's real filter parameter. answered: DEPRECATED alias kept for backwards compatibility. 'true' maps to answer_status='answered', 'false' to 'missed'. (CallRail has no answered query param; passing it used to be silently ignored, so results were unfiltered.) source: CallRail has NO server-side source filter, so this is applied CLIENT-SIDE to the current page only: the calls array is filtered by exact, case-insensitive match on each call's source field. total_records/total_pages in the response still describe the UNFILTERED query. See source_filter in the response for what was actually applied. For source breakdowns prefer call_stats(group_by='source'). per_page: Max 250. page: 1-indexed. fields: Comma-separated additional fields to include, e.g. 'company_name,source_name,keywords,landing_page_url,device_type, first_call,value,tags,note,gclid,fbclid,utm_source,utm_medium, utm_campaign,utm_content,utm_term,referrer_domain'.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
daysNo
pageNo
fieldsNo
sourceNo
answeredNo
end_dateNo
per_pageNo
account_idNo
company_idNo
start_dateNo
answer_statusNo

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.2.2
    • addedInput schema / properties / answer_status
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Answer Status"
+}
  2. First observedv1.0.0

TDQS

A4.9/5.0
Behavior5/5

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

With no annotations present, the description fully discloses important behaviors: pagination, default values (days=7, end_date=today), the client-side filtering of `source` and its impact on `total_records`/`total_pages`, the deprecated `answered` parameter and its mapping, and the fact that `source` is not a server-side filter, so results may be unfiltered if used incorrectly. This is transparent about edge cases.

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 description is structured with a clear overview and a detailed args list, but it is lengthy due to the extensive parameter documentation. The key points are front-loaded, and the detail is necessary given the lack of schema descriptions, but it could be tightened by removing some redundancy in the `fields` example list. Still, it is well-organized and readable.

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?

The description is highly complete for a complex tool with 11 parameters and an output schema. It covers parameter behavior, defaults, edge cases, and even directs to alternative tools for better functionality (e.g., `call_stats` for source breakdowns). The output schema presumably covers the response format, so nothing essential is missing for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% coverage (no descriptions within the schema), so the tool description must fully document each parameter. It does so comprehensively: explains `account_id` auto-resolution, `days` lookback, `start_date`/`end_date` formats, `answer_status` server-side filter, `answered` deprecation, `source` client-side behavior, `per_page` max, `page` 1-indexed, and `fields` comma-separated list with examples. This goes well beyond what the schema provides.

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 clearly indicates the tool lists calls, with explicit mention of pagination and filterable parameters (company, date window, answer status). It stands out from siblings like get_call (which retrieves a single call) and search_calls_by_number, providing a distinct purpose of listing many calls with filters.

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?

The description gives explicit usage guidance: explains that `days` is ignored if `start_date` is provided, that `source` is applied client-side and explains its limitations, and that `answered` is deprecated in favor of `answer_status`. It also clarifies when to use `call_stats(group_by='source')` for source breakdowns, offering alternative routing.

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

Deploy Server

Other Tools