> ## 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 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](/api-reference/endpoint/create-event-export) 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`](/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`](/mcp/tools/list-custom-events)               | Resolve "deals" → `custom_event_2` so the agent never guesses slot ids.                                                                                      |
| [`list_my_spaces`](/mcp/tools/list-my-spaces)                       | Show every space the authenticated user can access, with a marker on the current one.                                                                        |
| [`list_metric_catalog`](/mcp/tools/list-metric-catalog)             | Enumerate every supported analytics metric slug, scoped to what this space actually uses.                                                                    |
| [`list_filterable_fields`](/mcp/tools/list-filterable-fields)       | List every field that can appear in a `filters` object, with allowed operators per type.                                                                     |
| [`list_user_defined_metrics`](/mcp/tools/list-user-defined-metrics) | List space-defined custom metric formulas (built in the report builder).                                                                                     |
| [`resolve_date_range`](/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`](/mcp/tools/search-workspace) | Fuzzy search across campaigns, ad sets, ads, contacts, companies, reports, dashboards, segments. |

### Analytics

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

### Events

| Tool                                                            | Best for                                                 |
| --------------------------------------------------------------- | -------------------------------------------------------- |
| [`list_events`](/mcp/tools/list-events)                         | Individual conversion events.                            |
| [`get_event`](/mcp/tools/get-event)                             | Single event detail.                                     |
| [`query_events_aggregated`](/mcp/tools/query-events-aggregated) | Counted / summed event totals bucketed by time + source. |
| [`list_event_types`](/mcp/tools/list-event-types)               | Distinct event names + first/last seen + counts.         |

### Contacts

| Tool                                                                | Best for                                                                 |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| [`list_contacts`](/mcp/tools/list-contacts)                         | Cursor-paginated contact list with custom-field filtering.               |
| [`get_contact`](/mcp/tools/get-contact)                             | Single contact detail.                                                   |
| [`get_contact_journey`](/mcp/tools/get-contact-journey)             | Full chronological timeline (touchpoints + conversions) for one contact. |
| [`query_contacts_aggregated`](/mcp/tools/query-contacts-aggregated) | "How many contacts converted from X last month?" aggregated rollups.     |

### Companies

| Tool                                                    | Best for                                        |
| ------------------------------------------------------- | ----------------------------------------------- |
| [`list_companies`](/mcp/tools/list-companies)           | Company-level rollup.                           |
| [`get_company`](/mcp/tools/get-company)                 | Single company detail.                          |
| [`get_company_journey`](/mcp/tools/get-company-journey) | Full company-wide timeline with contact roster. |

### Ads Manager

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

### Reports

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

### Segments

| Tool                                                              | Best for                               |
| ----------------------------------------------------------------- | -------------------------------------- |
| [`list_segments`](/mcp/tools/list-segments)                       | Contact segments defined in the space. |
| [`get_segment`](/mcp/tools/get-segment)                           | One segment's definition.              |
| [`query_segment_membership`](/mcp/tools/query-segment-membership) | Paginated members of a segment.        |

### Integrations

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

### Health

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

### Diagnostics

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

### Webhooks

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

### AI helpers

| Tool                                                            | Best for                                                         |
| --------------------------------------------------------------- | ---------------------------------------------------------------- |
| [`search_cometly_docs`](/mcp/tools/search-cometly-docs)         | Grep over Cometly product docs for "how does X work?" questions. |
| [`get_chart_spec_template`](/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.                                  |
| `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](/mcp/authentication). Errors come back as `[error_class] message` envelopes — see [Rate Limits & Errors](/mcp/rate-limits-and-errors) for the full taxonomy.