Tools

The Teads MCP server exposes tools (actions the assistant calls). Ask in natural language; the assistant picks the right tool and fills in the parameters below on your behalf. This page documents every tool for people who want to understand exactly what the assistant can do, or who are building a custom MCP client.

Tasks vs. polling

A few operations — custom reports, the campaign reach dashboard, and the media barometer — run as background jobs because they take longer than a single request/response cycle. Each of these comes in two forms:

• Task tools (name ends in _task, or reporting_create_task): one blocking call. If your MCP client supports MCP Tasks, the server submits the job, polls it internally, and returns the finished result — you never call a separate polling tool.
• Submit + poll + result: for clients without MCP Tasks support. Call the _submit/_create tool to start the job, poll a status tool until it reports done, then call a result tool to fetch the data.

Prefer the task tool when your client supports it — it is fewer round trips for the same result.

Every tool response includes a _meta field telling you where the data came from: api-domains (campaign setup data) or reporting (the reporting API). You don't need to do anything with it — it's informational.

Seats and campaigns

list_my_seats

Lists the seats (ad accounts) accessible to the authenticated profile (SSO user or M2M machine identity): seat ID, name, and account type. Call this first — campaign_read, reporting_create, and the insight tools all take a seat_id from this list.

{
  "seats": [{ "id": 12345, "name": "Acme Agency", "account_type": "SEAT" }]
}

Example prompt: "Which seats can I access?"

get_campaign_seat

Looks up the seat that owns a campaign, when you only know the campaign_id. Use it to resolve seat_id before calling campaign_read or reporting_create if you don't already have it from list_my_seats.

{ "buyer_seat_id": 25193 }

Example prompt: "Which seat owns campaign 606714?"

campaign_read

Returns one campaign in full: metadata, status, flight dates, budget, insertion order lines, line items (billing model, pricing type, channel type, booked budget/volume, flight dates, deal info, targeting), and creatives.

Example prompt: "Show me campaign 606714."

Notes:

• Read-only — campaign_read never changes campaign data.
• Budgets are in the campaign's own currency; flight dates are Unix timestamps (flight_start_unix / flight_end_unix).
• Targeting fields (standard_audiences, teads_contextuals, device_types, …) reference segments by numeric ID — resolve them with list_taxonomy, see below.

Response shape:

insertion_order_lines[]: id, name, flight_start_unix, flight_end_unix, booked_volume, booked_budget, billing_model (e.g. CPM, VCPM), billing_model_rate, billing_event, auction_type (FIXED or DYNAMIC), creative_type_family (VIDEO or DISPLAY), is_guaranteed.

line_items[]: id, name, status, insertion_order_line_id, channel_type (WEB_AND_IN_APP or CONNECTED_TV), billing_model, pricing_type (DYNAMIC/FIXED), event_gross_rate, billing_price, booked_volume, booked_budget, min_margin, flight_start_unix, flight_end_unix, start_mode, has_pixel, is_guaranteed, deal (deal_id, deal_id_key, CPM rate), advertising_solution_id (e.g. AWARENESS, TA_CLICKS, TA_VISITS), targeting.

line_items[].targeting — every field optional; include/exclude lists use { "includes": [...], "excludes": [...] }: is_cookieless_criteria_only, locations, gender_audience, age_audiences, demographic_audiences_accuracy, languages, language_codes, device_languages, device_types, device_operating_systems, device_browsers, device_platform_environment, device_connection_types, device_internet_service_providers, mobile_device_brand, mobile_device_model, mobile_device_category, mobile_device_carrier, mobile_device_year, standard_audiences, narrowed_standard_audiences, teads_contextuals, ctv_custom_contexts, custom_audiences.

creatives[]: id, name, status, format_type_family (e.g. Video, Banner), format_type (e.g. Outstream), format_size (width × height), created_at_unix.

list_taxonomy

Resolves the numeric targeting IDs found in a campaign_read response into human-readable labels. No seat_id needed — the catalogs are the same for everyone.

device_types values: 0 = Desktop, 1 = Smartphone, 2 = Tablet, 3 = Smart TV / CTV. Example prompt: "What do these device and audience IDs mean?"

Reporting

list_reporting_dimensions

Lists every valid dimension field name for reporting_create/reporting_create_task, with a label and description for each.

Example prompt: "What dimensions can I break a report down by?"

list_reporting_metrics

Lists every valid metric field name for reporting_create/reporting_create_task. Only named metrics (ones with a description) are returned.

Currency-converted variants aren't listed individually but follow a fixed pattern: replace the trailing _value with _converted_<ISO-4217 code> — for example budget_delivered_value → budget_delivered_converted_eur. Use that pattern directly when you need a specific reporting currency.

Example prompt: "What metrics can I put in a report, and can I get spend in EUR?"

reporting_create

Schedules an asynchronous custom report and returns a report_id immediately — the row data is never in the response. Poll reporting_wait_for for the download link. Use this for file exports (CSV/xlsx), multi-dimension breakdowns, or portfolio-wide questions ("which campaigns are under-delivering?", "total spend for advertiser X?").

options fields: callback_url (webhook called on completion), id_data_destination, s3_target_bucket_name, s3_target_directory, s3_custom_file_name.

dimension_filters operators — wrap a value as {"<op>": value} or an array of such objects for a range: gt, lt, gte, lte, ne, like, not_like, not_in, length.

{ "ad_id": 606714 } // single campaign
{ "ad_id": [606714, 606715], "country_code": "FR" } // multiple campaigns + country
{ "advertiser_name": "Renault" } // by advertiser name — no lookup call needed first
{ "impression": [{ "gte": 1000 }, { "lte": 50000 }] } // numeric range

Response:

{
  "report_id": "rpt-a1b2c3d4-...",
  "status": "queued",
  "submitted_at": "2026-05-26T12:00:00Z",
  "report_progress": null
}

status is queued, processing, finished, or failed.

Example prompt: "Export impressions and clicks by day for the last 7 days as CSV."

reporting_create_task

The task-tool form of reporting_create — same parameters, but blocks until the report finishes and returns the download URI directly (no reporting_wait_for needed). Requires a Tasks-capable client.

reporting_wait_for

Checks one report job started by reporting_create. Returns the download URI once the job's status is finished.

Poll at most 6 times, 10 seconds apart. If it still isn't finished, stop and say so rather than continuing to poll indefinitely.

{
  "report_id": "rpt-a1b2c3d4-...",
  "status": "finished",
  "uri": "https://cdn.teads.com/reports/rpt-a1b2c3d4-....csv",
  "report_progress": { "stepMax": 4, "step": 4, "progressMax": 100, "progress": 100 }
}

uri is present only once status is finished.

Example prompt: "Is report 987654 ready?"

get_running_reports

Lists custom reports that are still queued or processing for the authenticated profile (SSO or M2M) — no parameters. Useful to check on in-flight jobs without knowing their IDs.

{
  "reports": [{ "report_id": "rpt-xyz...", "status": "processing", "submitted_at": "2026-05-26T11:45:00Z" }]
}

Example prompt: "What reports are still running?"

Audience insights

Teads' first-party audience intelligence, drawn from readership signals across 3,000+ premium publishers. Returns a dimension tree — sociodemographic, interests, intents, technology, top sites, and more — where each leaf carries a relative index (> 1.0 = over-represented versus the baseline) and a confidence level (0 Low — index hidden, 1 Medium, 2 High).

Top-level dimensions in the response: Sociodemographic, Interest, Intent, Audiences, Owners, Technology, Page Topics, Top Websites, Top Placements, Top Mobile Models. Category-level nodes under Sociodemographic, Interest, and Intent don't carry stats — only their leaves do.

audience_insights

Query by campaign entity (you need view permission on the resource; no date range needed — the campaign's own flight is used):

{ "type": "ad",                   "request": { "id": 606714 } }
{ "type": "insertion",            "request": { "id": 123456 } }
{ "type": "insertion-order-line", "request": { "id": 789012 } }
{ "type": "connection",           "request": { "id": 345678 } }

Query by audience definition (country + date range required):

{
  "type": "custom-audience",
  "request": {
    "customAudiences": [42],
    "country": "FR",
    "startDate": "2024-01-01",
    "endDate": "2024-03-31"
  }
}

{
  "type": "segment",
  "request": {
    "dataProviderSegments": [{ "dataProvider": "oracle", "segmentIds": ["seg-1"] }],
    "country": "FR",
    "startDate": "2024-01-01",
    "endDate": "2024-03-31"
  }
}

{
  "type": "device",
  "request": {
    "deviceVendor": "Apple",
    "deviceStandardisedName": null,
    "country": "FR",
    "startDate": "2024-01-01",
    "endDate": "2024-03-31"
  }
}

Valid dataProvider values for segment: oracle, nielsen, teads_conversions, teads_contextual, emetriq, liveramp, neustar, retargetly, salesforce, teads, skp, lotame.

Example prompt: "Who are the readers of insertion 123456?"

Campaign reach & measurement

measurement_campaign_reach_dashboard_task / _submit

Measures the de-duplicated reach of a Teads campaign across Web & Mobile App, CTV Homescreen (native), and CTV Instream, and — when a linear TV, BVOD, SVOD, or FAST reach figure is supplied — Teads' incremental reach on top of that external platform. Use it for "how many unique people did this campaign reach?", reach %, frequency, cost per reach point, channel overlap, or incremental reach versus TV.

_task is the single-call form (Tasks-capable clients); _submit starts the job for clients that poll manually (see status and result below). Both take the same parameters.

Example prompt: "How many unique people did campaign 606714 reach in France, and how much extra reach did we add over linear TV?"

measurement_campaign_reach_dashboard_status

Polls a job started by _submit.

Returns {"status": "PENDING" | "RUNNING" | "DONE"}. Typical latency is 10–60 seconds — poll every 5–10 seconds and stop after about 20 attempts.

measurement_campaign_reach_dashboard_result

Fetches the finished report once _status reports DONE.

Returns four sections:

base — aggregate campaign metrics: reach (fraction of target universe, 0–1), users, frequency, impressions, costPerReachPoint, deliveredBudget, and — only when tvExtendPercentage was supplied — incrementalReach, incrementalUsers, costPerIncrementalReachPoint.

dailyReachAndBudgets — array of {day, reach, incrementalReach?, users, incrementalUsers?, budgetWeb, budgetCtv, budgetCtvNative, cumulatedBudget}, for charting delivery pacing.

reachDistribution — Venn decomposition of shared reach: webAndMobileOnly, ctvOnly, ctvNativeOnly, the pairwise intersections between digital channels, and — when TV data is available — linearTvOnly, the digital/TV intersections, and allIntersect.

channelDetails — webAndMobile, ctv, and ctvNative sub-objects, each shaped like base.

→ measurement_campaign_reach_dashboard_submit(campaignId=606714, startDate="2024-03-01", endDate="2024-03-31", country="FR")
← { "jobId": "ir-abc123" }

→ measurement_campaign_reach_dashboard_status(jobId="ir-abc123")
← { "status": "RUNNING" }

→ measurement_campaign_reach_dashboard_result(jobId="ir-abc123")
← { "base": { "reach": 0.12, "incrementalReach": 0.04, "users": 1200000, ... }, "dailyReachAndBudgets": [...], "reachDistribution": {...}, "channelDetails": {...} }

Example prompt: "Is the reach dashboard for job ir-abc123 ready?"

Media planning

planning_media_barometer_task / planning_media_barometer

The Teads Media Barometer: a discovery tool that tells you when an audience is most engaged with a topic, content category, keyword, or brand, drawing on readership signals across 3,000+ premium publishers and Teads' contextual intelligence. Covers Web & Mobile App only — CTV is not included. Use it for timing questions: "best time to run a campaign for [category] in [country]", seasonal peaks, whether interest in a keyword is rising or declining, which weeks to prioritize.

Query with free-text keywords, with an item from the contextual taxonomy (teads://taxonomy/contextual), or both — you can compare several keywords or contextual items in one call.

_task is the single-call form (Tasks-capable clients: submits, polls, and returns the finished report). The non-task form returns three job IDs to poll manually — see planning_get_status and planning_get_result.

Example prompt: "When is interest in 'electric vehicles' peaking in France this quarter?"

planning_get_status

Polls the three jobs returned by planning_media_barometer.

{ "main": { "state": "done" }, "audience": { "state": "done" }, "context": { "state": "done" } }

Returns a status per job (pending, running, done). Poll until all three are done.

planning_get_result

Fetches the typed results once all three jobs are done. Same main / audience / context parameters as planning_get_status.

Knowledge

list_knowledge

Lists the curated playbooks and reference docs available on the server — each with a URI and description. Mainly useful for MCP clients that don't support resource discovery, or for anyone building a custom client who wants to see the server's built-in guidance for common workflows.

read_knowledge

Returns the markdown content of one knowledge concept by URI (from list_knowledge).