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}`	`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. 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`	`search`, `page`, `per_page`.
`get_audience`	`GET /api/v2/analyses/audiences/{id}`	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`	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`	Destructive.
`estimate_audience_size`	`POST /api/v2/analyses/audiences/estimate`	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}`	Poll until `data[0].status` is `completed`, `blocked`, or `failed`.
`create_lookalike_audience`	`POST /api/v2/analyses/audiences/create-lookalike`	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).
`cancel_lookalike`	`POST /api/v2/analyses/audiences/cancel-lookalike`	Cooperative cancel of an in-flight model run.

Activations

Tool	Wraps	Notes
`list_activations`	`GET /api/v2/analyses/activations/index`	`search`, `page`, `per_page`.
`get_activation`	`GET /api/v2/analyses/activations/{id}`	Delivered data lands at the destination configured on the endpoint connection.
`preview_activation`	`GET /api/v2/analyses/activations/preview`	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.
`create_activation`	`POST /api/v2/analyses/activations/create`	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`	Destructive.

Cohorts

Tool	Wraps	Notes
`list_cohorts`	`GET /api/v2/analyses/cohorts/index`	`search`, `page`, `per_page`.
`get_cohort`	`GET /api/v2/analyses/cohorts/{id}`
`create_cohort`	`POST /api/v2/analyses/cohorts/create`	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`	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`	Destructive.

POI data

Tool	Wraps	Notes
`browse_poi_data`	`GET /api/v2/my-data/pois/...`	`kind`: `segments`, `categories`, `brands`, `pois`, `submissions`; optional `id` for `pois`/`submissions`.
`create_poi_category`	`POST /api/v2/my-data/pois/categories/create`
`create_poi_brand`	`POST /api/v2/my-data/pois/brands/create`
`create_poi_submission`	`POST /api/v2/my-data/pois/submissions/create-by-list`	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).
`delete_poi_submission`	`POST /api/v2/my-data/pois/submissions/delete-by-id`	Destructive.

Projects

Tool	Wraps	Notes
`list_projects`	`GET /api/v2/analyses/projects/index`	`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`	Accepts `idempotency_key`. Takes `name` only.

Usage

Tool	Wraps	Notes
`get_usage`	`GET /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`	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 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
`intuizi://docs/mcp/preview-and-activate`	Preview, then Activate
`intuizi://docs/mcp/tools-reference`	This page
`intuizi://docs/concepts/envelope`	Request & Response Envelope
`intuizi://docs/concepts/async-model`	The Async Model
`intuizi://docs/concepts/errors`	Errors
`intuizi://docs/concepts/idempotency`	Idempotency
`intuizi://docs/concepts/datasets`	Datasets
`intuizi://docs/api/audiences`	Audiences and dataset blocks
`intuizi://docs/api/activations`	Activations
`intuizi://docs/api/common`	Common reference catalogs
`intuizi://docs/api/reference/poi`	POI reference
`intuizi://docs/api/reference/apps`	Apps reference
`intuizi://docs/api/reference/web`	Web reference
`intuizi://docs/api/reference/ctv`	CTV reference
`intuizi://docs/api/reference/affinity-transactions`	Affinity Transactions reference
`intuizi://docs/api/reference/demographics`	Demographics reference
`intuizi://docs/api/reference/profile-attributes`	Profile Attributes reference
`intuizi://docs/api/reference/deidentified`	Deidentified reference
`intuizi://docs/api/reference/cohorts`	Cohorts reference

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.

Preview, then Activate