> ## Documentation Index > Fetch the complete documentation index at: https://docs.semicola.com/llms.txt > Use this file to discover all available pages before exploring further. # v3 Tool Catalog > Every tool the Semicola v3 MCP endpoint can list, with its effect, risk, widget and input fields. This page lists every model-visible tool on `https://api.semicola.com/mcp/v3` (10 shared, 54 buyer, 39 seller). It is generated from the same contracts the server uses to validate calls, so field names and constraints here match what the server accepts. `tools/list` is still the contract for your session. The tools you see depend on the active account (buyer, seller or organization), your role and feature availability. Tools marked P1 or P2 may not be listed yet. ## How to read this page * **Effect** is `read` or `write`. Reads never change state and are always safe to retry. * **Risk** says what a write can touch. Durable writes change saved records; spend writes can commit budget; external writes contact a seller or buyer. In the app and in MCP hosts, risky writes pause for an explicit confirmation from the person you act for. * **Opens widget** names the MCP App the tool renders in hosts that support MCP Apps (`_meta.ui.resourceUri`). Hosts without MCP Apps receive the same data as structured content plus a text summary. * **Input** is flattened from the tool's JSON Schema. Nested fields use dots (`budget.total`); items of an array of objects use `[]` (`products[].productId`). A nested field marked required is required only when its parent is sent. Some tools accept one of several forms; each form has its own table. For failure shapes see [Errors](/v3/errors); for size and time bounds see [Limits](/v3/limits). ## Shared tools Available on every account, buyer or seller. Start every session here. | Tool | Effect | Priority | Summary | | -------------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `get` | Read | P0 | Read one object by kind and id, with optional includes. | | `get_delivery` | Read | P0 | Delivery report. | | `get_status` | Read | P0 | Where this account stands: active account and role, readiness, blockers, next actions and the other accounts you can switch to. | | `open_iu_plan_task` | Read | P1 | Open the "Choose an IU plan" task: the current Rate Card plans for this billing organization. | | `open_page` | Read | P0 | Open a page by name. | | `save_ask` | Write | P1 | File a request with the team (support, product, supply, integration or commercial; omit type if unclear), one ask per call. | | `save_billing` | Write | P1 | Accept the current Terms (\{terms: \{accepted: true, version}}, direct organization admins) or set up a card as the payment authority (\{paymentAuthority: \{action}}): "request" returns a confirmationToken; "confirm" with it returns a one-time link for the cardholder (card data never passes through here); poll "status" every 15–30 s until verified or expired. | | `save_notification_config` | Write | P1 | Save your notification preferences for this account: switch email or in-app notifications on or off per type ("campaign.unhealthy") or per family ("campaign"). | | `search` | Read | P0 | Find objects, docs or spec pages by text and/or kind (advertiser, campaign, proposal, rfp, …). | | `switch_account` | Write | P0 | Switch the active account (a customerId from get\_status, or "home"). | ### `get` Read one object by kind and id, with optional includes. Use it to check on long operations you started. | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | -------------------------- | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `kind` | `enum` | Yes | One of `advertiser`, `campaign`, `creative`, `creative_format`, `creative_collection`, `wholesale_product`, `proposal`, `media_buy`, `seller`, `connection`, `ask`, `catalog`, `measurement_source`, `creative_engine`, `creative_session`, `conversation`, `skill`, `buyer_agent`, `dimension`, `inventory_source`, `material`, `rfp`, `rfp_turn`, `library_request`, `coverage`, `playbook`, `business_rules`, `work_item`, `signal`, `agent`, and 1 more. | | `id` | `string` | No | | | `include` | `string[]` | No | | | `advertiserId` | `integer \| string` | No | | | `filter` | `object` | No | | | `cursor` | `string` | No | ≤ 64 chars. | | `limit` | `integer` | No | min 1, max 50. | | `connectionAccountsOffset` | `integer` | No | min 0, max 100000. | | `connectionMappingsOffset` | `integer` | No | min 0, max 100000. | | `sourceId` | `string` | No | 1–64 chars. | ### `get_delivery` Delivery report. Buyers use report "campaign\_delivery"; sellers "seller\_delivery", or "campaign\_delivery" for their own-supply advertisers (name the advertiser, campaign or media buy). Ranges ≤ 90 days or lifetime; a packageId filter needs a bounded range. Missing metrics are unavailable, never 0. | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | None (text result) | **Input** The input is one of 2 forms. Send exactly one; fields from different forms do not mix. **Form 1: `report: "campaign_delivery"`** | Field | Type | Required | Notes | | ------------------------ | ----------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `report` | `const` | Yes | Always `"campaign_delivery"`. | | `metrics` | `enum[]` | Yes | Each one of `impressions`, `clicks`, `spend`, `ctr`, `cpm`, `views`, `video_completions`, `vcr`, `viewable_impressions`, `conversions`, `conversion_value`, `pacing`. ≥ 1 items. | | `dimensions` | `(enum \| const \| string)[]` | No | Each item: Or `"channel_group"`. Default `[]`. | | `range` | `object` | Yes | Object form: `startDate`, `endDate`. Object form: `lifetime`. | | `filters` | `object` | No | | | `filters.advertiserId` | `integer \| string` | No | | | `filters.campaignId` | `string` | No | | | `filters.mediaBuyId` | `string` | No | | | `filters.packageId` | `string` | No | | | `filters.channelGroupId` | `string` | No | | | `limit` | `integer` | No | min 1, max 1000. | | `cursor` | `string` | No | | **Form 2: `report: "seller_delivery"`** | Field | Type | Required | Notes | | ------------------------- | ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `report` | `const` | Yes | Always `"seller_delivery"`. | | `metrics` | `enum[]` | Yes | Each one of `impressions`, `clicks`, `spend`, `ctr`, `cpm`, `views`, `video_completions`, `vcr`, `viewable_impressions`, `conversions`, `conversion_value`, `pacing`. ≥ 1 items. | | `dimensions` | `enum[]` | No | Each one of `date`, `campaign`, `media_buy`, `package`, `seller`, `sales_agent`, `buyer`, `product`. Default `[]`. | | `range` | `object` | Yes | Object form: `startDate`, `endDate`. Object form: `lifetime`. | | `filters` | `object` | No | | | `filters.mediaBuyId` | `string` | No | | | `filters.buyerCustomerId` | `integer \| string` | No | | | `limit` | `integer` | No | min 1, max 1000. | | `cursor` | `string` | No | | ### `get_status` Where this account stands: active account and role, readiness, blockers, next actions and the other accounts you can switch to. Call first when unsure what to do. | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | None (text result) | **Input** No arguments. ### `open_iu_plan_task` Open the "Choose an IU plan" task: the current Rate Card plans for this billing organization. Admins accept inside the task. | | | | ------------ | ------------------------------------------------ | | Effect | Read | | Risk | None | | Priority | P1 | | Opens widget | `iu-plan` (`ui://semicola/iu-plan/mcp-app.html`) | **Input** No arguments. ### `open_page` Open a page by name. The page field lists the buyer and seller pages; arguments focus the page. | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ----------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `page` | `enum` | Yes | Buyer pages: activity, marketplace, event\_sources, catalogs, advertiser\_setup, creative\_library, creative\_composer\_task, reporting. Seller pages: seller\_setup, business\_rules, playbook, listing, demand\_inbox, media\_buy\_timeline, seller\_dashboard, library, components, signals, pending\_operations, test\_runs, property\_roster, source\_diagnostics, modular\_source\_setup, modular\_inventory\_source, modular\_inventory\_feed, source\_discovery\_preview, buyer\_account\_mapping, demo\_seller, proposal\_studio. One of `activity`, `marketplace`, `event_sources`, `catalogs`, `hello`, `escalations`, `release_notes`, `advertiser_setup`, `creative_library`, `creative_composer_task`, `reporting`, `seller_setup`, `business_rules`, `playbook`, `listing`, `demand_inbox`, `media_buy_timeline`, `seller_dashboard`, `library`, `components`, `signals`, `pending_operations`, `test_runs`, `property_roster`, `source_diagnostics`, `modular_source_setup`, `modular_inventory_source`, `modular_inventory_feed`, `source_discovery_preview`, `buyer_account_mapping`, and 2 more. | | `arguments` | `object` | No | Page focus: \{campaignId}, \{rfpId, turnId}, \{sourceId, sourceName?}, \{tab: "changes"} for activity. | ### `save_ask` File a request with the team (support, product, supply, integration or commercial; omit type if unclear), one ask per call. Or pass an ask id with requesterState (confirmed\_resolved, accepted, still\_blocked, withdrawn) and an optional note to record the requester's answer. | | | | ------------ | ----------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | ---------------------------------------------------------------------- | | `id` | `string` | No | 1–64 chars. | | `requesterState` | `enum` | No | One of `confirmed_resolved`, `accepted`, `still_blocked`, `withdrawn`. | | `note` | `string` | No | ≤ 2000 chars. | | `type` | `enum` | No | One of `support`, `product`, `supply`, `integration`, `commercial`. | | `title` | `string` | No | 1–200 chars. | | `detail` | `string` | No | ≤ 4000 chars. | | `subject` | `string` | No | ≤ 200 chars. | | `channel` | `string` | No | | | `severity` | `enum` | No | One of `low`, `medium`, `high`. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `save_billing` Accept the current Terms (\{terms: \{accepted: true, version}}, direct organization admins) or set up a card as the payment authority (\{paymentAuthority: \{action}}): "request" returns a confirmationToken; "confirm" with it returns a one-time link for the cardholder (card data never passes through here); poll "status" every 15–30 s until verified or expired. Exactly one intent per call. | | | | ------------ | ----------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ------------------------------------ | --------- | -------- | -------------------------------------- | | `terms` | `object` | No | | | `terms.accepted` | `const` | Yes | Always `true`. | | `terms.version` | `string` | Yes | 1–64 chars. | | `paymentAuthority` | `object` | No | | | `paymentAuthority.action` | `enum` | Yes | One of `request`, `confirm`, `status`. | | `paymentAuthority.confirmationToken` | `string` | No | 1–128 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `save_notification_config` Save your notification preferences for this account: switch email or in-app notifications on or off per type ("campaign.unhealthy") or per family ("campaign"). Omit channel for both. Always-on types stay on. | | | | ------------ | ----------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | -------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `preferences` | `object[]` | Yes | ≥ 1 items, ≤ 100 items. | | `preferences[].notificationType` | `enum` | No | One of `campaign.healthy`, `campaign.unhealthy`, `campaign.created`, `campaign.updated`, `campaign.deleted`, `campaign.completed`, `creative.approved`, `creative.rejected`, `creative.changes_requested`, `creative.sync_started`, `creative.sync_completed`, `creative.sync_failed`, `creative.review_requested`, `media_buy.created`, `media_buy.updated`, `media_buy.deleted`, `media_buy.forward_failed`, `media_buy.awaiting_source_moderation`, `media_buy.source_rejected`, `media_buy.stuck`, `media_buy.approval_requested`, `media_buy_update_proposal.approved`, `media_buy_update_proposal.rejected`, `media_buy_update_proposal.expired`, `optimization.suggestion_received`, `optimization.suggestion_approved`, `optimization.suggestion_rejected`, `optimization.suggestion_applied`, `optimization.suggestion_failed`, `salesagent.available`, and 20 more. | | `preferences[].category` | `string` | No | 1–64 chars. | | `preferences[].channel` | `enum` | No | One of `email`, `in_app`. | | `preferences[].enabled` | `boolean` | Yes | | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `search` Find objects, docs or spec pages by text and/or kind (advertiser, campaign, proposal, rfp, …). Needs query or kind. | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | --------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `query` | `string` | No | 1–500 chars. | | `kind` | `enum` | No | One of `advertiser`, `campaign`, `creative`, `creative_format`, `creative_collection`, `wholesale_product`, `proposal`, `media_buy`, `seller`, `connection`, `ask`, `catalog`, `measurement_source`, `creative_engine`, `creative_session`, `conversation`, `skill`, `buyer_agent`, `dimension`, `inventory_source`, `material`, `rfp`, `rfp_turn`, `library_request`, `coverage`, `playbook`, `business_rules`, `work_item`, `signal`, `agent`, and 1 more. | | `sources` | `enum[]` | No | Each one of `objects`, `docs`, `spec`. | | `filter` | `object` | No | | | `limit` | `integer` | No | min 1, max 100. | | `cursor` | `string` | No | | ### `switch_account` Switch the active account (a customerId from get\_status, or "home"). Returns the new status. | | | | ------------ | ------------------ | | Effect | Write | | Risk | None | | Priority | P0 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ------------ | ---------------------------- | -------- | ------------ | | `customerId` | `integer \| string \| const` | Yes | Or `"home"`. | ## Buyer tools Listed when the active account is a buyer (advertiser or agency). | Tool | Effect | Priority | Summary | | ---------------------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `analyze_account` | Read | P1 | Analyze a connected ad-platform account (Meta, Google Ads, TikTok, Snap, Pinterest, Reddit, LinkedIn, Amazon Ads, Spotify) through the buyer's own linked account: account health, the last 30 days of delivery by campaign, and recommendations. | | `approve_optimization_suggestion` | Write | P1 | Approve an optimization suggestion and apply its budget change to the media buys (a live buy's change goes to its seller). | | `attach_creatives_to_campaign` | Write | P1 | Attach creatives saved by get\_creative\_intent (their creativeIds) to a campaign, then show the "here's what I added" card with format coverage. | | `attach_property_list_to_campaign` | Write | P1 | Push an advertiser include list to every active media buy in a campaign (for lists created after the buys went live). | | `auto_select_products` | Write | P1 | Auto-select products for a campaign based on brief and budget. | | `cancel_update_proposal` | Write | P1 | Cancel a PENDING update proposal so a corrected update can proceed. | | `check_property_list` | Read | P1 | Validate a candidate identifier set without creating a list: returns ok, modify (canonicalized), remove (duplicate or blocked) and assess (manual review; every mobile/CTV identifier) buckets, and a reportId when domains were checked. | | `create_property_list` | Write | P1 | Create a named include or exclude property list for an advertiser from domains and/or typed identifiers (web, mobile, CTV). | | `delete_property_list` | Write | P1 | Archive a property list: it stops shaping future discovery and media buys. | | `execute_catalog_activation_plan` | Write | P1 | Activate a catalog from its saved transform: creates one draft campaign per campaign group, queues creative generation and records seller feed sharing. | | `generate_variants` | Write | P0 | Execute one saved creative session revision through its engine connection with the buyer's own provider key. | | `get_campaign_property_lists` | Read | P1 | The property lists actually applied to a campaign through its media buys' packages. | | `get_creative_confirmation` | Read | P1 | Re-show a campaign's creative card (its creatives with status and format coverage). | | `get_creative_intent` | Write | P1 | Open the "Which campaign are these for?" picker when the person brings finished creative (images, video, audio, tag sheets, HTML5 bundles) into chat. | | `get_optimization_suggestion` | Read | P1 | Read one optimization suggestion: the proposed budget change, its rationale and the pacing recommendation. | | `get_property_list` | Read | P1 | Get one property list with its resolved identifiers, domains and filters. | | `get_property_list_report` | Read | P1 | Get the bucket summary of an earlier property list check by reportId (kept 7 days). | | `get_update_proposal` | Read | P1 | Poll a media buy update proposal: PENDING until the seller approves (APPROVED) or declines (REJECTED, with rejectionReason). | | `list_audiences` | Read | P1 | List an advertiser's synced audiences with status (PROCESSING, READY, ERROR, TOO\_SMALL), uploaded and matched counts. | | `list_catalogs` | Read | P1 | List the advertiser's catalog feeds with health, item counts, versions, refresh runs, transform and activation jobs. | | `list_geo_metros` | Read | P1 | Compatibility shortcut for listing Nielsen DMA geo metro code-name pairs. | | `list_optimization_suggestions` | Read | P1 | List optimization suggestions for your media buys, optionally by campaign, media buy or status (received = waiting for your approval). | | `list_property_lists` | Read | P1 | List an advertiser's property lists (include and exclude) as summaries: listId, name, purpose, propertyCount. | | `list_targeting_dimension_values` | Read | P1 | List code-name pairs for a targeting dimension. | | `list_targeting_dimensions` | Read | P1 | List supported targeting dimensions and the campaign constraint fields that accept them. | | `log_event` | Write | P1 | Log up to 10,000 conversion events to an event source (server-to-server). | | `open_advertisers_page` | Read | P0 | Open the advertisers list. | | `open_campaign_receipt` | Read | P0 | Open Review & go live for a draft campaign: plan, staged buys, budget, creative coverage and blockers. | | `open_campaigns_page` | Read | P0 | Open campaigns for the advertiser in scope, or one campaign workspace when campaignId is given. | | `open_connections_page` | Read | P0 | Open the sellers page. | | `open_creative_engines_page` | Read | P0 | Open the Creative Engines page (Connected and Available engines; enrolled Buyer Accounts). | | `preview_catalog_activation_plan` | Read | P1 | Preview what activating a catalog would create: campaign groups, creative assets and which connected sellers can take the catalog. | | `refine_proposal` | Write | P0 | Ask one seller to revise a proposal (keep or drop products, shift budget, new instructions). | | `refresh_catalog` | Write | P1 | Fetch a URL catalog feed now and store a new version when items changed. | | `reject_optimization_suggestion` | Write | P1 | Reject an optimization suggestion, with an optional reason. | | `request_proposals` | Write | P0 | Send the campaign brief to every eligible seller and collect proposals. | | `resolve_targeting_dimension` | Read | P1 | Resolve localized targeting text, DMA names, aliases, and messy buyer spreadsheet labels to code candidates within a specific dimension. | | `save_advertiser` | Write | P0 | Create, update, archive an advertiser, or preview a brand with \{resolveBrand: domain}. | | `save_buyer_agent` | Write | P1 | Create an external buyer agent (omit id; displayName, kind "external"), or change one agent by id with exactly one of: displayName, access (complete advertiser list plus expectedAccessRevision), or lifecycle (suspend \| resume \| retire with expectedLifecycleState; suspend and retire need the exact name as confirmationText). | | `save_campaign` | Write | P0 | Create a DRAFT campaign or change one. | | `save_catalog_transform` | Write | P1 | Save the transform recipe for a catalog: the item fields to group campaigns by, a creative prompt (\{field} placeholders take each group's values) and a budget per group. | | `save_connection` | Write | P0 | Change how a seller is used: account-wide selection (DEFAULT, ALWAYS\_INCLUDE, ALWAYS\_EXCLUDE) or one advertiser activation. | | `save_creative` | Write | P0 | Create or update a creative from library assets and copy, attach it to campaigns, or archive it. | | `save_creative_collection` | Write | P1 | Create or change a non-executable advertiser creative collection: name, description (null clears), parentId (null clears; 16 levels max), one addMemberIds or removeMemberIds list of the advertiser's saved creative ids per call, or isArchived (children first; restore with the archive's expectedUpdatedAt). | | `save_creative_session` | Write | P0 | Creative sessions. | | `save_creatives_to_library` | Write | P1 | Keep brought creatives on the advertiser for now: promote them to its library shelf as evergreen (reusable, serve-ready) or reference (a generation input, not served). | | `save_dimension` | Write | P1 | Create or update a buyer-owned dimension and its values; labels remain fields on advertisers and campaigns. | | `save_measurement_source` | Write | P1 | Create or update a conversion event source for the advertiser (event types, allowed domains). | | `save_media_buy` | Write | P0 | Stage a draft media buy on the campaign from a proposal or a product selection, archive a draft, or pause / resume one live buy (isPaused) without touching the rest of its campaign. | | `sync_audiences` | Write | P1 | Sync first-party CRM audiences for an advertiser: add members (externalId plus email, phone, their SHA-256 hashes or uids), remove members by externalId, or delete an audience. | | `sync_catalogs` | Write | P1 | Connect or update catalog feeds for an advertiser: a feed URL (JSON, CSV/TSV, RSS/Atom or Google Merchant XML, fetched now and on its update frequency) or inline items with an id. | | `update_media_buy` | Write | P1 | Change one media buy: package budget, pacing, bid or targeting overlay, flight end, or name. | | `update_property_list` | Write | P1 | Rename a property list and/or replace its full identifier set (no incremental add/remove: send the whole set). | | `upload_creative_asset` | Read | P0 | Open the upload task so the person can add images, video or audio to the library. | ### `analyze_account` Analyze a connected ad-platform account (Meta, Google Ads, TikTok, Snap, Pinterest, Reddit, LinkedIn, Amazon Ads, Spotify) through the buyer's own linked account: account health, the last 30 days of delivery by campaign, and recommendations. Read-only. Without a linked account it answers auth-required with the account link path. | | | | ------------ | ------------------------------------------------------------------ | | Effect | Read | | Risk | None | | Priority | P1 | | Opens widget | `account-analysis` (`ui://semicola/account-analysis/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ----------- | -------- | -------- | -------------------------------------------------------------------------------------------------- | | `provider` | `enum` | No | One of `amazon`, `google`, `linkedin`, `meta`, `pinterest`, `reddit`, `snap`, `spotify`, `tiktok`. | | `accountId` | `string` | No | 1–100 chars. | ### `approve_optimization_suggestion` Approve an optimization suggestion and apply its budget change to the media buys (a live buy's change goes to its seller). | | | | ------------ | ---------------------------------- | | Effect | Write | | Risk | External (contacts a counterparty) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | ---------- | | `suggestionId` | `string` | Yes | ≥ 1 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `attach_creatives_to_campaign` Attach creatives saved by get\_creative\_intent (their creativeIds) to a campaign, then show the "here's what I added" card with format coverage. Creatives saved for another of the account's advertisers move to the campaign's advertiser. | | | | ------------ | ---------------------------------------------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | `creative-intent` (`ui://semicola/creative-intent/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ----------------- | ---------- | -------- | ---------------------------------------------- | | `campaignId` | `string` | Yes | ≥ 1 chars. | | `creativeIds` | `string[]` | Yes | Each item: 1–64 chars. ≥ 1 items, ≤ 100 items. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `attach_property_list_to_campaign` Push an advertiser include list to every active media buy in a campaign (for lists created after the buys went live). Exclude lists can't be attached. Call get\_campaign\_property\_lists afterwards to confirm. | | | | ------------ | ---------------------------------- | | Effect | Write | | Risk | External (contacts a counterparty) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | ---------- | | `campaignId` | `string` | Yes | ≥ 1 chars. | | `propertyListId` | `string` | Yes | ≥ 1 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `auto_select_products` Auto-select products for a campaign based on brief and budget. For a DRAFT campaign with autonomy.inventorySelection "automatic" and a discovery session: picks products from the discovery, allocates budget, and replaces all previously selected products. Iterate with refine (request asks; product include / omit / moreLikeThis). Contacts no seller. | | | | ------------ | ---------------------------------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | `campaigns` (`ui://semicola/campaigns/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | --------------------- | ---------- | -------- | ----------------------------------------------------------------------------------------- | | `refine` | `object[]` | No | Each item: Object form: `scope`, `ask`. Object form: `scope`, `id`, `action`. ≤ 50 items. | | `maxProducts` | `integer` | No | min 1, max 50. | | `minBudgetPerProduct` | `number` | No | > 0. | | `campaignId` | `string` | Yes | ≥ 1 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `cancel_update_proposal` Cancel a PENDING update proposal so a corrected update can proceed. It does not recall a request already sent to the seller. Confirm with the buyer first. | | | | ------------ | ----------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | ---------- | | `proposalId` | `string` | Yes | ≥ 1 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `check_property_list` Validate a candidate identifier set without creating a list: returns ok, modify (canonicalized), remove (duplicate or blocked) and assess (manual review; every mobile/CTV identifier) buckets, and a reportId when domains were checked. | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | --------------------- | ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `domains` | `string[]` | No | Each item: 1–1024 chars. ≤ 100000 items. | | `identifiers` | `object[]` | No | ≤ 100000 items. | | `identifiers[].type` | `enum` | Yes | One of `domain`, `subdomain`, `ios_bundle`, `android_package`, `apple_app_store_id`, `google_play_id`, `roku_store_id`, `fire_tv_asin`, `samsung_app_id`, `apple_tv_bundle`, `bundle_id`. | | `identifiers[].value` | `string` | Yes | 1–1024 chars. | ### `create_property_list` Create a named include or exclude property list for an advertiser from domains and/or typed identifiers (web, mobile, CTV). Include lists go to sellers that declare property-list targeting and are pushed to the advertiser's active media buys; exclude lists filter products out of discovery and stop a launch. Always report resolutionSummary. Up to about 500 entries; larger lists use the xlsx/csv upload (POST …/advertisers/\{advertiserId}/property-lists/upload). | | | | ------------ | ---------------------------------- | | Effect | Write | | Risk | External (contacts a counterparty) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ---------------------- | ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | Yes | 1–255 chars. | | `purpose` | `enum` | Yes | One of `include`, `exclude`. | | `domains` | `string[]` | No | Each item: 1–1024 chars. ≤ 100000 items. | | `identifiers` | `object[]` | No | ≤ 100000 items. | | `identifiers[].type` | `enum` | Yes | One of `domain`, `subdomain`, `ios_bundle`, `android_package`, `apple_app_store_id`, `google_play_id`, `roku_store_id`, `fire_tv_asin`, `samsung_app_id`, `apple_tv_bundle`, `bundle_id`. | | `identifiers[].value` | `string` | Yes | 1–1024 chars. | | `filters` | `object` | No | | | `filters.channels_any` | `string[]` | No | Each item: 1–64 chars. ≤ 50 items. | | `advertiserId` | `integer \| string` | No | | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `delete_property_list` Archive a property list: it stops shaping future discovery and media buys. | | | | ------------ | ----------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ----------------- | ------------------- | -------- | ---------- | | `advertiserId` | `integer \| string` | No | | | `listId` | `string` | Yes | ≥ 1 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `execute_catalog_activation_plan` Activate a catalog from its saved transform: creates one draft campaign per campaign group, queues creative generation and records seller feed sharing. Nothing is booked or spent. | | | | ------------ | ----------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ----------------- | ------------------- | -------- | ---------- | | `advertiserId` | `integer \| string` | No | | | `catalogId` | `string` | Yes | ≥ 1 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `generate_variants` Execute one saved creative session revision through its engine connection with the buyer's own provider key. Pass the session ID, expectedRevision, sessionGeneration and a new actionKey (reuse it only for an identical retry, which recovers the original request instead of submitting another). To refine, name the parent variantId and feedback. Never starts without an explicit call; a failed key never falls back to another key. | | | | ------------ | ----------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P0 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ------------------- | --------- | -------- | ------------- | | `sessionId` | `string` | Yes | ≥ 1 chars. | | `expectedRevision` | `integer` | Yes | min 1. | | `sessionGeneration` | `integer` | Yes | min 0. | | `actionKey` | `string` | Yes | 8–128 chars. | | `variantId` | `string` | No | ≥ 1 chars. | | `feedback` | `string` | No | 1–5000 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `get_campaign_property_lists` The property lists actually applied to a campaign through its media buys' packages. An empty list is the authoritative answer that no list is applied. | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ------------ | -------- | -------- | ---------- | | `campaignId` | `string` | Yes | ≥ 1 chars. | ### `get_creative_confirmation` Re-show a campaign's creative card (its creatives with status and format coverage). Read-only: it attaches nothing. | | | | ------------ | ---------------------------------------------------------------- | | Effect | Read | | Risk | None | | Priority | P1 | | Opens widget | `creative-intent` (`ui://semicola/creative-intent/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ------------ | -------- | -------- | ---------- | | `campaignId` | `string` | Yes | ≥ 1 chars. | ### `get_creative_intent` Open the "Which campaign are these for?" picker when the person brings finished creative (images, video, audio, tag sheets, HTML5 bundles) into chat. Call it FIRST instead of listing campaigns: pass the chat attachments as attachmentIds (they are saved as the advertiser's creatives up front, so they survive later turns) or creativeIds saved earlier. The picker commits the choice itself (a campaign, or saving to the advertiser); do not replay it. | | | | ------------ | ---------------------------------------------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | `creative-intent` (`ui://semicola/creative-intent/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ----------------- | ------------------- | -------- | ----------------------------------- | | `advertiserId` | `integer \| string` | No | | | `attachmentIds` | `string[]` | No | Each item: 1–64 chars. ≤ 25 items. | | `creativeIds` | `string[]` | No | Each item: 1–64 chars. ≤ 100 items. | | `campaignQuery` | `string` | No | ≤ 200 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `get_optimization_suggestion` Read one optimization suggestion: the proposed budget change, its rationale and the pacing recommendation. | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | -------------- | -------- | -------- | ---------- | | `suggestionId` | `string` | Yes | ≥ 1 chars. | ### `get_property_list` Get one property list with its resolved identifiers, domains and filters. Call it after update\_property\_list to confirm the stored count. | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | -------------- | ------------------- | -------- | ---------- | | `advertiserId` | `integer \| string` | No | | | `listId` | `string` | Yes | ≥ 1 chars. | ### `get_property_list_report` Get the bucket summary of an earlier property list check by reportId (kept 7 days). | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ---------- | -------- | -------- | ---------- | | `reportId` | `string` | Yes | ≥ 1 chars. | ### `get_update_proposal` Poll a media buy update proposal: PENDING until the seller approves (APPROVED) or declines (REJECTED, with rejectionReason). | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ------------ | -------- | -------- | ---------- | | `proposalId` | `string` | Yes | ≥ 1 chars. | ### `list_audiences` List an advertiser's synced audiences with status (PROCESSING, READY, ERROR, TOO\_SMALL), uploaded and matched counts. Use the audienceId values in a campaign's audienceConfig. | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | -------------- | ------------------- | -------- | --------------- | | `advertiserId` | `integer \| string` | No | | | `take` | `integer` | No | min 1, max 250. | | `skip` | `integer` | No | min 0. | ### `list_catalogs` List the advertiser's catalog feeds with health, item counts, versions, refresh runs, transform and activation jobs. | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | -------------- | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `advertiserId` | `integer \| string` | No | | | `type` | `enum` | No | One of `offering`, `product`, `inventory`, `store`, `promotion`, `hotel`, `flight`, `job`, `vehicle`, `real_estate`, `education`, `destination`. | ### `list_geo_metros` Compatibility shortcut for listing Nielsen DMA geo metro code-name pairs. Do not use this to match buyer-provided DMA text or spreadsheet labels; use resolve\_targeting\_dimension with system=nielsen\_dma for each label. Send only numeric string codes in campaign constraints.geo\_metros. | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | -------- | ------ | -------- | ---------------------------------------------------------- | | `system` | `enum` | No | Supported targeting dimension system One of `nielsen_dma`. | ### `list_optimization_suggestions` List optimization suggestions for your media buys, optionally by campaign, media buy or status (received = waiting for your approval). | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ------------ | --------- | -------- | --------------------------------------------------------------- | | `campaignId` | `string` | No | ≥ 1 chars. | | `mediaBuyId` | `string` | No | ≥ 1 chars. | | `status` | `enum` | No | One of `received`, `approved`, `rejected`, `applied`, `failed`. | | `limit` | `integer` | No | min 1, max 100. | | `offset` | `integer` | No | min 0. | ### `list_property_lists` List an advertiser's property lists (include and exclude) as summaries: listId, name, purpose, propertyCount. Call it after create\_property\_list to confirm the new list and its count. | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | -------------- | ------------------- | -------- | ---------------------------- | | `advertiserId` | `integer \| string` | No | | | `purpose` | `enum` | No | One of `include`, `exclude`. | | `take` | `integer` | No | min 1, max 250. | | `skip` | `integer` | No | min 0. | ### `list_targeting_dimension_values` List code-name pairs for a targeting dimension. For Nielsen DMA, pass system=nielsen\_dma. Send only returned codes in campaign constraints. | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | -------- | ------ | -------- | ---------------------------------------------------------- | | `system` | `enum` | Yes | Supported targeting dimension system One of `nielsen_dma`. | | `locale` | `enum` | No | One of `en-US`. | ### `list_targeting_dimensions` List supported targeting dimensions and the campaign constraint fields that accept them. Use this before resolving localized targeting text when the user did not name the exact system. | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | -------- | ------ | -------- | --------------- | | `locale` | `enum` | No | One of `en-US`. | ### `log_event` Log up to 10,000 conversion events to an event source (server-to-server). | | | | ------------ | ----------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | -------------------------- | ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `eventSourceId` | `string` | Yes | ≥ 1 chars. | | `advertiserId` | `integer \| string` | No | | | `events` | `object[]` | Yes | ≥ 1 items, ≤ 10000 items. | | `events[].eventType` | `enum` | Yes | One of `page_view`, `view_content`, `add_to_cart`, `initiate_checkout`, `purchase`, `lead`, `complete_registration`, `subscribe`, `app_install`, `custom`. | | `events[].eventTime` | `string` | No | ISO 8601 date-time with offset. | | `events[].eventId` | `string` | No | ≤ 200 chars. | | `events[].value` | `number` | No | min 0. | | `events[].currency` | `string` | No | Pattern `^[A-Z]{3}$`. | | `events[].actionSource` | `enum` | No | One of `website`, `app`, `in_store`, `phone_call`, `system_generated`, `other`. | | `events[].customEventName` | `string` | No | 1–100 chars. | | `testEventCode` | `string` | No | 1–100 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `open_advertisers_page` Open the advertisers list. Use it for any request to see or pick advertisers. | | | | ------------ | -------------------------------------------------------------------------- | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | `all-advertisers-home` (`ui://semicola/all-advertisers-home/mcp-app.html`) | **Input** No arguments. ### `open_campaign_receipt` Open Review & go live for a draft campaign: plan, staged buys, budget, creative coverage and blockers. | | | | ------------ | ---------------------------------------------------- | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | `campaigns` (`ui://semicola/campaigns/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ------------ | -------- | -------- | ---------- | | `campaignId` | `string` | Yes | ≥ 1 chars. | ### `open_campaigns_page` Open campaigns for the advertiser in scope, or one campaign workspace when campaignId is given. | | | | ------------ | ---------------------------------------------------- | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | `campaigns` (`ui://semicola/campaigns/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | -------------- | ------------------- | -------- | ----------------------------------------------------------------------------- | | `advertiserId` | `integer \| string` | No | | | `campaignId` | `string` | No | | | `status` | `enum[]` | No | Each one of `DRAFT`, `ACTIVE`, `PAUSED`, `COMPLETED`, `CANCELED`, `ARCHIVED`. | | `management` | `enum \| const` | No | Or `"all"`. | ### `open_connections_page` Open the sellers page. Use it for "where can I advertise" and any request to see or manage sellers. | | | | ------------ | -------------------------------------------------------- | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | `connections` (`ui://semicola/connections/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ------------------ | ------------------- | -------- | ----------------------------------------------------------- | | `advertiserId` | `integer \| string` | No | | | `sellerId` | `integer \| string` | No | | | `connectionAction` | `string` | No | | | `tab` | `enum` | No | One of `advertiser_sellers`, `media_partners`, `available`. | ### `open_creative_engines_page` Open the Creative Engines page (Connected and Available engines; enrolled Buyer Accounts). connectionAction "connect" with engineId focuses that engine's secure setup; the buyer starts setup on the page. Never put a provider key in tool arguments. | | | | ------------ | ------------------------------------------------------------------ | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | `creative-engines` (`ui://semicola/creative-engines/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ------------------ | -------- | -------- | ------------------------- | | `connectionAction` | `const` | No | Always `"connect"`. | | `engineId` | `string` | No | Pattern `^[1-9]\d{0,8}$`. | ### `preview_catalog_activation_plan` Preview what activating a catalog would create: campaign groups, creative assets and which connected sellers can take the catalog. | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | -------------- | ------------------- | -------- | ---------- | | `advertiserId` | `integer \| string` | No | | | `catalogId` | `string` | Yes | ≥ 1 chars. | | `persist` | `boolean` | No | | ### `refine_proposal` Ask one seller to revise a proposal (keep or drop products, shift budget, new instructions). Returns the seller's new version; the seller may decline parts. | | | | ------------ | ---------------------------------------------------- | | Effect | Write | | Risk | External (contacts a counterparty) | | Priority | P0 | | Opens widget | `proposals` (`ui://semicola/proposals/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ----------------- | ---------- | -------- | ------------- | | `proposalId` | `string` | Yes | ≥ 1 chars. | | `instructions` | `string` | Yes | 1–4000 chars. | | `budgetDelta` | `number` | No | | | `keepProductIds` | `string[]` | No | | | `dropProductIds` | `string[]` | No | | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `refresh_catalog` Fetch a URL catalog feed now and store a new version when items changed. | | | | ------------ | ---------------------------------- | | Effect | Write | | Risk | External (contacts a counterparty) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ----------------- | ------------------- | -------- | ---------- | | `advertiserId` | `integer \| string` | No | | | `catalogId` | `string` | Yes | ≥ 1 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `reject_optimization_suggestion` Reject an optimization suggestion, with an optional reason. Nothing changes. | | | | ------------ | ----------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | ------------ | | `suggestionId` | `string` | Yes | ≥ 1 chars. | | `reason` | `string` | No | ≤ 500 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `request_proposals` Send the campaign brief to every eligible seller and collect proposals. Returns right away with an execution id; results stream into the proposals widget. One running execution per buyer. | | | | ------------ | ---------------------------------------------------- | | Effect | Write | | Risk | External (contacts a counterparty) | | Priority | P0 | | Opens widget | `proposals` (`ui://semicola/proposals/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | -------------------------- | ------------------- | -------- | ------------------------------------------- | | `campaignId` | `string` | Yes | ≥ 1 chars. | | `expectedCampaignRevision` | `integer` | Yes | min 0. | | `expectedSellerId` | `integer \| string` | No | | | `evaluation` | `object` | No | | | `evaluation.instructions` | `string` | Yes | ≤ 4000 chars. | | `idempotencyKey` | `string` | Yes | 16–255 chars. Pattern `^[A-Za-z0-9_.:-]+$`. | | `resultCursor` | `string` | No | | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `resolve_targeting_dimension` Resolve localized targeting text, DMA names, aliases, and messy buyer spreadsheet labels to code candidates within a specific dimension. For "LA DMA", pass system=nielsen\_dma and q="LA DMA"; use the top candidate only when not ambiguous. | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | -------- | -------- | -------- | ---------------------------------------------------------- | | `system` | `enum` | Yes | Supported targeting dimension system One of `nielsen_dma`. | | `q` | `string` | Yes | 1–200 chars. | | `locale` | `enum` | No | One of `en-US`. | ### `save_advertiser` Create, update, archive an advertiser, or preview a brand with \{resolveBrand: domain}. Confirm the primary currency before creating; it locks after the first campaign. Sandbox is fixed at creation. Missing fields come back as needs\_input. | | | | ------------ | -------------------------------------------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P0 | | Opens widget | `add-advertiser` (`ui://semicola/add-advertiser/mcp-app.html`) | **Input** The input is one of 4 forms. Send exactly one; fields from different forms do not mix. **Form 1: with `name`, `idempotencyKey`** | Field | Type | Required | Notes | | --------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | Yes | 1–200 chars. | | `brand` | `string` | No | ≥ 3 chars. | | `primaryCurrency` | `string` | No | Pattern `^[A-Z]{3}$`. | | `sandbox` | `boolean` | No | | | `description` | `string` | No | ≤ 2000 chars. | | `brandCountries` | `string[]` | No | Each item: Pattern `^[A-Z]{2}$`. | | `preferredTimezone` | `string` | No | | | `channels` | `enum[]` | No | Each one of `display`, `olv`, `social`, `search`, `ctv`, `linear_tv`, `radio`, `streaming_audio`, `podcast`, `dooh`, `ooh`, `print`, `cinema`, `email`, `gaming`, `retail_media`, `influencer`, `affiliate`, `product_placement`, `sponsored_intelligence`. | | `labels` | `object` | No | | | `frequencyCaps` | `object[]` | No | | | `frequencyCaps[].max_impressions` | `integer` | Yes | > 0. | | `frequencyCaps[].window` | `object` | Yes | | | `frequencyCaps[].window.interval` | `integer` | Yes | > 0. | | `frequencyCaps[].window.unit` | `enum` | Yes | One of `minutes`, `hours`, `days`, `campaign`. | | `idempotencyKey` | `string` | Yes | 16–255 chars. Pattern `^[A-Za-z0-9_.:-]+$`. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | **Form 2: with `advertiserId`** | Field | Type | Required | Notes | | --------------------------------- | ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `advertiserId` | `integer \| string` | Yes | | | `name` | `string` | No | 1–200 chars. | | `description` | `string` | No | ≤ 2000 chars. | | `primaryCurrency` | `string` | No | Pattern `^[A-Z]{3}$`. | | `brandCountries` | `string[]` | No | Each item: Pattern `^[A-Z]{2}$`. | | `preferredTimezone` | `string` | No | | | `channels` | `enum[]` | No | Each one of `display`, `olv`, `social`, `search`, `ctv`, `linear_tv`, `radio`, `streaming_audio`, `podcast`, `dooh`, `ooh`, `print`, `cinema`, `email`, `gaming`, `retail_media`, `influencer`, `affiliate`, `product_placement`, `sponsored_intelligence`. | | `autonomy` | `object` | No | | | `autonomy.inventorySelection` | `enum` | Yes | One of `manual`, `propose`, `automatic`. | | `autonomy.rebriefing` | `enum` | Yes | One of `manual`, `propose`, `automatic`. | | `labels` | `object` | No | | | `frequencyCaps` | `object[]` | No | | | `frequencyCaps[].max_impressions` | `integer` | Yes | > 0. | | `frequencyCaps[].window` | `object` | Yes | | | `frequencyCaps[].window.interval` | `integer` | Yes | > 0. | | `frequencyCaps[].window.unit` | `enum` | Yes | One of `minutes`, `hours`, `days`, `campaign`. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | **Form 3: with `advertiserIds`, `isArchived`** | Field | Type | Required | Notes | | ----------------- | ----------------------- | -------- | ---------------------- | | `advertiserIds` | `(integer \| string)[]` | Yes | ≥ 1 items, ≤ 50 items. | | `isArchived` | `boolean` | Yes | | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | **Form 4: with `resolveBrand`** | Field | Type | Required | Notes | | -------------- | -------- | -------- | ---------- | | `resolveBrand` | `string` | Yes | ≥ 3 chars. | ### `save_buyer_agent` Create an external buyer agent (omit id; displayName, kind "external"), or change one agent by id with exactly one of: displayName, access (complete advertiser list plus expectedAccessRevision), or lifecycle (suspend | resume | retire with expectedLifecycleState; suspend and retire need the exact name as confirmationText). Returns \{kind: "buyer\_agent", object} like get. Direct account admins only; hosted creation is not yet available. | | | | ------------ | ----------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ----------------------------------- | ------------------- | -------- | ---------------------------------------- | | `id` | `string` | No | 1–100 chars. | | `displayName` | `string` | No | 1–120 chars. | | `kind` | `enum` | No | One of `external`, `hosted`. | | `access` | `object` | No | | | `access.expectedAccessRevision` | `integer` | Yes | min 0. | | `access.advertisers` | `object[]` | Yes | ≤ 500 items. | | `access.advertisers[].advertiserId` | `integer \| string` | Yes | | | `access.advertisers[].role` | `enum` | Yes | One of `READ`, `READ_WRITE`. | | `lifecycle` | `object` | No | | | `lifecycle.kind` | `enum` | Yes | One of `suspend`, `resume`, `retire`. | | `lifecycle.expectedLifecycleState` | `enum` | Yes | One of `active`, `suspended`, `retired`. | | `lifecycle.confirmationText` | `string` | No | 1–255 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `save_campaign` Create a DRAFT campaign or change one. Confirm currency and budget before creating. A brief or budget is not authority to spend: going live is two calls (desiredPhase "active", then confirmLaunch with expectedRevision after the person approves). | | | | ------------ | ---------------------------------------------------- | | Effect | Write | | Risk | Spend (can commit budget) | | Priority | P0 | | Opens widget | `campaigns` (`ui://semicola/campaigns/mcp-app.html`) | **Input** The input is one of 2 forms. Send exactly one; fields from different forms do not mix. **Form 1: with `name`, `idempotencyKey`** | Field | Type | Required | Notes | | ------------------------------------ | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `advertiserId` | `integer \| string` | No | | | `name` | `string` | Yes | 1–200 chars. | | `brief` | `string` | No | ≤ 20000 chars. | | `flight` | `object` | No | | | `flight.startAt` | `string` | Yes | ISO 8601 date-time with offset. | | `flight.endAt` | `string` | Yes | ISO 8601 date-time with offset. | | `budget` | `object` | No | | | `budget.total` | `number \| string` | Yes | | | `budget.currency` | `string` | No | Pattern `^[A-Z]{3}$`. | | `budget.pacing` | `enum` | No | One of `EVEN`, `ASAP`, `FRONTLOADED`. | | `budget.dailyCap` | `number \| string` | No | | | `targeting` | `object` | No | Object form: `geo`, `language`, `device`, `dayparts`, `demographics`. Object form: `countries`, `channels`, `ageRange`, `audience`, `geoMetros`. | | `optimizationGoals` | `object[]` | No | Each item: Object form: `kind`, `eventSources`, `target`, `attributionWindow`, `priority`. Object form: `kind`, `metric`, `viewDurationSeconds`, `target`, `attributionWindow`, `priority`. ≥ 1 items, ≤ 10 items. | | `creativeIds` | `string[]` | No | | | `autonomy` | `object` | No | | | `autonomy.inventorySelection` | `enum` | No | One of `manual`, `propose`, `automatic`. | | `autonomy.rebriefing` | `enum` | No | One of `manual`, `propose`, `automatic`. | | `audienceConfig` | `object` | No | | | `audienceConfig.targetAudienceIds` | `string[]` | No | Each item: 1–255 chars. ≤ 100 items. | | `audienceConfig.suppressAudienceIds` | `string[]` | No | Each item: 1–255 chars. ≤ 100 items. | | `audienceConfig.deleteMissing` | `boolean` | No | | | `pacingPeriods` | `object` | No | | | `pacingPeriods.mode` | `enum` | Yes | One of `weight`, `budget`. | | `pacingPeriods.periods` | `object[]` | Yes | ≥ 1 items, ≤ 52 items. | | `pacingPeriods.periods[].label` | `string` | Yes | 1–100 chars. | | `pacingPeriods.periods[].start` | `string` | Yes | Pattern `^\d{4}-\d{2}-\d{2}$`. | | `pacingPeriods.periods[].end` | `string` | Yes | Pattern `^\d{4}-\d{2}-\d{2}$`. | | `pacingPeriods.periods[].weight` | `number` | No | | | `pacingPeriods.periods[].budget` | `number` | No | | | `labels` | `object` | No | | | `frequencyCaps` | `object[]` | No | | | `frequencyCaps[].max_impressions` | `integer` | Yes | > 0. | | `frequencyCaps[].window` | `object` | Yes | | | `frequencyCaps[].window.interval` | `integer` | Yes | > 0. | | `frequencyCaps[].window.unit` | `enum` | Yes | One of `minutes`, `hours`, `days`, `campaign`. | | `channelGroups` | `object[]` | No | Each item: Object form: `channelGroupId`, `presetId`, `name`. Object form: `channelGroupId`, `name`, `inventory`. Object form: `channelGroupId`, `name`, `source`, `inventory`. ≤ 20 items. | | `idempotencyKey` | `string` | Yes | 16–255 chars. Pattern `^[A-Za-z0-9_.:-]+$`. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | **Form 2: with `campaignId`, `expectedRevision`** | Field | Type | Required | Notes | | ------------------------------------ | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `campaignId` | `string` | Yes | ≥ 1 chars. | | `expectedRevision` | `integer` | Yes | min 0. | | `desiredPhase` | `enum` | No | One of `active`, `canceled`. | | `confirmLaunch` | `boolean` | No | | | `isPaused` | `boolean` | No | | | `isArchived` | `boolean` | No | | | `name` | `string` | No | 1–200 chars. | | `brief` | `string` | No | ≤ 20000 chars. | | `flight` | `object` | No | | | `flight.startAt` | `string` | Yes | ISO 8601 date-time with offset. | | `flight.endAt` | `string` | Yes | ISO 8601 date-time with offset. | | `budget` | `object` | No | | | `budget.total` | `number \| string` | Yes | | | `budget.currency` | `string` | No | Pattern `^[A-Z]{3}$`. | | `budget.pacing` | `enum` | No | One of `EVEN`, `ASAP`, `FRONTLOADED`. | | `budget.dailyCap` | `number \| string` | No | | | `targeting` | `object` | No | Object form: `geo`, `language`, `device`, `dayparts`, `demographics`. Object form: `countries`, `channels`, `ageRange`, `audience`, `geoMetros`. | | `audienceConfig` | `object` | No | | | `audienceConfig.targetAudienceIds` | `string[]` | No | Each item: 1–255 chars. ≤ 100 items. | | `audienceConfig.suppressAudienceIds` | `string[]` | No | Each item: 1–255 chars. ≤ 100 items. | | `audienceConfig.deleteMissing` | `boolean` | No | | | `pacingPeriods` | `object \| null` | No | Object form: `mode`, `periods`. | | `autonomy` | `object` | No | | | `autonomy.inventorySelection` | `enum` | No | One of `manual`, `propose`, `automatic`. | | `autonomy.rebriefing` | `enum` | No | One of `manual`, `propose`, `automatic`. | | `labels` | `object` | No | | | `frequencyCaps` | `object[]` | No | | | `frequencyCaps[].max_impressions` | `integer` | Yes | > 0. | | `frequencyCaps[].window` | `object` | Yes | | | `frequencyCaps[].window.interval` | `integer` | Yes | > 0. | | `frequencyCaps[].window.unit` | `enum` | Yes | One of `minutes`, `hours`, `days`, `campaign`. | | `channelGroups` | `object[]` | No | Each item: Object form: `channelGroupId`, `presetId`, `name`. Object form: `channelGroupId`, `name`, `inventory`. Object form: `channelGroupId`, `name`, `source`, `inventory`. ≤ 20 items. | | `optimizationGoals` | `object[] \| null` | No | | | `mediaBuys` | `object[]` | No | ≥ 1 items, ≤ 50 items. | | `mediaBuys[].action` | `const` | No | Always `"update"`. | | `mediaBuys[].mediaBuyId` | `string` | Yes | ≥ 1 chars. | | `mediaBuys[].packages` | `object[]` | No | ≤ 100 items. | | `mediaBuys[].packages[].packageId` | `string` | Yes | ≥ 1 chars. | | `mediaBuys[].packages[].budget` | `number \| string` | No | | | `mediaBuys[].packages[].pacing` | `enum` | No | One of `even`, `asap`, `front_loaded`. | | `mediaBuys[].packages[].bidPrice` | `number \| string` | No | | | `mediaBuys[].updated_reason` | `string` | No | ≤ 1000 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `save_catalog_transform` Save the transform recipe for a catalog: the item fields to group campaigns by, a creative prompt (\{field} placeholders take each group's values) and a budget per group. | | | | ------------ | ----------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ----------------- | ------------------- | -------- | --------------------------------- | | `advertiserId` | `integer \| string` | No | | | `catalogId` | `string` | Yes | ≥ 1 chars. | | `groupBy` | `string[]` | Yes | Each item: 1–64 chars. ≤ 4 items. | | `creativePrompt` | `string` | No | ≤ 2000 chars. | | `budgetPerGroup` | `number` | No | min 0. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `save_connection` Change how a seller is used: account-wide selection (DEFAULT, ALWAYS\_INCLUDE, ALWAYS\_EXCLUDE) or one advertiser activation. For a creative engine: target \{kind: "creative\_engine", id} with authorization \{} returns a secure handoff to enter the key; connectionId with authorization, refreshAccounts, selectedAccountId, advertiserMapping or state "removed" changes a creative grant. One intent per call. | | | | ------------ | -------------------------------------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P0 | | Opens widget | `connections` (`ui://semicola/connections/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ----------------------------------- | --------------------------- | -------- | ---------------------------------------------------------------------------------- | | `target` | `object` | No | | | `target.kind` | `enum` | Yes | One of `seller`, `creative_engine`. | | `target.id` | `integer \| string` | Yes | | | `connectionId` | `string` | No | 1–64 chars. | | `authorization` | `object` | No | | | `selectedAccountId` | `string` | No | 1–64 chars. | | `advertiserMapping` | `object` | No | Object form: `state`, `advertiserId`, `accountId`. Object form: `state`, `linkId`. | | `state` | `const` | No | Always `"removed"`. | | `selection` | `enum` | No | One of `DEFAULT`, `ALWAYS_INCLUDE`, `ALWAYS_EXCLUDE`. | | `advertiserActivation` | `object` | No | | | `advertiserActivation.advertiserId` | `integer \| string` | Yes | | | `advertiserActivation.decision` | `enum` | Yes | One of `DEFAULT`, `ENABLED`, `DISABLED`. | | `connect` | `const` | No | Always `true`. | | `accountMapping` | `object` | No | | | `accountMapping.accountId` | `integer \| string` | Yes | | | `accountMapping.advertiserId` | `integer \| string \| null` | Yes | | | `refreshAccounts` | `const` | No | Always `true`. | | `disconnect` | `const` | No | Always `true`. | | `featurePolicy` | `object` | No | | | `featurePolicy.buyEnabled` | `boolean` | No | | | `featurePolicy.eventsEnabled` | `boolean` | No | | | `featurePolicy.feedsEnabled` | `boolean` | No | | | `enhancedReporting` | `object` | No | | | `enhancedReporting.accountId` | `integer \| string` | Yes | | | `enhancedReporting.enabled` | `boolean` | Yes | | | `billing` | `object` | No | Object form: `requestedParty`. Object form: `directBillingAccepted`. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `save_creative` Create or update a creative from library assets and copy, attach it to campaigns, or archive it. Attaching reports format fit per campaign. | | | | ------------ | ------------------------------------------------------------------------ | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P0 | | Opens widget | `creative-library-v3` (`ui://semicola/creative-library-v3/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | --------------------------------- | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `advertiserId` | `integer \| string` | No | | | `campaignId` | `string` | No | | | `creativeId` | `string` | No | | | `expectedRevision` | `integer` | No | min 0. | | `name` | `string` | No | 1–200 chars. | | `sourceAssets` | `object[]` | No | | | `sourceAssets[].assetId` | `string` | Yes | ≥ 1 chars. | | `sourceAssets[].slot` | `string` | Yes | ≥ 1 chars. | | `creativeFormatId` | `string` | No | | | `formatKind` | `enum` | No | One of `image`, `html5`, `display_tag`, `image_carousel`, `video_hosted`, `video_vast`, `audio_hosted`, `audio_daast`, `sponsored_placement`, `native_in_feed`, `responsive_creative`, `agent_placement`, `custom`. | | `copy` | `object` | No | | | `clickUrl` | `string` | No | Format `uri`. | | `mode` | `enum` | No | One of `draft`, `complete`. | | `campaignIds` | `string[]` | No | | | `isArchived` | `boolean` | No | | | `promoted` | `boolean` | No | | | `role` | `enum` | No | One of `evergreen`, `reference`. | | `duplicate` | `const` | No | Always `true`. | | `message` | `string` | No | ≤ 2000 chars. | | `urlAsset` | `object` | No | | | `urlAsset.url` | `string` | Yes | ≤ 2048 chars. Format `uri`. | | `urlAsset.urlType` | `enum` | Yes | One of `clickthrough`, `tracker_pixel`, `tracker_script`, `vast`. | | `urlAsset.vastVersion` | `enum` | No | One of `2.0`, `3.0`, `4.0`, `4.1`, `4.2`, `4.3`. | | `webhookAsset` | `object` | No | | | `webhookAsset.url` | `string` | Yes | ≤ 2048 chars. Format `uri`. | | `webhookAsset.method` | `enum` | No | One of `GET`, `POST`. Default `"POST"`. | | `webhookAsset.timeoutMs` | `integer` | No | min 10, max 5000. Default `500`. | | `webhookAsset.responseType` | `enum` | No | One of `html`, `json`, `xml`, `javascript`. Default `"json"`. | | `webhookAsset.security` | `object` | Yes | Object form: `method`. Object form: `method`, `hmacHeader`. Object form: `method`, `apiKeyHeader`. | | `carouselCards` | `object[]` | No | ≤ 10 items. | | `carouselCards[].assetId` | `string` | Yes | ≥ 5 chars. | | `carouselCards[].headline` | `string` | No | ≤ 200 chars. | | `carouselCards[].description` | `string` | No | ≤ 1000 chars. | | `carouselCards[].cta` | `string` | No | ≤ 60 chars. | | `carouselCards[].landingPageUrl` | `string` | No | ≤ 2048 chars. Format `uri`. | | `frequencyCaps` | `object[]` | No | | | `frequencyCaps[].max_impressions` | `integer` | Yes | > 0. | | `frequencyCaps[].window` | `object` | Yes | | | `frequencyCaps[].window.interval` | `integer` | Yes | > 0. | | `frequencyCaps[].window.unit` | `enum` | Yes | One of `minutes`, `hours`, `days`, `campaign`. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `save_creative_collection` Create or change a non-executable advertiser creative collection: name, description (null clears), parentId (null clears; 16 levels max), one addMemberIds or removeMemberIds list of the advertiser's saved creative ids per call, or isArchived (children first; restore with the archive's expectedUpdatedAt). Changes send the current updatedAt as expectedUpdatedAt; a stale one is a CONFLICT. | | | | ------------ | ----------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ------------------- | ------------------- | -------- | --------------------------------------------- | | `advertiserId` | `integer \| string` | No | | | `collectionId` | `string` | No | ≥ 1 chars. | | `name` | `string` | No | 1–255 chars. | | `description` | `string \| null` | No | | | `parentId` | `string \| null` | No | | | `addMemberIds` | `string[]` | No | Each item: ≥ 1 chars. ≥ 1 items, ≤ 500 items. | | `removeMemberIds` | `string[]` | No | Each item: ≥ 1 chars. ≥ 1 items, ≤ 500 items. | | `isArchived` | `boolean` | No | | | `expectedUpdatedAt` | `string` | No | ISO 8601 date-time with offset. | | `role` | `any` | No | | | `syncPolicy` | `any` | No | | | `attachToCampaign` | `any` | No | | | `metadata` | `any` | No | | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `save_creative_session` Creative sessions. Composer drafts: save\_draft stores slot values (optimistic on expectedRevision). Generative briefs: save\_draft with campaignId, engine \{engineId, connectionId}, brief, plan \{format\_kind, params} and locked referenceAssetIds (saving never generates; call generate\_variants). select\_output then approve\_output bind one exact output (outputId = build\_variant\_id) to the revision; finalize\_approved\_output saves the approved output (or the composer draft) as a library creative. | | | | ------------ | ------------------------------------------------------------------------------ | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P0 | | Opens widget | `creative-composer-task` (`ui://semicola/creative-composer-task/mcp-app.html`) | **Input** The input is one of 4 forms. Send exactly one; fields from different forms do not mix. **Form 1: `operation: "save_draft"`** | Field | Type | Required | Notes | | ------------------------------- | ------------------- | -------- | ---------------------------------------------------------------------- | | `operation` | `const` | Yes | Always `"save_draft"`. | | `sessionId` | `string` | No | | | `advertiserId` | `integer \| string` | No | | | `campaignId` | `string` | No | | | `expectedRevision` | `integer` | No | min 0. | | `format` | `enum` | No | One of `vertical_story`, `display_300x250`, `audio_30`, `video_reels`. | | `slots` | `object[]` | No | ≥ 1 items, ≤ 12 items. | | `slots[].slotId` | `string` | Yes | ≥ 1 chars. | | `slots[].value` | `string` | No | ≤ 5000 chars. | | `slots[].assetId` | `string` | No | | | `slots[].crop` | `boolean` | No | | | `title` | `string` | No | ≤ 200 chars. | | `clickUrl` | `string \| null` | No | | | `engine` | `object` | No | | | `engine.engineId` | `string` | Yes | Pattern `^[1-9]\d{0,18}$`. | | `engine.connectionId` | `string` | Yes | ≥ 1 chars. | | `brief` | `object` | No | | | `brief.prompt` | `string` | Yes | 1–5000 chars. | | `brief.objective` | `string` | No | ≤ 500 chars. | | `brief.persona` | `string` | No | ≤ 500 chars. | | `plan` | `object` | No | | | `plan.format_kind` | `enum` | Yes | One of `image`, `audio_hosted`, `video_hosted`. | | `plan.params` | `object` | No | Default `{}`. | | `plan.params.width` | `integer` | No | > 0, max 4096. | | `plan.params.height` | `integer` | No | > 0, max 4096. | | `plan.params.duration_ms_exact` | `integer` | No | > 0, max 600000. | | `referenceAssetIds` | `string[]` | No | Each item: ≥ 1 chars. ≤ 10 items. | | `variantCount` | `integer` | No | min 1, max 4. | | `voiceId` | `string` | No | Pattern `^[A-Za-z0-9]{8,40}$`. | | `idempotencyKey` | `string` | Yes | 16–255 chars. Pattern `^[A-Za-z0-9_.:-]+$`. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | **Form 2: `operation: "finalize_approved_output"`** | Field | Type | Required | Notes | | ------------------ | --------- | -------- | ------------------------------------------- | | `operation` | `const` | Yes | Always `"finalize_approved_output"`. | | `sessionId` | `string` | Yes | ≥ 1 chars. | | `expectedRevision` | `integer` | Yes | min 0. | | `idempotencyKey` | `string` | Yes | 16–255 chars. Pattern `^[A-Za-z0-9_.:-]+$`. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | **Form 3: `operation: "select_output"`** | Field | Type | Required | Notes | | ------------------ | --------- | -------- | ------------------------- | | `operation` | `const` | Yes | Always `"select_output"`. | | `sessionId` | `string` | Yes | ≥ 1 chars. | | `outputId` | `string` | Yes | ≥ 1 chars. | | `expectedRevision` | `integer` | No | min 0. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | **Form 4: `operation: "approve_output"`** | Field | Type | Required | Notes | | ------------------ | --------- | -------- | -------------------------- | | `operation` | `const` | Yes | Always `"approve_output"`. | | `sessionId` | `string` | Yes | ≥ 1 chars. | | `outputId` | `string` | Yes | ≥ 1 chars. | | `expectedRevision` | `integer` | No | min 0. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `save_creatives_to_library` Keep brought creatives on the advertiser for now: promote them to its library shelf as evergreen (reusable, serve-ready) or reference (a generation input, not served). No campaign needed. | | | | ------------ | ---------------------------------------------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | `creative-intent` (`ui://semicola/creative-intent/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ----------------- | ------------------- | -------- | ---------------------------------------------- | | `advertiserId` | `integer \| string` | Yes | | | `creativeIds` | `string[]` | Yes | Each item: 1–64 chars. ≥ 1 items, ≤ 100 items. | | `role` | `enum` | Yes | One of `evergreen`, `reference`. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `save_dimension` Create or update a buyer-owned dimension and its values; labels remain fields on advertisers and campaigns. Create with a unique key, a name, valuesMode (open | governed) and appliesTo; update by id to add or rename values, merge a value into another (mergeInto), or retire a value or the whole dimension. The built-in tags dimension is always open. | | | | ------------ | ----------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | -------------------- | ---------- | -------- | ------------------------------------------------ | | `id` | `string` | No | ≥ 1 chars. | | `key` | `string` | No | Pattern `^[a-z][a-z0-9_]{0,63}$`. | | `name` | `string` | No | 1–100 chars. | | `valuesMode` | `enum` | No | One of `open`, `governed`. | | `appliesTo` | `enum[]` | No | Each one of `advertiser`, `campaign`. ≥ 1 items. | | `values` | `object[]` | No | ≤ 200 items. | | `values[].value` | `string` | Yes | 1–100 chars. | | `values[].name` | `string` | No | 1–100 chars. | | `values[].retired` | `boolean` | No | | | `values[].mergeInto` | `string` | No | 1–100 chars. | | `retired` | `boolean` | No | | | `idempotencyKey` | `string` | Yes | 16–255 chars. Pattern `^[A-Za-z0-9_.:-]+$`. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `save_measurement_source` Create or update a conversion event source for the advertiser (event types, allowed domains). Performance goals and reporting read its events. | | | | ------------ | ----------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | --------------------- | ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sourceType` | `const` | Yes | Always `"event"`. | | `eventSourceId` | `string` | Yes | 1–100 chars. | | `advertiserId` | `integer \| string` | No | | | `name` | `string` | No | 1–200 chars. | | `eventTypes` | `enum[]` | Yes | Each one of `page_view`, `view_content`, `add_to_cart`, `initiate_checkout`, `purchase`, `lead`, `complete_registration`, `subscribe`, `app_install`, `custom`. ≥ 1 items. | | `integrationPlatform` | `string` | No | ≤ 100 chars. | | `allowedDomains` | `string[]` | No | Each item: ≥ 3 chars. ≤ 50 items. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `save_media_buy` Stage a draft media buy on the campaign from a proposal or a product selection, archive a draft, or pause / resume one live buy (isPaused) without touching the rest of its campaign. Staging contacts no seller; pausing tells the seller. | | | | ------------ | ---------------------------------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P0 | | Opens widget | `campaigns` (`ui://semicola/campaigns/mcp-app.html`) | **Input** The input is one of 4 forms. Send exactly one; fields from different forms do not mix. **Form 1: with `fromProposalId`, `idempotencyKey`** | Field | Type | Required | Notes | | ----------------- | ------------------ | -------- | ------------------------------------------- | | `fromProposalId` | `string` | Yes | ≥ 1 chars. | | `totalBudget` | `number \| string` | No | | | `channelGroupId` | `string` | No | ≥ 1 chars. | | `idempotencyKey` | `string` | Yes | 16–255 chars. Pattern `^[A-Za-z0-9_.:-]+$`. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | **Form 2: with `campaignId`, `sellerId`, `products`, `idempotencyKey`** | Field | Type | Required | Notes | | ---------------------------- | ------------------- | -------- | ------------------------------------------- | | `campaignId` | `string` | Yes | ≥ 1 chars. | | `sellerId` | `integer \| string` | Yes | | | `products` | `object[]` | Yes | ≥ 1 items. | | `products[].productId` | `string` | Yes | ≥ 1 chars. | | `products[].pricingOptionId` | `string` | Yes | ≥ 1 chars. | | `products[].budget` | `number \| string` | Yes | | | `products[].bidPrice` | `number \| string` | No | | | `channelGroupId` | `string` | No | ≥ 1 chars. | | `flight` | `object` | No | | | `flight.startAt` | `string` | Yes | ISO 8601 date-time with offset. | | `flight.endAt` | `string` | Yes | ISO 8601 date-time with offset. | | `budget` | `number \| string` | No | | | `idempotencyKey` | `string` | Yes | 16–255 chars. Pattern `^[A-Za-z0-9_.:-]+$`. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | **Form 3: `isArchived: true`** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | -------------- | | `mediaBuyId` | `string` | Yes | ≥ 1 chars. | | `isArchived` | `const` | Yes | Always `true`. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | **Form 4: with `mediaBuyId`, `isPaused`** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | ---------- | | `mediaBuyId` | `string` | Yes | ≥ 1 chars. | | `isPaused` | `boolean` | Yes | | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `sync_audiences` Sync first-party CRM audiences for an advertiser: add members (externalId plus email, phone, their SHA-256 hashes or uids), remove members by externalId, or delete an audience. Raw email and phone are hashed before anything is stored. Asynchronous: returns a taskId. | | | | ------------ | ----------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | --------------------------------------- | ------------------- | -------- | ------------------------------------------------------------------------ | | `audiences` | `object[]` | Yes | ≥ 1 items. | | `audiences[].audienceId` | `string` | Yes | 1–255 chars. | | `audiences[].name` | `string` | No | ≤ 255 chars. | | `audiences[].consentBasis` | `enum` | No | One of `consent`, `legitimate_interest`, `contract`, `legal_obligation`. | | `audiences[].add` | `object[]` | No | ≤ 100000 items. | | `audiences[].add[].externalId` | `string` | Yes | 1–255 chars. | | `audiences[].add[].email` | `string` | No | ≤ 320 chars. | | `audiences[].add[].phone` | `string` | No | ≤ 32 chars. | | `audiences[].add[].hashedEmail` | `string` | No | Pattern `^[0-9a-fA-F]{64}$`. | | `audiences[].add[].hashedPhone` | `string` | No | Pattern `^[0-9a-fA-F]{64}$`. | | `audiences[].add[].uids` | `object[]` | No | ≤ 20 items. | | `audiences[].remove` | `object[]` | No | ≤ 100000 items. | | `audiences[].remove[].externalId` | `string` | Yes | 1–255 chars. | | `audiences[].delete` | `boolean` | No | | | `deleteMissing` | `boolean` | No | | | `pushNotificationConfig` | `object` | No | | | `pushNotificationConfig.url` | `string` | Yes | Format `uri`. | | `pushNotificationConfig.operation_id` | `string` | No | | | `pushNotificationConfig.token` | `string` | No | | | `pushNotificationConfig.authentication` | `object` | No | | | `advertiserId` | `integer \| string` | No | | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `sync_catalogs` Connect or update catalog feeds for an advertiser: a feed URL (JSON, CSV/TSV, RSS/Atom or Google Merchant XML, fetched now and on its update frequency) or inline items with an id. Each sync stores a version with its changes. | | | | ------------ | ---------------------------------- | | Effect | Write | | Risk | External (contacts a counterparty) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ---------------------------- | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `advertiserId` | `integer \| string` | No | | | `catalogs` | `object[]` | Yes | ≥ 1 items, ≤ 10 items. | | `catalogs[].catalogId` | `string` | No | | | `catalogs[].platformId` | `string` | No | Pattern `^[a-z0-9][a-z0-9_-]{0,63}$`. | | `catalogs[].name` | `string` | No | 1–200 chars. | | `catalogs[].type` | `enum` | No | One of `offering`, `product`, `inventory`, `store`, `promotion`, `hotel`, `flight`, `job`, `vehicle`, `real_estate`, `education`, `destination`. | | `catalogs[].url` | `string` | No | Format `uri`. | | `catalogs[].feedFormat` | `enum` | No | One of `google_merchant_center`, `facebook_catalog`, `shopify`, `linkedin_jobs`, `custom`. | | `catalogs[].updateFrequency` | `enum` | No | One of `realtime`, `hourly`, `daily`, `weekly`. | | `catalogs[].items` | `object[]` | No | ≤ 5000 items. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `update_media_buy` Change one media buy: package budget, pacing, bid or targeting overlay, flight end, or name. A live buy goes to its seller; when the seller must approve, the result carries an update proposal that stays PENDING until it does. Targeting keys you name replace the package's current ones; keys you omit stay. A targeting field the seller doesn't declare support for is refused before anything is sent. | | | | ------------ | ---------------------------------- | | Effect | Write | | Risk | External (contacts a counterparty) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | --------------------------------------------------- | ---------------- | -------- | -------------------------------------------------------------------- | | `mediaBuyId` | `string` | Yes | ≥ 1 chars. | | `name` | `string` | No | 1–200 chars. | | `packages` | `object[]` | No | | | `packages[].packageId` | `string` | Yes | ≥ 1 chars. | | `packages[].budget` | `string` | No | Pattern `^-?\d+(\.\d{1,6})?$`. | | `packages[].pacing` | `enum` | No | One of `even`, `asap`, `front_loaded`. | | `packages[].bidPrice` | `string` | No | Pattern `^-?\d+(\.\d{1,6})?$`. | | `packages[].targetingOverlay` | `object` | No | | | `packages[].targetingOverlay.geo_countries` | `string[]` | No | Each item: Pattern `^[A-Z]{2}$`. | | `packages[].targetingOverlay.geo_countries_exclude` | `string[]` | No | Each item: Pattern `^[A-Z]{2}$`. | | `packages[].targetingOverlay.geo_regions` | `string[]` | No | Each item: Pattern `^[A-Z]{2}-[A-Z0-9]{1,3}$`. | | `packages[].targetingOverlay.geo_regions_exclude` | `string[]` | No | Each item: Pattern `^[A-Z]{2}-[A-Z0-9]{1,3}$`. | | `packages[].targetingOverlay.geo_metros` | `object[]` | No | | | `packages[].targetingOverlay.geo_metros_exclude` | `object[]` | No | | | `packages[].targetingOverlay.audience_include` | `string[]` | No | | | `packages[].targetingOverlay.audience_exclude` | `string[]` | No | | | `packages[].targetingOverlay.device_type` | `enum[]` | No | Each one of `desktop`, `mobile`, `tablet`, `ctv`, `dooh`, `unknown`. | | `packages[].targetingOverlay.device_type_exclude` | `enum[]` | No | Each one of `desktop`, `mobile`, `tablet`, `ctv`, `dooh`, `unknown`. | | `packages[].targetingOverlay.language` | `string[]` | No | | | `endTime` | `string` | No | ISO 8601 date-time with offset. | | `pacingPeriods` | `object \| null` | No | Object form: `mode`, `periods`. | | `reason` | `string` | No | ≤ 500 chars. | | `expectedRevision` | `integer` | No | min 0. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `update_property_list` Rename a property list and/or replace its full identifier set (no incremental add/remove: send the whole set). Changing an include list's identifiers re-sends it to the advertiser's active media buys (cascadeSummary). | | | | ------------ | ---------------------------------- | | Effect | Write | | Risk | External (contacts a counterparty) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | --------------------- | ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | No | 1–255 chars. | | `domains` | `string[]` | No | Each item: 1–1024 chars. ≤ 100000 items. | | `identifiers` | `object[]` | No | ≤ 100000 items. | | `identifiers[].type` | `enum` | Yes | One of `domain`, `subdomain`, `ios_bundle`, `android_package`, `apple_app_store_id`, `google_play_id`, `roku_store_id`, `fire_tv_asin`, `samsung_app_id`, `apple_tv_bundle`, `bundle_id`. | | `identifiers[].value` | `string` | Yes | 1–1024 chars. | | `advertiserId` | `integer \| string` | No | | | `listId` | `string` | Yes | ≥ 1 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `upload_creative_asset` Open the upload task so the person can add images, video or audio to the library. | | | | ------------ | ---------------------------------------------------------------------------- | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | `upload-creative-asset` (`ui://semicola/upload-creative-asset/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | -------------- | ------------------- | -------- | ----- | | `advertiserId` | `integer \| string` | Yes | | | `campaignId` | `string` | No | | ## Seller tools Listed when the active account is a seller (a storefront). | Tool | Effect | Priority | Summary | | ------------------------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `activate_discovery_hostname` | Write | P1 | Verify or re-verify the storefront's public listing domain by reading its routing proof. | | `approve_sponsored_buyer` | Write | P1 | Approve a pending buyer on your storefront so it can transact (optionally set prepay or credit). | | `create_inventory_feed` | Write | P1 | Register an inventory feed capability on a modular source (static-avails-feed v1 or v1-push). | | `decide_creative_review` | Write | P0 | Approve or reject a pending creative review. | | `decide_media_buy_approval` | Write | P0 | Approve or reject a queued media buy. | | `declare_roster_property` | Write | P1 | Record a seller-declared property under an already-declared publisher domain. | | `discover_agents` | Read | P1 | Find the agents authorized for a domain: the publisher's live adagents.json (direct, authoritative\_location or ads.txt managerdomain) and the AAO registry's operator record when the registry is connected. | | `get_inventory_feed_status` | Read | P1 | Read an inventory feed's canonical identity, registered capabilities, active head, sync health and latest attempt (counts, digests and diagnostic codes; never rows). | | `get_rfp_performance` | Read | P0 | RFP performance over a range: win rate, booked budget, average grade, response and acceptance rates, latency. | | `get_status_setup_nav` | Read | P1 | The storefront setup rail: sections, row health, go-live steps and the next action. | | `get_storefront_activity_call` | Read | P1 | One recorded API/MCP call on the storefront (an id from list\_storefront\_activity view "calls"): outcome, correlation ids, error, safe request JSON, error response, selected headers and diagnostic steps. | | `list_storefront_activity` | Read | P1 | Storefront activity. | | `open_approvals` | Read | P0 | Open approvals & operations: media buy approvals, creative reviews and failed forwards. | | `open_media_buys_page` | Read | P0 | Open every media buy on the storefront, most urgent first. | | `open_proposal_pass` | Read | P0 | Open one RFP turn: request, decision, products, allocations and history. | | `preview_wholesale_pricing_upload` | Read | P1 | Preview a wholesale avails & pricing feed attached in chat (CSV or XLSX) for an ad-server source. | | `probe_discovery_openai_challenge` | Write | P1 | Re-check that the OpenAI challenge address returns exactly the saved token. | | `publish_discovery` | Write | P1 | Set listing visibility: marketplace, public (served on the verified public listing domain), or private (unlists everywhere; confirm first). | | `reactivate_sponsored_buyer` | Write | P1 | Reactivate a suspended buyer on your storefront. | | `remove_declared_roster_property` | Write | P1 | Remove one seller-declared property from the roster. | | `retry_forward` | Write | P1 | Re-send an approved media buy whose forward to the inventory source failed (same idempotency key, so it cannot double-book). | | `run_inventory_source_discovery_test` | Write | P1 | Run a discovery test against an inventory source and refresh its products. | | `save_business_rules` | Write | P0 | Save and activate AI Business Rules: the acceptance policy (brief acceptance + creative policy), approval gates and listing disclosures. | | `save_discovery_hostname` | Write | P1 | Save, replace (confirmReplace) or remove the storefront's public listing domain. | | `save_inventory_source` | Write | P0 | Connect or update an inventory source (external sales agent URL + auth, or the ad server). | | `save_material` | Write | P0 | Teach the storefront agent from a media kit, rate card, deck, past RFP, note or URL. | | `save_playbook` | Write | P0 | Save the playbook: how the storefront agent pitches, packages and prices, plus pricing facts (hard floors, defaults, guidance). | | `save_proposal_draft` | Write | P1 | Proposal studio actions: start or update a draft, submit it, approve or reject it (the approver must not be the composer), or discard it. | | `save_rfp` | Write | P0 | Work a brief: create a practice or manual RFP, append a revision turn (coach and re-run), record feedback, endorse, attach a response, or request a representation (html or json). | | `save_seller` | Write | P0 | Update the storefront identity, setup intent, capabilities and listing (description, channels, countries, links, marketplace participation). | | `save_signal` | Write | P1 | Add a signal (from a suggestion or described), or archive / restore one. | | `save_test_run` | Write | P1 | Run an end-to-end sandbox check: a practice brief is answered, a sandbox media buy is booked and delivery is read back. | | `save_wholesale_product` | Write | P0 | Create or update a wholesale product: channels, delivery type, format kinds and pricing options with floors. | | `save_work_item` | Write | P1 | Complete or update a typed item from the unified work queue (search kind work\_item): a modular source follow-up with its requiredResultFields, a media-buy approval, or a creative review with its expectedContentDigest. | | `set_storefront_operator_domain` | Write | P1 | Save the storefront's brand domain from the Listing. | | `suspend_sponsored_buyer` | Write | P1 | Suspend a buyer on your storefront: new media buys and edits are blocked. | | `update_business_profile` | Write | P1 | Apply an exact business-profile change the person confirmed (summary, channels, regions, verticals, publisher domains, evidence URLs, notes, property count). | | `update_discovery_openai_challenge` | Write | P1 | Publish or remove the ChatGPT destination's OpenAI domain-ownership token on the public listing domain. | | `upload_wholesale_pricing` | Write | P1 | Commit a wholesale avails & pricing feed attached in chat, after preview\_wholesale\_pricing\_upload showed zero rejected rows and the user asked to commit. | ### `activate_discovery_hostname` Verify or re-verify the storefront's public listing domain by reading its routing proof. Requires a listing published on the marketplace; verifying never publishes. | | | | ------------ | ---------------------------------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | `media-kit` (`ui://semicola/media-kit/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | ---------- | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `approve_sponsored_buyer` Approve a pending buyer on your storefront so it can transact (optionally set prepay or credit). Asks the person to confirm. | | | | ------------ | ------------------------------------------------------------------ | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | `sponsored-buyers` (`ui://semicola/sponsored-buyers/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | -------------------------- | | `relationshipId` | `string` | Yes | ≥ 1 chars. | | `posture` | `enum` | No | One of `prepay`, `credit`. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `create_inventory_feed` Register an inventory feed capability on a modular source (static-avails-feed v1 or v1-push). Idempotent; returns the canonical feed id, key and the authenticated REST paths for feed bytes. Never issues credentials. | | | | ------------ | ----------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ------------------- | --------- | -------- | ------------ | | `profileId` | `string` | Yes | 1–100 chars. | | `profileVersion` | `string` | Yes | 1–40 chars. | | `inventorySourceId` | `string` | Yes | 1–64 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `decide_creative_review` Approve or reject a pending creative review. Always asks the person to confirm. A short note on rejection helps the buyer fix and resubmit. | | | | ------------ | ---------------------------------------------------- | | Effect | Write | | Risk | External (contacts a counterparty) | | Priority | P0 | | Opens widget | `approvals` (`ui://semicola/approvals/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | ------------------------------ | | `approvalId` | `string` | Yes | ≥ 1 chars. | | `decision` | `enum` | Yes | One of `approved`, `rejected`. | | `reviewerNotes` | `string` | No | ≤ 4000 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `decide_media_buy_approval` Approve or reject a queued media buy. Always asks the person to confirm. A short note on rejection helps the buyer fix and resubmit. | | | | ------------ | ---------------------------------------------------- | | Effect | Write | | Risk | External (contacts a counterparty) | | Priority | P0 | | Opens widget | `approvals` (`ui://semicola/approvals/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | ------------------------------ | | `approvalId` | `string` | Yes | ≥ 1 chars. | | `decision` | `enum` | Yes | One of `approved`, `rejected`. | | `reviewerNotes` | `string` | No | ≤ 4000 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `declare_roster_property` Record a seller-declared property under an already-declared publisher domain. Give at least a propertyId, an identifier or a name (the roster never invents identity); use only identity the seller has stated. A publisher-origin adagents.json declaration with the same key supersedes it (outcome: already\_resolved). | | | | ------------ | ----------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ------------------------------ | ---------- | -------- | ----------------------------------- | | `domain` | `string` | Yes | 1–253 chars. | | `property` | `object` | Yes | | | `property.propertyId` | `string` | No | 1–200 chars. | | `property.propertyType` | `string` | No | 1–64 chars. | | `property.name` | `string` | No | 1–200 chars. | | `property.identifiers` | `object[]` | No | ≤ 20 items. | | `property.identifiers[].type` | `string` | Yes | 1–64 chars. | | `property.identifiers[].value` | `string` | Yes | 1–500 chars. | | `property.tags` | `string[]` | No | Each item: 1–100 chars. ≤ 50 items. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `discover_agents` Find the agents authorized for a domain: the publisher's live adagents.json (direct, authoritative\_location or ads.txt managerdomain) and the AAO registry's operator record when the registry is connected. | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | --------- | --------- | -------- | ------------ | | `domain` | `string` | Yes | 1–253 chars. | | `refresh` | `boolean` | No | | ### `get_inventory_feed_status` Read an inventory feed's canonical identity, registered capabilities, active head, sync health and latest attempt (counts, digests and diagnostic codes; never rows). | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ------------------- | -------- | -------- | ----------- | | `inventorySourceId` | `string` | Yes | 1–64 chars. | | `feedId` | `string` | Yes | 1–64 chars. | ### `get_rfp_performance` RFP performance over a range: win rate, booked budget, average grade, response and acceptance rates, latency. Metrics with no inputs are unavailable, never 0. | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ----------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `metrics` | `enum[]` | No | Each one of `win_rate`, `booked_budget`, `average_grade`, `buyer_response_rate`, `acceptance_rate`, `average_processing_latency_ms`. ≥ 1 items. | | `range` | `object` | No | | | `range.startDate` | `string` | Yes | Pattern `^\d{4}-\d{2}-\d{2}$`. | | `range.endDate` | `string` | Yes | Pattern `^\d{4}-\d{2}-\d{2}$`. | ### `get_status_setup_nav` The storefront setup rail: sections, row health, go-live steps and the next action. Hosts render it; it never changes anything. | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ---------------------- | --------- | -------- | ----- | | `maxProjectionVersion` | `integer` | No | > 0. | ### `get_storefront_activity_call` One recorded API/MCP call on the storefront (an id from list\_storefront\_activity view "calls"): outcome, correlation ids, error, safe request JSON, error response, selected headers and diagnostic steps. Use it to debug a failed or denied call. | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | -------- | -------- | -------- | ------------ | | `callId` | `string` | Yes | 1–128 chars. | ### `list_storefront_activity` Storefront activity. view "changes" (default): who changed what, briefs received, orders and their timeline, AdCP tasks. view "calls": recorded API/MCP calls. Filter by period, action or resource. | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ------------ | -------- | -------- | --------------------------------------------------------------------------- | | `view` | `enum` | No | One of `calls`, `changes`. | | `period` | `enum` | No | One of `today`, `7d`, `30d`, `90d`, `6m`, `1y`. | | `filter` | `enum` | No | One of `all`, `created`, `updated`, `removed`, `activated`, `deactivated`. | | `resourceId` | `string` | No | ≥ 1 chars. | | `outcome` | `enum` | No | One of `succeeded`, `accepted`, `denied`, `failed`, `cancelled`, `unknown`. | | `cursor` | `string` | No | 1–200 chars. | ### `open_approvals` Open approvals & operations: media buy approvals, creative reviews and failed forwards. | | | | ------------ | ---------------------------------------------------- | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | `approvals` (`ui://semicola/approvals/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ------------ | -------- | -------- | ---------------------------------------------------- | | `queue` | `enum` | No | One of `media_buys`, `creatives`, `failed_forwards`. | | `approvalId` | `string` | No | | ### `open_media_buys_page` Open every media buy on the storefront, most urgent first. | | | | ------------ | ------------------------------------------------------ | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | `media-buys` (`ui://semicola/media-buys/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ----------------------- | -------- | -------- | --------------------------------------------- | | `accountRelationshipId` | `string` | No | | | `view` | `enum` | No | One of `media_buys`, `creatives`, `delivery`. | ### `open_proposal_pass` Open one RFP turn: request, decision, products, allocations and history. | | | | ------------ | ------------------------------------------------------------------ | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | `proposal-pass-v3` (`ui://semicola/proposal-pass-v3/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | -------- | -------- | -------- | ---------- | | `rfpId` | `string` | Yes | ≥ 1 chars. | | `turnId` | `string` | Yes | ≥ 1 chars. | ### `preview_wholesale_pricing_upload` Preview a wholesale avails & pricing feed attached in chat (CSV or XLSX) for an ad-server source. Writes nothing. Reports accepted and rejected row counts, every rejected row (row, column, why), advisories, and which selectors matched a product (or that the match is unavailable before the first product sync). Only for the wholesale pricing template; rate cards and buyer discounts have their own flows. | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | -------------- | -------- | -------- | ----------- | | `sourceId` | `string` | No | 1–64 chars. | | `attachmentId` | `string` | Yes | 1–64 chars. | ### `probe_discovery_openai_challenge` Re-check that the OpenAI challenge address returns exactly the saved token. It does not call OpenAI or mean OpenAI has verified the domain. | | | | ------------ | ---------------------------------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | `media-kit` (`ui://semicola/media-kit/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | ---------- | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `publish_discovery` Set listing visibility: marketplace, public (served on the verified public listing domain), or private (unlists everywhere; confirm first). | | | | ------------ | ---------------------------------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | `media-kit` (`ui://semicola/media-kit/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | ------------------------------------------ | | `visibility` | `enum` | Yes | One of `marketplace`, `public`, `private`. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `reactivate_sponsored_buyer` Reactivate a suspended buyer on your storefront. Asks the person to confirm. | | | | ------------ | ------------------------------------------------------------------ | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | `sponsored-buyers` (`ui://semicola/sponsored-buyers/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | ---------- | | `relationshipId` | `string` | Yes | ≥ 1 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `remove_declared_roster_property` Remove one seller-declared property from the roster. Publisher-origin properties can't be removed; they follow the publisher's adagents.json. | | | | ------------ | ----------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | ------------ | | `domain` | `string` | Yes | 1–253 chars. | | `propertyKey` | `string` | Yes | 1–500 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `retry_forward` Re-send an approved media buy whose forward to the inventory source failed (same idempotency key, so it cannot double-book). Asks the person to confirm. | | | | ------------ | ---------------------------------------------------- | | Effect | Write | | Risk | External (contacts a counterparty) | | Priority | P1 | | Opens widget | `approvals` (`ui://semicola/approvals/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | ---------- | | `mediaBuyId` | `string` | Yes | ≥ 1 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `run_inventory_source_discovery_test` Run a discovery test against an inventory source and refresh its products. | | | | ------------ | ---------------------------------------------------------------------- | | Effect | Write | | Risk | None | | Priority | P1 | | Opens widget | `source-diagnostics` (`ui://semicola/source-diagnostics/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | ---------- | | `sourceId` | `string` | Yes | ≥ 1 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `save_business_rules` Save and activate AI Business Rules: the acceptance policy (brief acceptance + creative policy), approval gates and listing disclosures. Saving activates a new version immediately. When both gates are automatic, acknowledgeNoHumanReview is required. Start conservative: no category is pre-cleared. | | | | ------------ | -------------------------------------------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P0 | | Opens widget | `business-rules` (`ui://semicola/business-rules/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | --------------------------------------------- | --------- | -------- | ------------------------ | | `content` | `object` | No | | | `content.briefAcceptance` | `string` | Yes | 1–50000 chars. | | `content.creativePolicy` | `string` | Yes | ≤ 50000 chars. | | `notes` | `string` | No | ≤ 2000 chars. | | `creativeApproval` | `enum` | No | One of `auto`, `manual`. | | `mediaBuyApproval` | `enum` | No | One of `auto`, `manual`. | | `acknowledgeNoHumanReview` | `boolean` | No | | | `advertisingPolicyDisclosure` | `object` | No | | | `advertisingPolicyDisclosure.briefAcceptance` | `boolean` | Yes | | | `advertisingPolicyDisclosure.creativePolicy` | `boolean` | Yes | | | `activateVersion` | `integer` | No | > 0. | | `approvalRouting` | `any` | No | | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `save_discovery_hostname` Save, replace (confirmReplace) or remove the storefront's public listing domain. Returns the one CNAME record to add at the registrar. | | | | ------------ | ---------------------------------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | `media-kit` (`ui://semicola/media-kit/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ----------------- | ---------------- | -------- | ---------- | | `hostname` | `string \| null` | Yes | | | `confirmReplace` | `boolean` | No | | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `save_inventory_source` Connect or update an inventory source (external sales agent URL + auth, or the ad server). Credentials are write-only and never returned. Optionally runs a discovery test. | | | | ------------ | ---------------------------------------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P0 | | Opens widget | `seller-setup` (`ui://semicola/seller-setup/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ------------------------------- | --------- | -------- | ----------------------------------------------------------------------------- | | `sourceId` | `string` | No | | | `name` | `string` | Yes | 1–200 chars. | | `executionType` | `enum` | Yes | One of `AGENT`, `MANAGED_SALES_AGENT`, `LINKED_STOREFRONT`, `MODULAR_SOURCE`. | | `endpointUrl` | `string` | No | Format `uri`. | | `protocol` | `enum` | Yes | One of `MCP`, `A2A`. | | `authenticationType` | `enum` | Yes | One of `API_KEY`, `NO_AUTH`, `JWT`, `OAUTH`, `BASIC_AUTH`. | | `credentials` | `object` | No | | | `credentials.apiKey` | `string` | No | | | `credentials.bearerToken` | `string` | No | | | `credentials.username` | `string` | No | | | `credentials.password` | `string` | No | | | `credentials.oauthClientId` | `string` | No | | | `credentials.oauthClientSecret` | `string` | No | | | `productMode` | `enum` | Yes | One of `WHOLESALE`, `COMPOSING`, `BOTH`. | | `adServer` | `object` | No | | | `adServer.type` | `enum` | Yes | One of `google_ad_manager`, `freewheel`, `springserve`. | | `adServer.networkCode` | `string` | No | Pattern `^\d+$`. | | `adServer.environment` | `enum` | No | One of `production`, `staging`. | | `runDiscoveryTest` | `boolean` | No | | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `save_material` Teach the storefront agent from a media kit, rate card, deck, past RFP, note or URL. Extracted selling points come back with their evidence status. | | | | ------------ | ------------------------------------------------ | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P0 | | Opens widget | `library` (`ui://semicola/library/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------- | | `materialId` | `string` | No | | | `kind` | `enum` | No | One of `media_kit`, `rate_card`, `deck`, `past_rfp`, `note`, `url`. | | `title` | `string` | No | 1–200 chars. | | `text` | `string` | No | ≤ 200000 chars. | | `assetRef` | `string` | No | | | `url` | `string` | No | Format `uri`. | | `action` | `enum` | No | One of `mark_reusable`, `confirm_claim`, `withdraw_claim`, `add_claim`, `open_request`, `close_request`, `evaluate`. | | `sellingPointId` | `string` | No | | | `claim` | `string` | No | 3–500 chars. | | `evidence` | `string` | No | ≤ 2000 chars. | | `requestId` | `string` | No | | | `requestDetail` | `string` | No | ≤ 2000 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `save_playbook` Save the playbook: how the storefront agent pitches, packages and prices, plus pricing facts (hard floors, defaults, guidance). Saving activates a new version. | | | | ------------ | -------------------------------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P0 | | Opens widget | `playbook` (`ui://semicola/playbook/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ------------------------------------- | ---------- | -------- | ------------------------------------------- | | `content` | `string` | No | ≤ 50000 chars. | | `activateVersion` | `integer` | No | > 0. | | `notes` | `string` | No | ≤ 2000 chars. | | `pricing` | `object` | No | | | `pricing.targetPercentile` | `enum` | No | One of `p50`, `p75`, `p90`. | | `pricing.facts` | `object[]` | No | | | `pricing.facts[].id` | `string` | No | | | `pricing.facts[].label` | `string` | Yes | 1–200 chars. | | `pricing.facts[].appliesWhen` | `string` | Yes | ≤ 1000 chars. | | `pricing.facts[].strength` | `enum` | Yes | One of `hard_floor`, `default`, `guidance`. | | `pricing.facts[].pricing` | `object` | Yes | | | `discounts` | `object[]` | No | | | `discounts[].houseDomain` | `string` | Yes | ≥ 3 chars. | | `discounts[].scope` | `enum` | Yes | One of `brand`, `operator`. | | `discounts[].discountPercent` | `number` | Yes | min 0, max 100. | | `discounts[].notes` | `string` | No | | | `buyerInstructions` | `object[]` | No | | | `buyerInstructions[].operatorDomain` | `string` | No | ≥ 3 chars. | | `buyerInstructions[].brandDomain` | `string` | No | ≥ 3 chars. | | `buyerInstructions[].discountPercent` | `number` | No | min 0, max 50. | | `buyerInstructions[].notes` | `string` | No | ≤ 4000 chars. | | `buyerInstructions[].countries` | `string[]` | No | Each item: 2–2 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `save_proposal_draft` Proposal studio actions: start or update a draft, submit it, approve or reject it (the approver must not be the composer), or discard it. Prices never go below the floor. | | | | ------------ | ---------------------------------------------------------------- | | Effect | Write | | Risk | External (contacts a counterparty) | | Priority | P1 | | Opens widget | `proposal-studio` (`ui://semicola/proposal-studio/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | -------------------------- | ---------- | -------- | ------------------------------------------------------------------- | | `action` | `enum` | Yes | One of `start`, `update`, `submit`, `approve`, `reject`, `discard`. | | `rfpId` | `string` | Yes | ≥ 1 chars. | | `turnId` | `string` | Yes | ≥ 1 chars. | | `draftId` | `string` | No | | | `products` | `object[]` | No | ≤ 20 items. | | `products[].productId` | `string` | Yes | ≥ 1 chars. | | `products[].price` | `number` | Yes | > 0. | | `allocations` | `object[]` | No | ≤ 20 items. | | `allocations[].productId` | `string` | Yes | ≥ 1 chars. | | `allocations[].percentage` | `integer` | Yes | min 0, max 100. | | `allocations[].rationale` | `string` | No | ≤ 2000 chars. | | `note` | `string` | No | ≤ 4000 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `save_rfp` Work a brief: create a practice or manual RFP, append a revision turn (coach and re-run), record feedback, endorse, attach a response, or request a representation (html or json). | | | | ------------ | ------------------------------------------------------------------ | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P0 | | Opens widget | `proposal-pass-v3` (`ui://semicola/proposal-pass-v3/mcp-app.html`) | **Input** The input is one of 8 forms. Send exactly one; fields from different forms do not mix. **Form 1: `action: "create"`** | Field | Type | Required | Notes | | ------------------------ | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | | `action` | `const` | Yes | Always `"create"`. | | `origin` | `enum` | Yes | One of `adcp`, `manual`, `imported`, `starter`. | | `purpose` | `enum` | Yes | One of `live`, `evaluation`, `draft`. | | `request` | `object` | Yes | | | `request.brief` | `string` | Yes | 1–20000 chars. | | `request.budget` | `number \| string` | No | | | `request.currency` | `string` | No | Pattern `^[A-Z]{3}$`. | | `request.flight` | `object` | No | | | `request.flight.startAt` | `string` | Yes | ISO 8601 date-time with offset. | | `request.flight.endAt` | `string` | Yes | ISO 8601 date-time with offset. | | `request.channels` | `enum[]` | No | Each one of `display`, `olv`, `social`, `search`, `ctv`, `linear_tv`, `radio`, `streaming_audio`, `podcast`, `dooh`, `ooh`, `print`, `cinema`, `email`, `gaming`, `retail_media`, `influencer`, `affiliate`, `product_placement`, `sponsored_intelligence`. | | `request.formatKinds` | `enum[]` | No | Each one of `image`, `html5`, `display_tag`, `image_carousel`, `video_hosted`, `video_vast`, `audio_hosted`, `audio_daast`, `sponsored_placement`, `native_in_feed`, `responsive_creative`, `agent_placement`, `custom`. | | `request.countries` | `string[]` | No | Each item: Pattern `^[A-Z]{2}$`. | | `request.constraints` | `string[] \| object` | No | Object form: `locale`, `mustInclude`. | | `request.productCount` | `integer` | No | > 0. | | `request.instruction` | `string` | No | ≤ 4000 chars. | | `strategy` | `object` | No | | | `clientRequestId` | `string` | No | ≥ 1 chars. | **Form 2: `action: "append_turn"`** | Field | Type | Required | Notes | | ------------------------ | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | | `action` | `const` | Yes | Always `"append_turn"`. | | `rfpId` | `string` | Yes | ≥ 1 chars. | | `parentTurnId` | `string` | Yes | ≥ 1 chars. | | `request` | `object` | Yes | | | `request.brief` | `string` | Yes | 1–20000 chars. | | `request.budget` | `number \| string` | No | | | `request.currency` | `string` | No | Pattern `^[A-Z]{3}$`. | | `request.flight` | `object` | No | | | `request.flight.startAt` | `string` | Yes | ISO 8601 date-time with offset. | | `request.flight.endAt` | `string` | Yes | ISO 8601 date-time with offset. | | `request.channels` | `enum[]` | No | Each one of `display`, `olv`, `social`, `search`, `ctv`, `linear_tv`, `radio`, `streaming_audio`, `podcast`, `dooh`, `ooh`, `print`, `cinema`, `email`, `gaming`, `retail_media`, `influencer`, `affiliate`, `product_placement`, `sponsored_intelligence`. | | `request.formatKinds` | `enum[]` | No | Each one of `image`, `html5`, `display_tag`, `image_carousel`, `video_hosted`, `video_vast`, `audio_hosted`, `audio_daast`, `sponsored_placement`, `native_in_feed`, `responsive_creative`, `agent_placement`, `custom`. | | `request.countries` | `string[]` | No | Each item: Pattern `^[A-Z]{2}$`. | | `request.constraints` | `string[] \| object` | No | Object form: `locale`, `mustInclude`. | | `request.productCount` | `integer` | No | > 0. | | `request.instruction` | `string` | No | ≤ 4000 chars. | **Form 3: `action: "record_feedback"`** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | ------------------------------------ | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | | `action` | `const` | Yes | Always `"record_feedback"`. | | `rfpId` | `string` | Yes | ≥ 1 chars. | | `turnId` | `string` | Yes | ≥ 1 chars. | | `grade` | `enum` | No | One of `A`, `B`, `C`, `D`, `E`, `F`. | | `ledBy` | `enum` | No | One of `agent`, `human`. | | `feedback` | `object` | No | | | `feedback.note` | `string` | Yes | ≤ 4000 chars. | **Form 4: `action: "endorse"`** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | ------------------- | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | | `action` | `const` | Yes | Always `"endorse"`. | | `rfpId` | `string` | Yes | ≥ 1 chars. | | `commentary` | `string` | No | ≤ 4000 chars. | **Form 5: `action: "unendorse"`** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | --------------------- | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | | `action` | `const` | Yes | Always `"unendorse"`. | | `rfpId` | `string` | Yes | ≥ 1 chars. | **Form 6: `action: "attach_response"`** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | --------------------------- | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | | `action` | `const` | Yes | Always `"attach_response"`. | | `rfpId` | `string` | Yes | ≥ 1 chars. | | `materialId` | `string` | Yes | ≥ 1 chars. | **Form 7: `action: "request_representation"`** | Field | Type | Required | Notes | | ------------------------- | --------- | -------- | ----------------------------------------------------- | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | | `action` | `const` | Yes | Always `"request_representation"`. | | `rfpId` | `string` | Yes | ≥ 1 chars. | | `turnId` | `string` | Yes | ≥ 1 chars. | | `representation` | `object` | Yes | | | `representation.format` | `enum` | Yes | One of `seller_response_json`, `html`, `pdf`, `pptx`. | | `representation.audience` | `enum` | No | One of `seller_preview`, `buyer_delivery`. | | `representation.language` | `string` | No | ≤ 35 chars. | **Form 8: `action: "cancel_representation"`** | Field | Type | Required | Notes | | ------------------ | --------- | -------- | --------------------------------- | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | | `action` | `const` | Yes | Always `"cancel_representation"`. | | `rfpId` | `string` | Yes | ≥ 1 chars. | | `representationId` | `string` | Yes | ≥ 1 chars. | ### `save_seller` Update the storefront identity, setup intent, capabilities and listing (description, channels, countries, links, marketplace participation). | | | | ------------ | ---------------------------------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P0 | | Opens widget | `media-kit` (`ui://semicola/media-kit/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | --------------------------------------- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `identity` | `object` | No | | | `identity.brandDomain` | `string` | No | ≥ 3 chars. | | `identity.name` | `string` | No | 1–200 chars. | | `setupIntent` | `enum` | No | One of `third_party_connect`, `sell_through_platform`. | | `capabilities` | `object` | No | | | `capabilities.offersCreativeReview` | `boolean` | No | | | `capabilities.offersCampaignApproval` | `boolean` | No | | | `capabilities.offersProductComposition` | `boolean` | No | | | `listing` | `object` | No | | | `listing.description` | `string` | No | ≤ 2000 chars. | | `listing.subtitle` | `string` | No | ≤ 200 chars. | | `listing.channels` | `enum[]` | No | Each one of `display`, `olv`, `social`, `search`, `ctv`, `linear_tv`, `radio`, `streaming_audio`, `podcast`, `dooh`, `ooh`, `print`, `cinema`, `email`, `gaming`, `retail_media`, `influencer`, `affiliate`, `product_placement`, `sponsored_intelligence`. | | `listing.acceptedCountries` | `string[]` | No | Each item: Pattern `^[A-Z]{2}$`. | | `listing.acceptsAllCountries` | `boolean` | No | | | `listing.supportUrl` | `string` | No | Format `uri`. | | `listing.privacyUrl` | `string` | No | Format `uri`. | | `listing.termsUrl` | `string` | No | Format `uri`. | | `marketplaceParticipation` | `enum` | No | One of `PUBLISHED`, `OPTED_OUT`. | | `demandContact` | `object \| null` | No | Object form: `name`, `email`. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `save_signal` Add a signal (from a suggestion or described), or archive / restore one. Signals are recorded on the storefront and count toward readiness; buyers cannot target them yet. | | | | ------------ | ------------------------------------------------ | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | `signals` (`ui://semicola/signals/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | ------------------------------------------------------------------------- | | `action` | `enum` | Yes | One of `create`, `archive`, `restore`. | | `signalId` | `string` | No | | | `candidateKey` | `string` | No | | | `name` | `string` | No | 2–120 chars. | | `description` | `string` | No | ≤ 1000 chars. | | `kind` | `enum` | No | One of `audience`, `contextual`, `geographic`, `temporal`, `first_party`. | | `sourceId` | `string` | No | | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `save_test_run` Run an end-to-end sandbox check: a practice brief is answered, a sandbox media buy is booked and delivery is read back. Nothing reaches buyers. | | | | ------------ | ---------------------------------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | `test-runs` (`ui://semicola/test-runs/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | --------------- | | `action` | `const` | Yes | Always `"run"`. | | `brief` | `string` | No | 1–4000 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `save_wholesale_product` Create or update a wholesale product: channels, delivery type, format kinds and pricing options with floors. | | | | ------------ | ----------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P0 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ---------------------------------- | ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `productId` | `string` | No | | | `sourceId` | `string` | No | | | `name` | `string` | Yes | 1–200 chars. | | `description` | `string` | No | ≤ 4000 chars. | | `channels` | `enum[]` | Yes | Each one of `display`, `olv`, `social`, `search`, `ctv`, `linear_tv`, `radio`, `streaming_audio`, `podcast`, `dooh`, `ooh`, `print`, `cinema`, `email`, `gaming`, `retail_media`, `influencer`, `affiliate`, `product_placement`, `sponsored_intelligence`. ≥ 1 items. | | `deliveryType` | `enum` | Yes | One of `guaranteed`, `non_guaranteed`. | | `formatKinds` | `enum[]` | Yes | Each one of `image`, `html5`, `display_tag`, `image_carousel`, `video_hosted`, `video_vast`, `audio_hosted`, `audio_daast`, `sponsored_placement`, `native_in_feed`, `responsive_creative`, `agent_placement`, `custom`. ≥ 1 items. | | `pricingOptions` | `object[]` | Yes | ≥ 1 items. | | `pricingOptions[].pricingOptionId` | `string` | No | | | `pricingOptions[].pricingModel` | `enum` | Yes | One of `cpm`, `vcpm`, `cpc`, `cpcv`, `cpv`, `cpp`, `cpa`, `flat_rate`, `time`. | | `pricingOptions[].currency` | `string` | Yes | Pattern `^[A-Z]{3}$`. | | `pricingOptions[].rate` | `number \| string` | No | | | `pricingOptions[].floorPrice` | `number \| string` | No | | | `pricingOptions[].isFixed` | `boolean` | No | | | `minSpend` | `number \| string` | No | | | `isArchived` | `boolean` | No | | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `save_work_item` Complete or update a typed item from the unified work queue (search kind work\_item): a modular source follow-up with its requiredResultFields, a media-buy approval, or a creative review with its expectedContentDigest. A repeat is unchanged; a conflicting correction is refused. | | | | ------------ | ---------------------------------- | | Effect | Write | | Risk | External (contacts a counterparty) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ----------------------- | --------- | -------- | ----------------------------------------------------------------------------- | | `kind` | `enum` | Yes | One of `modular_source`, `media_buy_approval`, `creative_review`. | | `id` | `string` | Yes | 1–64 chars. | | `status` | `enum` | Yes | One of `OPEN`, `IN_PROGRESS`, `BLOCKED`, `COMPLETED`, `approved`, `rejected`. | | `result` | `object` | No | | | `notes` | `string` | No | ≤ 4000 chars. | | `blockedReason` | `string` | No | ≤ 1000 chars. | | `expectedContentDigest` | `string` | No | ≤ 128 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `set_storefront_operator_domain` Save the storefront's brand domain from the Listing. Name and logo resolve from its brand.json; a new domain re-runs verification. | | | | ------------ | ---------------------------------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | `media-kit` (`ui://semicola/media-kit/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | ------------ | | `domain` | `string` | Yes | 3–253 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `suspend_sponsored_buyer` Suspend a buyer on your storefront: new media buys and edits are blocked. Asks the person to confirm. | | | | ------------ | ------------------------------------------------------------------ | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | `sponsored-buyers` (`ui://semicola/sponsored-buyers/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | ---------- | | `relationshipId` | `string` | Yes | ≥ 1 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `update_business_profile` Apply an exact business-profile change the person confirmed (summary, channels, regions, verticals, publisher domains, evidence URLs, notes, property count). Omitted fields stay; null clears one. | | | | ------------ | ---------------------------------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | `media-kit` (`ui://semicola/media-kit/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ------------------ | ------------------ | -------- | ---------- | | `summary` | `string \| null` | No | | | `propertyCount` | `integer \| null` | No | | | `channels` | `enum[] \| null` | No | | | `regions` | `string[] \| null` | No | | | `verticals` | `string[] \| null` | No | | | `publisherDomains` | `string[] \| null` | No | | | `evidenceUrls` | `string[] \| null` | No | | | `notes` | `string \| null` | No | | | `agentName` | `null` | No | | | `agentPersonality` | `null` | No | | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `update_discovery_openai_challenge` Publish or remove the ChatGPT destination's OpenAI domain-ownership token on the public listing domain. Replacing or removing needs explicit confirmation. | | | | ------------ | ---------------------------------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | `media-kit` (`ui://semicola/media-kit/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ----------------- | ---------------- | -------- | ---------- | | `token` | `string \| null` | Yes | | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `upload_wholesale_pricing` Commit a wholesale avails & pricing feed attached in chat, after preview\_wholesale\_pricing\_upload showed zero rejected rows and the user asked to commit. Needs approval. Fully replaces the source's prior feed; refused while any row is rejected. Check the selector match on the response: a commit can succeed and still price nothing. | | | | ------------ | ----------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | ----------- | | `sourceId` | `string` | No | 1–64 chars. | | `attachmentId` | `string` | Yes | 1–64 chars. | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ## Pages opened with `open_page` Pages without their own tool open with `open_page` and a `page` name; pass the page's focus in `arguments`. The named openers listed here are not in `tools/list` but still answer when called by name, for clients and app pages built before they moved. | Page | Account | Named opener (callable, not listed) | | -------------------------- | ------- | ----------------------------------- | | `activity` | Buyer | — | | `marketplace` | Buyer | — | | `event_sources` | Buyer | — | | `catalogs` | Buyer | — | | `escalations` | Any | `open_customer_requests` | | `release_notes` | Any | `open_release_notes` | | `advertiser_setup` | Buyer | `open_add_advertiser` | | `creative_library` | Buyer | `open_creative_library` | | `creative_composer_task` | Buyer | `open_creative_composer` | | `reporting` | Buyer | `open_reporting` | | `seller_setup` | Seller | `open_seller_setup` | | `business_rules` | Seller | `open_business_rules` | | `playbook` | Seller | `open_playbook` | | `listing` | Seller | `open_listing` | | `demand_inbox` | Seller | `open_demand_inbox` | | `media_buy_timeline` | Seller | `open_media_buy_timeline` | | `seller_dashboard` | Seller | `open_seller_dashboard` | | `library` | Seller | `open_library` | | `components` | Seller | `open_components` | | `signals` | Seller | `open_signals` | | `pending_operations` | Seller | `open_pending_operations` | | `test_runs` | Seller | `open_test_runs` | | `property_roster` | Seller | `open_property_roster` | | `source_diagnostics` | Seller | `open_source_diagnostics` | | `modular_source_setup` | Seller | `open_modular_source_setup` | | `modular_inventory_source` | Seller | `open_modular_inventory_source` | | `modular_inventory_feed` | Seller | `open_modular_inventory_feed` | | `source_discovery_preview` | Seller | `open_source_discovery_preview` | | `buyer_account_mapping` | Seller | `open_seller_buyers` | | `demo_seller` | Seller | `open_demo_storefront` | | `proposal_studio` | Seller | `open_proposal_studio` | Older page names still work but are not listed: `sellers` → `open_connections_page`, `approvals` → `open_approvals`, `discovery_card` → `listing`, `demo_storefront` → `demo_seller`, `sponsored_buyers` → `buyer_account_mapping`. `media_kit` is retired and answers with an error naming `listing`. ## Deprecated names These names answer as the current tool (same input unless noted) and are never listed. Move to the current name. | Deprecated name | Current tool | | ------------------------- | ---------------------------------------------------------------------------------- | | `decide_approval` | `decide_media_buy_approval` | | `test_inventory_source` | `run_inventory_source_discovery_test` | | `save_buyer_relationship` | `approve_sponsored_buyer`, `suspend_sponsored_buyer`, `reactivate_sponsored_buyer` | | `iu_plan_accept` | `accept_iu_rate_card_offer` | | `open_hello` | `open_page` |