> ## Documentation Index
> Fetch the complete documentation index at: https://docs.traceten.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP tools

> All 83 Traceten MCP tools, what each one answers, and which permission it needs.

## How the tools are named

Every tool is `traceten_<resource>_<action>` and maps one to one onto a documented [REST endpoint](/api/authentication), with the same arguments, the same validation and the same permissions. Anything you can do through a tool you can do with `curl`, and the reverse.

Your assistant sees a full description of each tool, including the traps that change the answer. This page is the map.

## Reading the table

* **Permission** is the API key permission the call needs. A key without it gets a clear error naming what is missing, rather than a silent empty result.
* **(confirm)** marks a tool that returns a preview and changes nothing until you approve it. See [Safety and permissions](/mcp/safety).
* `traceten_sites_create` needs three permissions because it **mints a key**, and a key can never create one more capable than itself. `stats:read` and `ingest:write` are what the new key will carry, so the caller has to hold them already. This is not a reason to over-provision your other keys.
* Every site-scoped tool takes `site_id` (or `siteId`) as the `ttid_` snippet key from `traceten_sites_list`, not the UUID in your dashboard URL.

## Two distinctions worth knowing before you read a number

**`ai_source` is not `source_kind`.** `ai_source` names which assistant sent the traffic (ChatGPT, Claude, Perplexity, Gemini, Copilot, Grok). `source_kind` names the category of traffic (`ai`, `non_ai`, `unknown`, and on the revenue side a fourth value, `unmatched`). They are different axes over overlapping populations. Adding a figure from one to a figure from the other double counts.

**A session is not a person.** A session is one visit, and it ends after 30 minutes of inactivity. A returning customer is many sessions and one visitor, so a session count is never a headcount.

## The tools

### Stats

| Tool                        | What it answers                      | Endpoint                   | Permission   |
| --------------------------- | ------------------------------------ | -------------------------- | ------------ |
| `traceten_stats_overview`   | Headline numbers for a window        | `GET /v1/stats/overview`   | `stats:read` |
| `traceten_stats_timeseries` | Headline numbers, bucketed over time | `GET /v1/stats/timeseries` | `stats:read` |
| `traceten_stats_realtime`   | Who is on the site right now         | `GET /v1/stats/realtime`   | `stats:read` |
| `traceten_stats_metadata`   | A site's display settings            | `GET /v1/stats/metadata`   | `stats:read` |

### AI attribution

| Tool                              | What it answers                                         | Endpoint                          | Permission   |
| --------------------------------- | ------------------------------------------------------- | --------------------------------- | ------------ |
| `traceten_breakdown_ai_sources`   | Which AI assistants sent traffic, and what it was worth | `GET /v1/breakdowns/ai-sources`   | `stats:read` |
| `traceten_breakdown_source_kinds` | AI vs non-AI vs unknown traffic                         | `GET /v1/breakdowns/source-kinds` | `stats:read` |
| `traceten_detection_quality`      | What the bot filter removed                             | `GET /v1/detection/quality`       | `stats:read` |
| `traceten_detection_coverage`     | How much revenue could be tied to a session             | `GET /v1/detection/coverage`      | `stats:read` |

### AI crawlers

| Tool                          | What it answers                                  | Endpoint                     | Permission   |
| ----------------------------- | ------------------------------------------------ | ---------------------------- | ------------ |
| `traceten_ai_crawls_summary`  | AI crawler totals and how far they were verified | `GET /v1/ai-crawls/summary`  | `stats:read` |
| `traceten_ai_crawls_by_page`  | Which pages AI crawlers read                     | `GET /v1/ai-crawls/by-page`  | `stats:read` |
| `traceten_ai_crawls_timeline` | Daily AI crawl volume                            | `GET /v1/ai-crawls/timeline` | `stats:read` |
| `traceten_ai_crawls_series`   | Ranked daily crawl series by company or page     | `GET /v1/ai-crawls/series`   | `stats:read` |
| `traceten_ai_crawls_recent`   | The live AI crawler feed                         | `GET /v1/ai-crawls/recent`   | `stats:read` |

### Answer-engine visibility

| Tool                              | What it answers                               | Endpoint                               | Permission   |
| --------------------------------- | --------------------------------------------- | -------------------------------------- | ------------ |
| `traceten_visibility_summary`     | Do answer engines mention and cite this brand | `GET /v1/visibility/summary`           | `stats:read` |
| `traceten_visibility_timeseries`  | Visibility over time, by scan window          | `GET /v1/visibility/timeseries`        | `stats:read` |
| `traceten_visibility_competitors` | Share of voice against tracked competitors    | `GET /v1/visibility/competitors`       | `stats:read` |
| `traceten_visibility_by_prompt`   | Per-prompt presence, rivals and cited pages   | `GET /v1/visibility/by-prompt`         | `stats:read` |
| `traceten_citations_by_page`      | Cited pages, joined to crawls and revenue     | `GET /v1/visibility/citations/by-page` | `stats:read` |
| `traceten_visibility_runs`        | The verbatim answers behind the numbers       | `GET /v1/visibility/runs`              | `stats:read` |

`traceten_visibility_runs` returns answer text written by third-party AI engines. That text can name people and companies other than you. It carries no visitor identifier and describes nobody who visited your site, but it is the one visibility tool whose output is prose rather than counts. See [Safety and permissions](/mcp/safety).

### What gets measured

These tools change the measurement itself, not just settings. The prompt list is the denominator of every rate in the table above: adding a question you rank badly for lowers your presence rate, and removing one raises it, without anything changing on your site.

| Tool                                 | What it answers                           | Endpoint                                   | Permission     |
| ------------------------------------ | ----------------------------------------- | ------------------------------------------ | -------------- |
| `traceten_brands_list`               | Which brands are matched in answers       | `GET /v1/visibility/brands`                | `stats:read`   |
| `traceten_brands_create`             | Track a brand or a competitor             | `POST /v1/visibility/brands`               | `config:write` |
| `traceten_brands_update`             | Change a brand's name, aliases or domains | `PATCH /v1/visibility/brands/{id}`         | `config:write` |
| `traceten_brands_confirm`            | Admit a proposed brand to measurement     | `POST /v1/visibility/brands/{id}/confirm`  | `config:write` |
| `traceten_brands_archive` (confirm)  | Stop tracking a brand                     | `DELETE /v1/visibility/brands/{id}`        | `config:write` |
| `traceten_prompts_list`              | Which questions the engines are asked     | `GET /v1/visibility/prompts`               | `stats:read`   |
| `traceten_prompts_create`            | Track a question                          | `POST /v1/visibility/prompts`              | `config:write` |
| `traceten_prompts_update`            | Change a question's grouping or status    | `PATCH /v1/visibility/prompts/{id}`        | `config:write` |
| `traceten_prompts_replace`           | Reword a question (archives the old one)  | `POST /v1/visibility/prompts/{id}/replace` | `config:write` |
| `traceten_prompts_archive` (confirm) | Stop asking a question                    | `DELETE /v1/visibility/prompts/{id}`       | `config:write` |
| `traceten_prompts_suggest`           | Suggest questions from your own pages     | `POST /v1/visibility/prompts/suggest`      | `config:write` |

Three things worth knowing before you let an assistant use these:

* **A prompt's wording can never be edited.** Past runs record only the prompt's id, so changing the text would rewrite what your history claims was asked. `traceten_prompts_replace` archives the old question and returns a **new one with a new id**, starting a new series.
* **Suggestions are never enrolled automatically.** `traceten_prompts_suggest` returns candidates and saves nothing. You create the ones you want. The prompt list decides your score, so Traceten does not get to pick it.
* **`traceten_prompts_suggest` needs `config:write` even though it saves nothing**, because it makes Traceten fetch your site: at most 8 pages, 12 requests and 15 seconds, every request pinned to your own host, honouring your `robots.txt`. Your site must already have received tracking events, or it returns 409 `site_not_verified` and fetches nothing. No AI provider is involved; the candidates are templates filled with your own page wording, copied verbatim, so read them before you create them.

### Revenue

| Tool                             | What it answers                      | Endpoint                        | Permission   |
| -------------------------------- | ------------------------------------ | ------------------------------- | ------------ |
| `traceten_revenue_breakdown`     | Attributed revenue by source         | `GET /v1/revenue/breakdown`     | `stats:read` |
| `traceten_revenue_timeseries`    | Attributed revenue over time         | `GET /v1/revenue/timeseries`    | `stats:read` |
| `traceten_revenue_sku_breakdown` | Revenue by product and SKU           | `GET /v1/revenue/sku-breakdown` | `stats:read` |
| `traceten_revenue_ltv`           | Lifetime value by acquisition source | `GET /v1/revenue/ltv`           | `stats:read` |

### Breakdowns

| Tool                                   | What it answers                  | Endpoint                               | Permission   |
| -------------------------------------- | -------------------------------- | -------------------------------------- | ------------ |
| `traceten_breakdown_pages`             | Top pages                        | `GET /v1/breakdowns/pages`             | `stats:read` |
| `traceten_breakdown_referrers`         | Traffic sources by name          | `GET /v1/breakdowns/referrers`         | `stats:read` |
| `traceten_breakdown_countries`         | Sessions by country              | `GET /v1/breakdowns/countries`         | `stats:read` |
| `traceten_breakdown_cities`            | Sessions by city                 | `GET /v1/breakdowns/cities`            | `stats:read` |
| `traceten_breakdown_devices`           | Sessions by device type          | `GET /v1/breakdowns/devices`           | `stats:read` |
| `traceten_breakdown_browsers`          | Sessions by browser              | `GET /v1/breakdowns/browsers`          | `stats:read` |
| `traceten_breakdown_operating_systems` | Sessions by operating system     | `GET /v1/breakdowns/operating-systems` | `stats:read` |
| `traceten_breakdown_campaigns`         | Sessions by utm\_campaign        | `GET /v1/breakdowns/campaigns`         | `stats:read` |
| `traceten_breakdown_hostnames`         | Sessions by hostname             | `GET /v1/breakdowns/hostnames`         | `stats:read` |
| `traceten_breakdown_exit_links`        | Sessions by outbound link domain | `GET /v1/breakdowns/exit-links`        | `stats:read` |

### Sessions

| Tool                        | What it answers                            | Endpoint                        | Permission   |
| --------------------------- | ------------------------------------------ | ------------------------------- | ------------ |
| `traceten_sessions_list`    | List sessions with their AI attribution    | `GET /v1/sessions`              | `stats:read` |
| `traceten_sessions_get`     | One session in full                        | `GET /v1/sessions/{id}/detail`  | `stats:read` |
| `traceten_sessions_journey` | Multi-touch AI attribution for one session | `GET /v1/sessions/{id}/journey` | `stats:read` |

For what a visit actually did, and for the person behind it, go through the [Visitors](#visitors) tools. `traceten_visitors_timeline` returns the events inside each of a person's visits, and `traceten_visitors_get` returns the person.

### Goals

| Tool                               | What it answers                 | Endpoint                          | Permission     |
| ---------------------------------- | ------------------------------- | --------------------------------- | -------------- |
| `traceten_goals_list`              | List a site's goals             | `GET /v1/goals`                   | `stats:read`   |
| `traceten_goals_create`            | Pre-declare a goal              | `POST /v1/goals`                  | `config:write` |
| `traceten_goals_update`            | Rename a goal's display fields  | `PATCH /v1/goals/{id}`            | `config:write` |
| `traceten_goals_archive` (confirm) | Archive a goal                  | `DELETE /v1/goals/{id}`           | `config:write` |
| `traceten_goals_unarchive`         | Restore an archived goal        | `POST /v1/goals/{id}/unarchive`   | `config:write` |
| `traceten_goals_timeseries`        | Goal completions per day        | `GET /v1/goals/timeseries`        | `stats:read`   |
| `traceten_goals_properties`        | Property breakdown for one goal | `GET /v1/goals/{name}/properties` | `stats:read`   |

### Funnels

| Tool                                | What it answers          | Endpoint                       | Permission     |
| ----------------------------------- | ------------------------ | ------------------------------ | -------------- |
| `traceten_funnels_list`             | List a site's funnels    | `GET /v1/funnels`              | `stats:read`   |
| `traceten_funnels_create`           | Define a funnel          | `POST /v1/funnels`             | `config:write` |
| `traceten_funnels_update`           | Edit a funnel definition | `PATCH /v1/funnels/{id}`       | `config:write` |
| `traceten_funnels_delete` (confirm) | Delete a funnel          | `DELETE /v1/funnels/{id}`      | `config:write` |
| `traceten_funnels_results`          | Run a funnel             | `GET /v1/funnels/{id}/results` | `stats:read`   |

### Visitors

One row per person rather than per visit. Use these when the question counts people, and the [Sessions](#sessions) tools when it counts visits.

| Tool                             | What it answers                      | Endpoint                                         | Permission   |
| -------------------------------- | ------------------------------------ | ------------------------------------------------ | ------------ |
| `traceten_visitors_list`         | List visitors, filtered and sorted   | `GET /v1/visitors`                               | `stats:read` |
| `traceten_visitors_get`          | One visitor in full                  | `GET /v1/visitors/{handle}`                      | `stats:read` |
| `traceten_visitors_timeline`     | What one visitor did, visit by visit | `GET /v1/visitors/{handle}/timeline`             | `stats:read` |
| `traceten_funnels_step_visitors` | Who dropped at one funnel step       | `GET /v1/funnels/{id}/steps/{position}/visitors` | `stats:read` |
| `traceten_goals_visitors`        | Who completed one goal               | `GET /v1/goals/{name}/visitors`                  | `stats:read` |

`traceten_visitors_timeline` pages by **visit**, not by event: `page_size` counts visits and one page of 10 can carry several hundred events. It returns two date ranges, and they are different. `meta.effective_window` is the range you asked for, clamped to how long a session record is kept. `history_window` is the range the visits are drawn from, bounded by how long raw events are kept, and it is usually wider.

Rows carry an opaque `handle`, not a visitor identifier. A handle is stable, so an assistant can cache it and come back to it, and it is scoped to one site, so the same person on another of your sites has a different one and this one returns `404` there. It is not reversible by you and carries no name, email address or IP address.

### Chart notes

Notes your team pins to UTC days on a site's traffic chart. They are shared with everyone in the organization. Note text is written by people, so the tools return it wrapped as `{ "untrusted_text": … }`, and your assistant is told to treat it as data, never as instructions. The assistant's vendor receives the text it reads. Member ids are never returned; `created_via` says whether a note came from the dashboard, an API key or an AI assistant.

| Tool                                    | What it answers           | Endpoint                      | Permission     |
| --------------------------------------- | ------------------------- | ----------------------------- | -------------- |
| `traceten_annotations_list`             | List a site's chart notes | `GET /v1/annotations`         | `stats:read`   |
| `traceten_annotations_create`           | Add a chart note          | `POST /v1/annotations`        | `config:write` |
| `traceten_annotations_update` (confirm) | Change a chart note       | `PATCH /v1/annotations/{id}`  | `config:write` |
| `traceten_annotations_delete` (confirm) | Delete a chart note       | `DELETE /v1/annotations/{id}` | `config:write` |

### Sites

| Tool                              | What it answers          | Endpoint                   | Permission                                          |
| --------------------------------- | ------------------------ | -------------------------- | --------------------------------------------------- |
| `traceten_sites_list`             | List the account's sites | `GET /v1/sites`            | `stats:read`                                        |
| `traceten_sites_get`              | Fetch one site           | `GET /v1/sites/{siteId}`   | `stats:read`                                        |
| `traceten_sites_create` (confirm) | Create a site            | `POST /v1/sites`           | `credentials:write` + `stats:read` + `ingest:write` |
| `traceten_sites_update` (confirm) | Update a site's settings | `PATCH /v1/sites/{siteId}` | `config:write`                                      |

### Account and keys

| Tool                                | What it answers                    | Endpoint                              | Permission          |
| ----------------------------------- | ---------------------------------- | ------------------------------------- | ------------------- |
| `traceten_account_get`              | The account's profile and plan     | `GET /v1/account`                     | `stats:read`        |
| `traceten_account_usage`            | Current billing period consumption | `GET /v1/account/usage`               | `stats:read`        |
| `traceten_apikeys_list`             | List the account's API keys        | `GET /v1/account/api-keys`            | `config:write`      |
| `traceten_apikeys_create` (confirm) | Mint an API key                    | `POST /v1/account/api-keys`           | `credentials:write` |
| `traceten_apikeys_revoke` (confirm) | Revoke an API key                  | `DELETE /v1/account/api-keys/{keyId}` | `config:write`      |

### Webhooks

| Tool                                        | What it answers                   | Endpoint                                                     | Permission          |
| ------------------------------------------- | --------------------------------- | ------------------------------------------------------------ | ------------------- |
| `traceten_webhooks_list`                    | List a site's outbound webhooks   | `GET /v1/sites/{siteId}/webhooks`                            | `stats:read`        |
| `traceten_webhooks_create` (confirm)        | Register an outbound webhook      | `POST /v1/sites/{siteId}/webhooks`                           | `credentials:write` |
| `traceten_webhooks_test`                    | Send a test ping                  | `POST /v1/sites/{siteId}/webhooks/{webhookId}/test`          | `config:write`      |
| `traceten_webhooks_rotate_secret` (confirm) | Rotate a webhook's signing secret | `POST /v1/sites/{siteId}/webhooks/{webhookId}/rotate-secret` | `credentials:write` |

### Integrations and team

| Tool                           | What it answers                       | Endpoint               | Permission   |
| ------------------------------ | ------------------------------------- | ---------------------- | ------------ |
| `traceten_integrations_status` | Revenue provider connection status    | `GET /v1/integrations` | `stats:read` |
| `traceten_team_list`           | The account's members and their roles | `GET /v1/team`         | `stats:read` |

## Tools that deliberately do not exist

* **No lookup by identity.** `traceten_visitors_list` filters people by dimensions you already report on: source, campaign, landing page, country, city, device, browser. No tool accepts a name, an email address, an IP address or a visitor identifier as an input, because none of those is stored in a form any tool could match. A `handle` addresses a visitor an assistant has already listed; it is not a search term.
* **No cross-site view of a person.** Every tool is scoped to one site, and a handle from one site means nothing on another. Traceten holds no key that links a person's activity across two customers.
* **No event write or delete.** Recording events belongs to the [server SDKs](/sdks/overview); erasure belongs to the [data deletion API](/privacy/data-deletion), which needs its own permission.
* **No site deletion.** Deleting a property destroys its history. That stays in the dashboard, behind a typed confirmation.
* **No integration connect or disconnect.** Connecting pastes a secret and follows a browser redirect, neither of which an assistant can do safely.
* **No team changes.** Membership and roles live in your identity provider.
* **No `regions` breakdown.** Traceten records country and city, and holds no region field, so there is nothing to report.

## Next

* [Safety and permissions](/mcp/safety)
* [API reference](/api/authentication) for the same surface over HTTP