> ## 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.

# Tools Overview

> Every MCP tool Cometly exposes, organized by toolset, with when-to-use guidance.

The Cometly MCP server exposes **50+ tools** across 13 toolsets covering workspace context, analytics, journeys, ads-manager hierarchy, reports, integrations, health, diagnostics, webhook debugging, and AI helpers. All but three are read-only (and the three write tools are unavailable to [read-only tokens](https://docs.cometly.com/mcp/authentication.md#read-only-tokens)); the write tools (`update_contact`, `update_company`, [`update_event`](https://docs.cometly.com/mcp/tools/update-event)) edit fields on one record by ID and are marked **(write)** below. 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 tools plus additional internal-only capabilities (see below).

Every tool also accepts an optional `space_id` (the numeric ID from [`list_my_spaces`](https://docs.cometly.com/mcp/tools/list-my-spaces)) to run in another Space the connection covers. Without it, the tool runs in the connection's default Space.

Bulk extraction lives in the [Public API V1 export endpoints](https://docs.cometly.com/api-reference/endpoint/create-event-export.md) 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`](https://docs.cometly.com/mcp/tools/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`](https://docs.cometly.com/mcp/tools/list-custom-events) | Resolve "deals" → `custom_event_2` so the agent never guesses slot ids. |
| [`list_my_spaces`](https://docs.cometly.com/mcp/tools/list-my-spaces) | Show every space the authenticated user belongs to, marking which this connection can use and which is the default. |
| [`list_metric_catalog`](https://docs.cometly.com/mcp/tools/list-metric-catalog) | Enumerate every supported analytics metric slug, scoped to what this space actually uses. |
| [`list_filterable_fields`](https://docs.cometly.com/mcp/tools/list-filterable-fields) | List every field that can appear in a `filters` object, with allowed operators per type. |
| [`list_user_defined_metrics`](https://docs.cometly.com/mcp/tools/list-user-defined-metrics) | List space-defined custom metric formulas (built in the report builder). |
| [`resolve_date_range`](https://docs.cometly.com/mcp/tools/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`](https://docs.cometly.com/mcp/tools/search-workspace) | Fuzzy search across campaigns, ad sets, ads, contacts, companies, reports, dashboards, segments. |

### Analytics

| Tool | Best for |
| - | - |
| [`query_ad_metrics`](https://docs.cometly.com/mcp/tools/query-ad-metrics) | Primary tool for aggregated ad performance. |
| [`query_ad_metrics_compare`](https://docs.cometly.com/mcp/tools/query-ad-metrics-compare) | Two-period comparison (current vs previous) in one call. |
| [`query_attribution_models`](https://docs.cometly.com/mcp/tools/query-attribution-models) | Same query across multiple attribution models. |
| [`query_metric_breakdown`](https://docs.cometly.com/mcp/tools/query-metric-breakdown) | "Top N by X" ranked drill-down. |

### Events

| Tool | Best for |
| - | - |
| [`list_events`](https://docs.cometly.com/mcp/tools/list-events) | Individual conversion events. |
| [`get_event`](https://docs.cometly.com/mcp/tools/get-event) | Single event detail. |
| [`update_event`](https://docs.cometly.com/mcp/tools/update-event) **(write)** | Correct the `amount` on one existing event without touching its contact, journey position, or attribution. |
| [`query_events_aggregated`](https://docs.cometly.com/mcp/tools/query-events-aggregated) | Counted / summed event totals bucketed by time + source. |
| [`list_event_types`](https://docs.cometly.com/mcp/tools/list-event-types) | Distinct event names + first/last seen + counts. |

### Contacts

| Tool | Best for |
| - | - |
| [`list_contacts`](https://docs.cometly.com/mcp/tools/list-contacts) | Cursor-paginated contact list with custom-field filtering. |
| [`get_contact`](https://docs.cometly.com/mcp/tools/get-contact) | Single contact detail. |
| `update_contact` **(write)** | Replace a contact's emails, phones, names, locations, or custom fields (sparse PUT — any collection you send is the full authoritative list). |
| [`get_contact_journey`](https://docs.cometly.com/mcp/tools/get-contact-journey) | Full chronological timeline (touchpoints + conversions) for one contact. |
| [`query_contacts_aggregated`](https://docs.cometly.com/mcp/tools/query-contacts-aggregated) | "How many contacts converted from X last month?" aggregated rollups. |

### Companies

| Tool | Best for |
| - | - |
| [`list_companies`](https://docs.cometly.com/mcp/tools/list-companies) | Company-level rollup. |
| [`get_company`](https://docs.cometly.com/mcp/tools/get-company) | Single company detail. |
| `update_company` **(write)** | Change a company's `domain`, `external_id`, or `name`. Identifier changes are rejected when another company already owns the value. |
| [`get_company_journey`](https://docs.cometly.com/mcp/tools/get-company-journey) | Full company-wide timeline with contact roster. |

### Ads Manager

| Tool | Best for |
| - | - |
| [`list_ad_accounts`](https://docs.cometly.com/mcp/tools/list-ad-accounts) | Every connected ad account with currency + last sync. |
| [`list_campaigns`](https://docs.cometly.com/mcp/tools/list-campaigns) | Campaign roster across platforms. |
| [`list_adsets`](https://docs.cometly.com/mcp/tools/list-adsets) | Ad sets / ad groups. |
| [`list_ads`](https://docs.cometly.com/mcp/tools/list-ads) | Individual ads / creatives. |
| [`get_ad_entity`](https://docs.cometly.com/mcp/tools/get-ad-entity) | Full campaign/adset/ad detail. |

### Reports

| Tool | Best for |
| - | - |
| [`list_dashboards`](https://docs.cometly.com/mcp/tools/list-dashboards) | Dashboards in this space. |
| [`get_dashboard`](https://docs.cometly.com/mcp/tools/get-dashboard) | One dashboard + its reports. |
| [`list_reports`](https://docs.cometly.com/mcp/tools/list-reports) | Saved reports across the space. |
| [`get_report_definition`](https://docs.cometly.com/mcp/tools/get-report-definition) | A saved report's full config. |
| [`run_saved_report`](https://docs.cometly.com/mcp/tools/run-saved-report) | Execute a saved report as configured. |
| [`analyze_report`](https://docs.cometly.com/mcp/tools/analyze-report) | Tuned AI narrative summary (deducts AI credits). |
| [`list_subscriptions`](https://docs.cometly.com/mcp/tools/list-subscriptions) | Scheduled digest subscriptions. |
| [`get_subscription_last_run`](https://docs.cometly.com/mcp/tools/get-subscription-last-run) | Most recent dispatched digest for a subscription. |

### Integrations

| Tool | Best for |
| - | - |
| [`list_integrations`](https://docs.cometly.com/mcp/tools/list-integrations) | Every connected integration (OAuth + webhook). |
| [`get_pixel_status`](https://docs.cometly.com/mcp/tools/get-pixel-status) | Per-domain pixel + CAPI + form-tracking health. |
| [`list_event_mappings`](https://docs.cometly.com/mcp/tools/list-event-mappings) | How external integration events map to Cometly events. |

### Health

| Tool | Best for |
| - | - |
| [`get_space_health`](https://docs.cometly.com/mcp/tools/get-space-health) | Composite tracking-health checklist. |
| [`debug_data_flow`](https://docs.cometly.com/mcp/tools/debug-data-flow) | Trace why a specific event isn't appearing. |

### Diagnostics

| Tool | Best for |
| - | - |
| [`inspect_site`](https://docs.cometly.com/mcp/tools/inspect-site) | Server-side crawl of a landing page for tracking installation. |
| [`verify_pixel_events`](https://docs.cometly.com/mcp/tools/verify-pixel-events) | Confirm pixel events are actually arriving from a domain. |

### Webhooks

| Tool | Best for |
| - | - |
| [`list_recent_webhooks`](https://docs.cometly.com/mcp/tools/list-recent-webhooks) | Recent webhook receipts with status + summarized payload. PII redacted. |
| [`get_webhook_event`](https://docs.cometly.com/mcp/tools/get-webhook-event) | One webhook fire with redacted payload + parse result. |

### AI helpers

| Tool | Best for |
| - | - |
| [`search_cometly_docs`](https://docs.cometly.com/mcp/tools/search-cometly-docs) | Grep over Cometly product docs for "how does X work?" questions. |
| [`get_chart_spec_template`](https://docs.cometly.com/mcp/tools/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. |
| `list_segments`, `get_segment`, `query_segment_membership` | Contact segments aren't available yet, so these are hidden from external clients until they ship. |
| `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:

```json theme={null}
{ "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](https://docs.cometly.com/mcp/authentication.md). Errors come back as `[error_class] message` envelopes — see [Rate Limits & Errors](https://docs.cometly.com/mcp/rate-limits-and-errors.md) for the full taxonomy.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.