Tools Overview

The Cometly MCP server exposes 50 read-only tools across 14 toolsets covering workspace context, analytics, journeys, ads-manager hierarchy, reports, segments, integrations, health, diagnostics, webhook debugging, and AI helpers. This page documents the public MCP surface — what Cursor, Claude Desktop, ChatGPT, and other external clients see after OAuth. The in-app Ask AI chat gets the same 50 tools plus additional internal-only capabilities (see below). Bulk extraction lives in the Public API V1 export endpoints and the in-app CSV export buttons — not in the MCP. Hand the dashboard URL to the user, or call the V1 export endpoints directly, instead of routing 50k rows through an LLM.

At a glance

Workspace

Tool	Best for
`get_workspace_context`	One cheap call that returns space name, timezone, currency, connected ad accounts, custom event labels, and default attribution. Call this at session start.
`list_custom_events`	Resolve “deals” → `custom_event_2` so the agent never guesses slot ids.
`list_my_spaces`	Show every space the authenticated user can access, with a marker on the current one.
`list_metric_catalog`	Enumerate every supported analytics metric slug, scoped to what this space actually uses.
`list_filterable_fields`	List every field that can appear in a `filters` object, with allowed operators per type.
`list_user_defined_metrics`	List space-defined custom metric formulas (built in the report builder).
`resolve_date_range`	Turn “last week” / “this month” / “Q1 2026” into concrete UTC bounds. Prevents off-by-one errors at DST boundaries.

Search

Tool	Best for
`search_workspace`	Fuzzy search across campaigns, ad sets, ads, contacts, companies, reports, dashboards, segments.

Analytics

Tool	Best for
`query_ad_metrics`	Primary tool for aggregated ad performance.
`query_ad_metrics_compare`	Two-period comparison (current vs previous) in one call.
`query_attribution_models`	Same query across multiple attribution models.
`query_metric_breakdown`	”Top N by X” ranked drill-down.

Events

Tool	Best for
`list_events`	Individual conversion events.
`get_event`	Single event detail.
`query_events_aggregated`	Counted / summed event totals bucketed by time + source.
`list_event_types`	Distinct event names + first/last seen + counts.

Contacts

Tool	Best for
`list_contacts`	Cursor-paginated contact list with custom-field filtering.
`get_contact`	Single contact detail.
`get_contact_journey`	Full chronological timeline (touchpoints + conversions) for one contact.
`query_contacts_aggregated`	”How many contacts converted from X last month?” aggregated rollups.

Companies

Tool	Best for
`list_companies`	Company-level rollup.
`get_company`	Single company detail.
`get_company_journey`	Full company-wide timeline with contact roster.

Ads Manager

Tool	Best for
`list_ad_accounts`	Every connected ad account with currency + last sync.
`list_campaigns`	Campaign roster across platforms.
`list_adsets`	Ad sets / ad groups.
`list_ads`	Individual ads / creatives.
`get_ad_entity`	Full campaign/adset/ad detail.

Reports

Tool	Best for
`list_dashboards`	Dashboards in this space.
`get_dashboard`	One dashboard + its reports.
`list_reports`	Saved reports across the space.
`get_report_definition`	A saved report’s full config.
`run_saved_report`	Execute a saved report as configured.
`analyze_report`	Tuned AI narrative summary (deducts AI credits).
`list_subscriptions`	Scheduled digest subscriptions.
`get_subscription_last_run`	Most recent dispatched digest for a subscription.

Segments

Tool	Best for
`list_segments`	Contact segments defined in the space.
`get_segment`	One segment’s definition.
`query_segment_membership`	Paginated members of a segment.

Integrations

Tool	Best for
`list_integrations`	Every connected integration (OAuth + webhook).
`get_pixel_status`	Per-domain pixel + CAPI + form-tracking health.
`list_event_mappings`	How external integration events map to Cometly events.

Health

Tool	Best for
`get_space_health`	Composite tracking-health checklist.
`debug_data_flow`	Trace why a specific event isn’t appearing.

Diagnostics

Tool	Best for
`inspect_site`	Server-side crawl of a landing page for tracking installation.
`verify_pixel_events`	Confirm pixel events are actually arriving from a domain.

Webhooks

Tool	Best for
`list_recent_webhooks`	Recent webhook receipts with status + summarized payload. PII redacted.
`get_webhook_event`	One webhook fire with redacted payload + parse result.

AI helpers

Tool	Best for
`search_cometly_docs`	Grep over Cometly product docs for “how does X work?” questions.
`get_chart_spec_template`	Chart.js v4 templates the agent fills in.

The in-app Ask AI chat also gets tools that are not on the public MCP transport:

Tool	Why it’s internal
`list_recent_chats`, `get_chat_room`, `search_chat_history`	Only meaningful inside Cometly’s chat UI.
`read_attachment`	Reads files uploaded to an Ask AI thread.
`query_cohort_analysis`	Cohort retention tables — Ask AI only for now.
`remember_fact`, `forget_fact`, `search_memory`	Persistent memory for Ask AI — registered separately, never exposed externally.

These are marked internal-only (external: false) or live only in the in-app agent registry. External MCP clients (Cursor, Claude Desktop, ChatGPT) won’t see them in tools/list.

Tool naming convention

Prefix	Meaning
`list_*`	Returns a cursor-paginated array. Tools accept a `cursor` parameter to walk the result set.
`get_*`	Returns a single record by ID.
`query_*`	Aggregated analytics — returns a result set shaped by `metrics`, `group_by`, and `filters`.
`search_*`	Fuzzy search (lower-precision lookup helpers).
`resolve_*`	Pure helpers that turn human-readable input into structured output.
`debug_*`	Diagnostic, multi-source composition.
`analyze_*`	Runs Cometly’s AI pipelines — deducts credits.

Output format

Most tools accept format: "csv" | "json" | "yaml". CSV is the default for tools added in v2.0 because it’s ~50% cheaper in tokens for tabular results. The legacy tools (list_events, list_contacts, query_ad_metrics, etc.) keep json as the default for backwards compatibility — pass format: "csv" explicitly when you want compactness. Token-budget pagination kicks in around ~6,000 tokens per tool response; when truncation happens the response includes a truncated_at_token_budget: true footer and an opaque next_cursor you should pass back verbatim.

Custom event awareness

Tools that touch custom events — list_events, query_ad_metrics, query_events_aggregated, and friends — automatically rewrite custom_event_* slot ids to your configured labels in their output. You can also pass labels directly:

{ "metrics": ["Deal Created", "purchase"] }

The server resolves “Deal Created” to its slot id (e.g. custom_event_2) on the way in. The result column header comes back as Deal Created, never the internal slug.

Authentication & errors

All external tools authenticate via the OAuth-issued Sanctum token described in Authentication. Errors come back as [error_class] message envelopes — see Rate Limits & Errors for the full taxonomy.

Get Started

Connecting Clients

Tools

Resources

Prompts

At a glance

Workspace

Search

Analytics

Events

Contacts

Companies

Ads Manager

Reports

Segments

Integrations

Health

Diagnostics

Webhooks

AI helpers

Tool naming convention

Output format

Custom event awareness

Authentication & errors

​At a glance

​Workspace

​Search

​Analytics

​Events

​Contacts

​Companies

​Ads Manager

​Reports

​Segments

​Integrations

​Health

​Diagnostics

​Webhooks

​AI helpers

​Tool naming convention

​Output format

​Custom event awareness

​Authentication & errors

At a glance

Workspace

Search

Analytics

Events

Contacts

Companies

Ads Manager

Reports

Segments

Integrations

Health

Diagnostics

Webhooks

AI helpers

Tool naming convention

Output format

Custom event awareness

Authentication & errors