Documentation Index
Fetch the complete documentation index at: https://docs.cometly.com/llms.txt
Use this file to discover all available pages before exploring further.
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. |
| 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. |
| 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. |
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.
| 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. |
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"] }
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.
