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`. A `Demographics` entry names the monthly vintage it read in `dataset[].vintage` (`YYYY-MM`), and the agent reports it as “latest monthly vintage, as of YYYY-MM”. `demographics_stream_vintage` names the month an audience’s `demographics` data stream reads.
`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. Some dataset combinations turn an analysis off, as in the Audience Manager (a `422` on it). `signal_providers` come from `catalog: signal-providers` for the block’s type. A provider already used on one of your organization’s audiences of that type is accepted too, as long as it is still a signal provider. A `Deidentified` block’s `start_date` can go back to the first day of the previous month, unless a longer look-back is enabled for your account. A `POI` block takes optional quality `filters` (`anomalous_devices`, `anomalous_pois`, `strict_gps`; none by default, the same on both blocks of a two-`POI` audience) - see POI filters. A `POI` block with `poi_selection_mode: attributes` is built from the locations where the attribute values in `poi_attributes` are scheduled, instead of `categories` / `analysisdata` / `locations` - read the ids with `dataset: poi`, `catalog: attributes` and `catalog: attribute-values` - see POI attributes. 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`. A replay answers with the estimate as it is now and waits again. Same body as `create_audience`. Read-only: nothing is created. Waits up to about 12 seconds for the answer and returns the estimate as it is then: `completed` with the numbers, `blocked` or `failed`, or still `pending` / `processing`, which means calling `get_audience_estimate` in the same turn. Some estimates, such as two combined datasets, still take about as long as a real build: after about 8 pending calls (about 2 minutes) the agent stops and gives the user the estimate id to read later. Metered on the bytes it scans, toward the monthly data-scan limit (`estimate` on `get_usage`), and refused with the quota `422` once the limit is reached. For a `Demographics` dataset, `data[0].estimate.vintage` (`YYYY-MM`) is the monthly vintage the numbers come from, and the agent reports them as “latest monthly vintage, as of YYYY-MM”.
`get_audience_estimate`	`GET /api/v2/analyses/audiences/estimate/{id}`	Reads with `wait=15`: waits up to 15 seconds and returns as soon as `data[0].status` is `completed`, `blocked`, or `failed`. While it is `pending` or `processing`, call it again in the same turn, up to about 8 calls (about 2 minutes): some estimates, such as two combined datasets, still take about as long as a real build. At most 5 calls of an organization, and 25 across all organizations, wait at once. Another one answers at once. Only one call waits per estimate: a newer call for it takes the wait over. For a `Demographics` dataset, `data[0].estimate.vintage` (`YYYY-MM`) is the monthly vintage the numbers come from, and the agent reports them as “latest monthly vintage, as of YYYY-MM”.
`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.
`quote_audience`	`POST /api/v2/analyses/audiences/quote`	Listed only for an organization billed in credits. Same body as `create_audience`, without `idempotency_key`, and the same `422`s. Read-only and free: nothing is created. Returns the price in `data[0].credits` and the credits left after the run in `data[0].available_after`. Its description tells the agent to quote before every `create_audience` and to create only once the user agrees.
`quote_lookalike_audience`	`POST /api/v2/analyses/audiences/quote-lookalike`	Listed only for an organization billed in credits. Same body as `create_lookalike_audience`, without `idempotency_key`. Read-only and free. A lookalike costs the same for any size.

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 directly, and the API does not proxy it.
`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). The activation takes the price of its pricing model (`pricing_model_id`). `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. Also takes the activation limits: a Lookalike Model’s score range (`score_limit` with `min_score` / `max_score`) and, for an audience of one Transactions dataset, spend and transaction ranges (`affinity_spend_limit` / `affinity_txn_limit` with their bounds), each behind its explicit flag.
`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. A location may give an address instead of coordinates, and Intuizi geocodes it, or give coordinates without a country or address fields, and Intuizi fills them from the point. Intuizi also checks the locations before the review, and the checks only flag. Past 10,000 lookups a submission, the rest waits for Intuizi’s team (see Files past the limit, Locations without coordinates, Locations without an address, and Checks of locations). 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. The name needs at least one letter or digit and must differ from your company’s other project names (case ignored).

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. For an organization billed in credits, `credits` carries the balance of the current period (`null` otherwise).

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