# Tools Reference


Every MCP tool wraps exactly one documented API v2 endpoint. Arguments are
forwarded verbatim - the endpoint's documented body and query contract IS the
tool's contract. Follow the endpoint link for fields, required values, and
response shapes.

## Reference data

| Tool | Wraps | Notes |
| --- | --- | --- |
| `lookup_reference` | [`GET /api/v2/analyses/reference/{dataset}/{catalog}`](/api/v2/reference) | `dataset` + `catalog` select the catalog; other arguments become query parameters. `signal-providers` needs `dataType`; `pricing-models` and `datastreams` need `partner_id`. Call `tools/list` for the live list of valid `dataset`/`catalog` pairs - the tool description carries it. |

The `dataset` argument is the reference **group** name, which is not always the
dataset's display name. The dataset shown as **Transactions** in the console is
`affinity-transactions` here, and its audience-create `type` is
`AffinityTransactions` - see
[Transactions reference](/api/v2/reference/affinity-transactions). Groups that
no longer exist return a tool error naming the supported replacement rather
than a failed request.

## Audiences

| Tool | Wraps | Notes |
| --- | --- | --- |
| `list_audiences` | [`GET /api/v2/analyses/audiences/index`](/api/v2/audiences) | `search`, `page`, `per_page`. |
| `get_audience` | [`GET /api/v2/analyses/audiences/{id}`](/api/v2/audiences) | Poll until `data[0].status.id` is `104` (Completed). Response also carries `eligibility` (allowed / reasons / metrics incl. `unique_scids` and `eid_scid_ratio`) and `totals`. |
| `create_audience` | [`POST /api/v2/analyses/audiences/create`](/api/v2/audiences) | Accepts `idempotency_key`. `datasets` blocks per the endpoint docs; the tool description names every `type` the endpoint accepts, and `lookup_reference` with `dataset: common`, `catalog: dataset-types` returns the ones enabled for your account. A `WebDomain` block's `start_date` is limited to the last 45 days of available data. On a `POI` block the brand field is `analysisdata` (there is no `brands` key) and `categories` is a flat list of integers; an unknown key, or an object where an id belongs, is rejected with a 422 that names the field. An `Origin` block (home location) filters on geography only: `location.countries` is required - fetch the covered ones with `dataset: common`, `catalog: countries`, `datasetType: Origin` - `states` / `cities` / `dmas` / `zipcodes` are optional, `signal_providers` come from `catalog: signal-providers` with `dataType: Origin`, and the window is widened to the whole Monday-to-Sunday weeks it touches (the data is weekly, so a sub-week window cannot be built). `analyses` runs the frequency analyses: `frequency` (needs a `POI` block; `frequency_day_part` is its day-part sub-option), `apps_frequency` (`Apps`) and `web_frequency` (`WebDomain`), all behind the Frequency feature on the account - the only way an audience built here can later be previewed by `preview_activation`; none can be added after the build. Refused with the quota `422` once the company's monthly data-scan limit is reached (`get_usage`). |
| `delete_audience` | [`POST /api/v2/analyses/audiences/delete-by-id`](/api/v2/audiences) | Destructive. |
| `estimate_audience_size` | [`POST /api/v2/analyses/audiences/estimate`](/api/v2/audiences) | Accepts `idempotency_key`. Same body as `create_audience`; read-only - nothing is created. Scans the same data a create would and counts toward the monthly data-scan limit (`estimate` on `get_usage`); refused with the quota `422` once the limit is reached. Poll `get_audience_estimate`. |
| `get_audience_estimate` | [`GET /api/v2/analyses/audiences/estimate/{id}`](/api/v2/audiences) | Poll until `data[0].status` is `completed`, `blocked`, or `failed`. |
| `create_lookalike_audience` | [`POST /api/v2/analyses/audiences/create-lookalike`](/api/v2/audiences) | Accepts `idempotency_key`. Seed must be Completed, non-lookalike, 1,000+ devices by default. `config.signals` accepts `poi`, `apps`, `demographics` and `transactions` (`web` is temporarily withdrawn while its training contrast is re-validated - [Data families](/api/v2/audiences/#data-families)). |
| `cancel_lookalike` | [`POST /api/v2/analyses/audiences/cancel-lookalike`](/api/v2/audiences) | Cooperative cancel of an in-flight model run. |

## Activations

| Tool | Wraps | Notes |
| --- | --- | --- |
| `list_activations` | [`GET /api/v2/analyses/activations/index`](/api/v2/activations) | `search`, `page`, `per_page`. |
| `get_activation` | [`GET /api/v2/analyses/activations/{id}`](/api/v2/activations) | Delivered data lands at the destination configured on the endpoint connection. |
| `preview_activation` | [`GET /api/v2/analyses/activations/preview`](/api/v2/activations#get-apiv2analysesactivationspreview) | Read-only. `audience_id`, `freq_min`, `freq_max` only (recency is fixed by the audience; any other field is rejected). Returns the exact Audience Manager "Limit Audience" count for that range, the histogram and bounds, `recency`, eligibility and `filter_hash`. Nothing is created or billed. Worked session: [Preview, then Activate](/mcp/preview-and-activate). |
| `create_activation` | [`POST /api/v2/analyses/activations/create`](/api/v2/activations) | Accepts `idempotency_key`. The audience must be Completed first (`data[0].status.id` = 104). `freq_min` / `freq_max` require an explicit `freq_limit`; pass `freq_limit: true` plus the `filter_hash` from `preview_activation` to activate exactly the previewed range. |
| `delete_activation` | [`POST /api/v2/analyses/activations/delete-by-id`](/api/v2/activations) | Destructive. |

## Cohorts

| Tool | Wraps | Notes |
| --- | --- | --- |
| `list_cohorts` | [`GET /api/v2/analyses/cohorts/index`](/api/v2/cohorts) | `search`, `page`, `per_page`. |
| `get_cohort` | [`GET /api/v2/analyses/cohorts/{id}`](/api/v2/cohorts) | |
| `create_cohort` | [`POST /api/v2/analyses/cohorts/create`](/api/v2/cohorts) | Accepts `idempotency_key`. Two sources: `source: file` (the default) builds from a cloud-hosted file (`file_uri`) or an uploaded file (`upload_reference` from `create_upload`) - exactly one of the two; `source: audience` builds from a Completed audience (`audience_id`). |
| `preview_cohort_file` | [`POST /api/v2/analyses/cohorts/preview`](/api/v2/cohorts) | Bounded-prefix read returning `columns` / `samples` / `sample_rows`; confirms `identifier_column` before `create_cohort`. Does not consume the reference. |
| `delete_cohort` | [`POST /api/v2/analyses/cohorts/delete-by-id`](/api/v2/cohorts) | Destructive. |

## POI data

| Tool | Wraps | Notes |
| --- | --- | --- |
| `browse_poi_data` | [`GET /api/v2/my-data/pois/...`](/api/v2/poi) | `kind`: `segments`, `categories`, `brands`, `pois`, `submissions`; optional `id` for `pois`/`submissions`. |
| `create_poi_category` | [`POST /api/v2/my-data/pois/categories/create`](/api/v2/poi) | |
| `create_poi_brand` | [`POST /api/v2/my-data/pois/brands/create`](/api/v2/poi) | |
| `create_poi_submission` | [`POST /api/v2/my-data/pois/submissions/create-by-list`](/api/v2/poi) | List submissions only. For file submissions, reserve with `create_upload` (purpose `poi_submission`) and call the raw create-by-upload endpoint. Destructive: with `remove`, approving the submission archives every POI of the brand that no listed location matches (see the [matching note](/api/v2/poi/submissions#post-apiv2my-datapoissubmissionscreate-by-file)). |
| `delete_poi_submission` | [`POST /api/v2/my-data/pois/submissions/delete-by-id`](/api/v2/poi) | Destructive. |

## Projects

| Tool | Wraps | Notes |
| --- | --- | --- |
| `list_projects` | [`GET /api/v2/analyses/projects/index`](/api/v2/projects) | `search`, `page`, `per_page`. Resolves a project name to the `project_id` the audience / activation / cohort creates accept. |
| `create_project` | [`POST /api/v2/analyses/projects/create`](/api/v2/projects) | Accepts `idempotency_key`. Takes `name` only. |

## Usage

| Tool | Wraps | Notes |
| --- | --- | --- |
| `get_usage` | [`GET /api/v2/usage`](/api/v2/usage) | Read-only. Optional `yearmonth` (`YYYY-MM`, defaults to the current month). Scanned bytes, per-operation breakdown, and the monthly limit block for that month. Always the caller's own company; for a past month `over_limit` / `percent_used` come back null. |

## Uploads

| Tool | Wraps | Notes |
| --- | --- | --- |
| `create_upload` | [`POST /api/v2/uploads/create`](/api/v2/uploads) | Reserves a presigned `PUT` slot and returns `upload_url` + a one-shot `upload_reference`. The tool cannot transfer bytes itself - the file must be `PUT` to `upload_url` (by you, or by a client that can make HTTP requests) before the reference is used. |

## Prompts

| Prompt | Purpose |
| --- | --- |
| `build_and_activate_audience` | Guided end-to-end workflow: reference discovery, audience create, polling to Completed, activation, delivery polling. |

## Resources

The server also publishes these developer-docs pages as MCP resources, so an
agent can read the contracts it needs without leaving the session. Read
[Audiences and dataset blocks](/api/v2/audiences) before writing a
`create_audience` payload: it is the source of truth for which keys each
dataset type takes, and for which reference catalog resolves each one. Resources are read-only markdown (`mimeType: text/markdown`) and carry
no account data - everything account-specific comes from a tool call.

Call `resources/list` for the live catalog, then `resources/read` with the
`uri` you want.

| Resource `uri` | Page |
| --- | --- |
| `intuizi://docs/mcp/getting-started` | [MCP getting started](/mcp/getting-started) |
| `intuizi://docs/mcp/preview-and-activate` | [Preview, then Activate](/mcp/preview-and-activate) |
| `intuizi://docs/mcp/tools-reference` | This page |
| `intuizi://docs/concepts/envelope` | [Request & Response Envelope](/concepts/envelope) |
| `intuizi://docs/concepts/async-model` | [The Async Model](/concepts/async-model) |
| `intuizi://docs/concepts/errors` | [Errors](/concepts/errors) |
| `intuizi://docs/concepts/idempotency` | [Idempotency](/concepts/idempotency) |
| `intuizi://docs/concepts/datasets` | [Datasets](/concepts/datasets) |
| `intuizi://docs/api/audiences` | [Audiences and dataset blocks](/api/v2/audiences) |
| `intuizi://docs/api/activations` | [Activations](/api/v2/activations) |
| `intuizi://docs/api/common` | [Common reference catalogs](/api/v2/common) |
| `intuizi://docs/api/reference/poi` | [POI reference](/api/v2/reference/poi) |
| `intuizi://docs/api/reference/apps` | [Apps reference](/api/v2/reference/apps) |
| `intuizi://docs/api/reference/web` | [Web reference](/api/v2/reference/web) |
| `intuizi://docs/api/reference/ctv` | [CTV reference](/api/v2/reference/ctv) |
| `intuizi://docs/api/reference/affinity-transactions` | [Affinity Transactions reference](/api/v2/reference/affinity-transactions) |
| `intuizi://docs/api/reference/demographics` | [Demographics reference](/api/v2/reference/demographics) |
| `intuizi://docs/api/reference/profile-attributes` | [Profile Attributes reference](/api/v2/reference/profile-attributes) |
| `intuizi://docs/api/reference/deidentified` | [Deidentified reference](/api/v2/reference/deidentified) |
| `intuizi://docs/api/reference/cohorts` | [Cohorts reference](/api/v2/reference/cohorts) |

A `resources/read` for a `uri` outside this catalog returns a JSON-RPC
`-32602` error frame. The catalog is static: there are no resource templates,
and no subscriptions.