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. With dataset: skus, catalog: insights needs dimension (brand, merchant, category, or total) and takes period, category, merchant, and limit, and catalog: coverage takes none - see SKUs. 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. The purchase catalogs
of the Transactions dataset are the transactions group, and its
audience-create type is Transactions - see
Transactions reference. An audience built from
the retired merchant-level dataset reads as type TransactionsLegacy, which
create_audience rejects. These are the MCP names: the REST API and the CLI
name this type, its group and its activation limits differently (see their
reference pages), and the MCP server still accepts those names.
Audiences
| Tool | Wraps | Notes |
|---|---|---|
list_audiences | GET /api/v2/analyses/audiences/index | search, page, per_page. Items leave out analysis_results: read it with get_audience. |
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. For an audience built with a networkswitching block, analysis_results.network_switching is null until the analysis finishes (and for good if the build fails), then it counts the devices that kept, changed, and switched their network - see Analysis results. The results say source connectivity and version 2, and from and to hold the two weeks compared. The tool shows a short view of it: the networks have no top_from and top_to, and only the 20 largest flows are listed. Every network row and every total is still there. Get Audience and the CSV hold the full lists. For any other audience analysis_results is an empty object. list_audiences items do not carry it. |
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). A Connectivity block (available on request) names a home internet network or a mobile carrier: read the names with dataset: connectivity, catalog: networks (kind, search), and the sources with catalog: signal-providers and dataType: Connectivity. A SKUs block (available on request) names merchants, product brands or product categories, at least one of the three: read the keys with dataset: skus, catalog: merchants and catalog: brands (search, and categories to narrow the brands), and the category ids with catalog: categories (parent_id to walk the tree, or search). device_types, device_oses, device_makes and device_models filter the purchase click’s device, with values from catalog: device-values and field (type, os, make, model). It takes no signal_providers, its location reads countries and states only, and max_devices_per_ip sets its Match Strictness (1 to 5, default 3) - see SKUs. A SKUs block also takes the spend filters item_price_min / item_price_max (USD per purchased item), spend_min / spend_max (USD a home network spent in the window), orders_min / orders_max (its orders) and spend_top_percent (50, 25, 10, 5 or 1); create_audience and estimate_audience_size accept all seven - see Spend filters. A SKUs dataset combines with one other dataset of the types Combining a SKUs dataset lists, and an audience with one takes no analysis and no refine (a 422). 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; left out, the default set anomalous_devices + strict_gps applies, [] turns every filter off, a two-POI audience needs the same set on both blocks, and next to a Transactions block a non-empty list is a 422) - 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. A networkswitching block (from_month and to_month as YYYY-MM, optional network_type and min_home_days) compares each device’s home network in the last full Monday-to-Sunday week of two months, on an audience with one Connectivity dataset (any other audience is a 422), and it cannot be sent together with a crosspurchase block (a 422). Both weeks must be built for the dataset’s signal providers (otherwise a 422 names the weeks that are built), the dataset keeps its own dates, and the result is read with get_audience - see Network Switching. For a question such as “how many devices switched to Starlink”, the tool description asks for one Connectivity dataset with connectivity_network_kind home, the network in connectivity_networks (or none for any network), every provider of its signal-providers catalog, and location.countries USA. 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. An estimate cannot count devices that switched their network between two months, for example to Starlink: use create_audience with a networkswitching block on one Connectivity dataset. A single-dataset POI estimate at country or state level, Transactions estimate by brands or categories, or CTV estimate at country or state level, optionally with vendors or with channel names, usually comes back completed at once, with method sketch and as_of (when its data was read): a fast answer. 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. An estimate can take minutes, for example AND, OR, NOTIN, and city, DMA, or ZIP requests: 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. A fast answer is metered on the bytes it reads and does not count toward the build budget. 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”. The same recipe sent again while an estimate of it is still running, or within 10 minutes after that run completed, gets a new estimate that shares that run (data[0].reused_from): not metered, not counted toward the build budget. A fast answer is not shared: the same recipe sent again is usually answered again, often in about a second. A POI estimate gets a fast answer only with the default filters: left out, or exactly anomalous_devices and strict_gps. An estimate with filters: [] or any other set goes to a worker, which is slower and counts toward the build budget. |
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). An estimate can take minutes, for example AND, OR, NOTIN, and city, DMA, or ZIP requests. 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”. data[0].reused_from is null, or the estimate whose run this one shares and ends with. method says how the number was made: sketch for a fast answer, approx_set or approx_distinct for a full estimate. A fast Transactions answer leaves transactions, amount, online_transactions, and the four ratios (avg_amount_per_scid, avg_transaction_value, avg_transactions_per_scid, and online_share) null in totals, not 0. A fast CTV answer gives uniques (CTV viewers), signals, and unique_eips (households). |
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 422s. 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 (transactions_spend_limit / transactions_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, and row_filters keeps only the rows whose columns hold the chosen values (csv and gzip); source: audience builds from a Completed audience (audience_id). match_months: source “file” with identifier_type scid only: months of SCID links to match, 1 (latest month) to 3. Each SCID uses its most recent month in that window. Default 1. |
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. |
scan_cohort_file | POST /api/v2/analyses/cohorts/scan | Counts the rows of a csv or gzip file by the values of 1 to 5 columns (never the identifier_column), before create_cohort with row_filters. Same file_uri / upload_reference as the preview, and does not consume the reference. Takes no idempotency_key: the same file and columns sent again answer the scan that is running, or that completed in the last hour. Answers at once at status 2. Read it with get_cohort_file_scan. |
get_cohort_file_scan | GET /api/v2/analyses/cohorts/scan/{id} | At status 4: total_rows and the row count of each combination of values (combinations, at most 1,000, truncated when more existed). At 5: message says why. A scan usually takes under a minute, and this read does not wait. |
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/transactions | 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 |
intuizi://docs/api/reference/connectivity | Connectivity reference |
intuizi://docs/api/reference/skus | SKUs 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.