> ## 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` (8 shared, 17 buyer, 20 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_hello` | Read | P0 | Open the hello widget (reference widget used to check the widget host). | | `open_page` | Read | P0 | Open a page widget by name (activity, marketplace, …). | | `save_ask` | Write | P1 | File a request with the team: support, product, supply, integration or commercial. | | `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`, `wholesale_product`, `proposal`, `media_buy`, `seller`, `connection`, `ask`, `catalog`, `measurement_source`, `conversation`, `skill`, `inventory_source`, `material`, `rfp`, `rfp_turn`, `library_request`, `coverage`, `playbook`, `business_rules`, `work_item`, `signal`, `agent`, `session`. | | `id` | `string` | No | | | `include` | `string[]` | No | | | `advertiserId` | `integer \| string` | No | | ### `get_delivery` Delivery report. Buyers use report "campaign\_delivery"; sellers "seller\_delivery". Ranges ≤ 90 days or lifetime. 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[]` | 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.advertiserId` | `integer \| string` | No | | | `filters.campaignId` | `string` | No | | | `filters.mediaBuyId` | `string` | No | | | `filters.packageId` | `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_hello` Open the hello widget (reference widget used to check the widget host). | | | | ------------ | -------------------------------------------- | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | `hello` (`ui://semicola/hello/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ------ | -------- | -------- | ------------ | | `name` | `string` | No | ≤ 100 chars. | ### `open_page` Open a page widget by name (activity, marketplace, …). Prefer the specific open\_\* tool when one exists. | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ----------- | -------- | -------- | ------------------------------------------------------------------------------------ | | `page` | `enum` | Yes | One of `activity`, `marketplace`, `event_sources`, `buyer_account_mapping`, `hello`. | | `arguments` | `object` | No | | ### `save_ask` File a request with the team: support, product, supply, integration or commercial. One ask per call. | | | | ------------ | ----------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P1 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | ----------------- | --------- | -------- | ------------------------------------------------------------------- | | `type` | `enum` | Yes | One of `support`, `product`, `supply`, `integration`, `commercial`. | | `title` | `string` | Yes | 1–200 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. | ### `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`, `wholesale_product`, `proposal`, `media_buy`, `seller`, `connection`, `ask`, `catalog`, `measurement_source`, `conversation`, `skill`, `inventory_source`, `material`, `rfp`, `rfp_turn`, `library_request`, `coverage`, `playbook`, `business_rules`, `work_item`, `signal`, `agent`, `session`. | | `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 | | ------------------------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `open_add_advertiser` | Read | P0 | Open the advertiser setup task (brand lookup, currency, countries, sandbox). | | `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_composer` | Read | P0 | Open the creative composer for a format (vertical\_story, display\_300x250, audio\_30, video\_reels), or resume a draft. | | `open_creative_library` | Read | P0 | Open the creative library for the advertiser in scope. | | `open_reporting` | Read | P0 | Open the reporting view for the advertiser or campaign in scope. | | `refine_proposal` | Write | P0 | Ask one seller to revise a proposal (keep or drop products, shift budget, new instructions). | | `request_proposals` | Write | P0 | Send the campaign brief to every eligible seller and collect proposals. | | `save_advertiser` | Write | P0 | Create, update, archive an advertiser, or preview a brand with \{resolveBrand: domain}. | | `save_campaign` | Write | P0 | Create a DRAFT campaign or change one. | | `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_session` | Write | P0 | Composer drafts: save\_draft stores slot values (optimistic on expectedRevision); finalize\_approved\_output turns the draft into a library creative. | | `save_media_buy` | Write | P0 | Stage a draft media buy on the campaign from a proposal or a product selection, or archive a draft. | | `upload_creative_asset` | Read | P0 | Open the upload task so the person can add images, video or audio to the library. | ### `open_add_advertiser` Open the advertiser setup task (brand lookup, currency, countries, sandbox). | | | | ------------ | -------------------------------------------------------------- | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | `add-advertiser` (`ui://semicola/add-advertiser/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ------------- | -------- | -------- | ----- | | `brandDomain` | `string` | No | | ### `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`. | ### `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_composer` Open the creative composer for a format (vertical\_story, display\_300x250, audio\_30, video\_reels), or resume a draft. | | | | ------------ | ------------------------------------------------------------------------------ | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | `creative-composer-task` (`ui://semicola/creative-composer-task/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | --------------- | ------------------- | -------- | ---------------------------------------------------------------------- | | `advertiserId` | `integer \| string` | No | | | `campaignId` | `string` | No | | | `format` | `enum` | No | One of `vertical_story`, `display_300x250`, `audio_30`, `video_reels`. | | `sessionId` | `string` | No | | | `creativeId` | `string` | No | | | `pinnedAssetId` | `string` | No | | ### `open_creative_library` Open the creative library for the advertiser in scope. | | | | ------------ | ------------------------------------------------------------------------ | | Effect | Read | | Risk | None | | 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 | | | `lens` | `enum` | No | One of `creatives`, `assets`. | | `initialAction` | `enum` | No | One of `upload`, `compose`. | ### `open_reporting` Open the reporting view for the advertiser or campaign in scope. | | | | ------------ | ------------------ | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | None (text result) | **Input** | Field | Type | Required | Notes | | -------------- | ------------------- | -------- | -------------- | | `advertiserId` | `integer \| string` | No | | | `campaignId` | `string` | No | | | `days` | `integer` | No | min 1, max 90. | ### `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. | ### `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 | | ### `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`. | | `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`. | | `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_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 `advertiserId`, `name`, `idempotencyKey`** | Field | Type | Required | Notes | | ----------------------------- | ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `advertiserId` | `integer \| string` | Yes | | | `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 | | | `targeting.countries` | `string[]` | No | Each item: Pattern `^[A-Z]{2}$`. | | `targeting.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`. | | `targeting.ageRange` | `object` | No | | | `targeting.ageRange.min` | `integer` | Yes | min 13. | | `targeting.ageRange.max` | `integer` | Yes | max 99. | | `targeting.audience` | `string` | No | ≤ 500 chars. | | `targeting.geoMetros` | `string[]` | No | | | `optimizationGoals` | `object[]` | No | | | `creativeIds` | `string[]` | No | | | `autonomy` | `object` | No | | | `autonomy.inventorySelection` | `enum` | Yes | One of `manual`, `propose`, `automatic`. | | `autonomy.rebriefing` | `enum` | Yes | One of `manual`, `propose`, `automatic`. | | `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 | | | `targeting.countries` | `string[]` | No | Each item: Pattern `^[A-Z]{2}$`. | | `targeting.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`. | | `targeting.ageRange` | `object` | No | | | `targeting.ageRange.min` | `integer` | Yes | min 13. | | `targeting.ageRange.max` | `integer` | Yes | max 99. | | `targeting.audience` | `string` | No | ≤ 500 chars. | | `targeting.geoMetros` | `string[]` | No | | | `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. 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` | Yes | | | `target.kind` | `enum` | Yes | One of `seller`, `creative_engine`. | | `target.id` | `integer \| string` | Yes | | | `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`. | | `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 | | | `confirm` | `boolean` | No | | | `confirmationUid` | `string` | No | ≥ 5 chars. | ### `save_creative_session` Composer drafts: save\_draft stores slot values (optimistic on expectedRevision); finalize\_approved\_output turns the draft into 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` | Yes | One of `vertical_story`, `display_300x250`, `audio_30`, `video_reels`. | | `slots` | `object[]` | Yes | ≥ 1 items, ≤ 12 items. | | `slots[].slotId` | `string` | Yes | ≥ 1 chars. | | `slots[].value` | `string` | No | ≤ 5000 chars. | | `slots[].assetId` | `string` | No | | | `title` | `string` | No | ≤ 200 chars. | | `clickUrl` | `string \| null` | No | | | `idempotencyKey` | `string` | Yes | 16–255 chars. Pattern `^[A-Za-z0-9_.:-]+$`. | **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. | **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. | ### `save_media_buy` Stage a draft media buy on the campaign from a proposal or a product selection, or archive a draft. Staging contacts no seller; nothing is booked until the campaign goes live. | | | | ------------ | ---------------------------------------------------- | | Effect | Write | | Risk | Durable (changes saved state) | | Priority | P0 | | Opens widget | `campaigns` (`ui://semicola/campaigns/mcp-app.html`) | **Input** The input is one of 3 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 | | | `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 | | | `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. | ### `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 | | ------------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `decide_approval` | Write | P0 | Approve or reject a queued media buy or creative. | | `get_rfp_performance` | Read | P0 | RFP performance over a range: win rate, booked budget, average grade, response and acceptance rates, latency. | | `open_approvals` | Read | P0 | Open approvals & operations: media buy approvals, creative reviews and failed forwards. | | `open_business_rules` | Read | P0 | Open AI Business Rules. | | `open_demand_inbox` | Read | P0 | Open the demand inbox: metrics, starter briefs and the brief ledger. | | `open_library` | Read | P0 | Open the library: uploaded materials and extracted selling points. | | `open_listing` | Read | P0 | Open the listing (branding & distribution) and the "How buyers see you" preview. | | `open_media_buy_timeline` | Read | P0 | Open the timeline for one media buy: stages, timestamps and where it is stuck. | | `open_media_buys_page` | Read | P0 | Open every media buy on the storefront, most urgent first. | | `open_playbook` | Read | P0 | Open the playbook. | | `open_proposal_pass` | Read | P0 | Open one RFP turn: request, decision, products, allocations and history. | | `open_seller_dashboard` | Read | P0 | Open the seller dashboard: RFP performance and delivery on your inventory. | | `open_seller_setup` | Read | P0 | Open "Get ready to sell": readiness checks, inventory sources and demand coverage. | | `save_business_rules` | Write | P0 | Save and activate AI Business Rules: the acceptance policy (brief acceptance + creative policy), approval gates and listing disclosures. | | `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_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_wholesale_product` | Write | P0 | Create or update a wholesale product: channels, delivery type, format kinds and pricing options with floors. | ### `decide_approval` Approve or reject a queued media buy or creative. 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. | ### `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}$`. | ### `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_business_rules` Open AI Business Rules. Use it whenever the person wants to see or change what the storefront accepts or when a human reviews. | | | | ------------ | -------------------------------------------------------------- | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | `business-rules` (`ui://semicola/business-rules/mcp-app.html`) | **Input** No arguments. ### `open_demand_inbox` Open the demand inbox: metrics, starter briefs and the brief ledger. | | | | ------------ | ---------------------------------------------------------------- | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | `demand-inbox-v3` (`ui://semicola/demand-inbox-v3/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ------- | -------- | -------- | ------------ | | `query` | `string` | No | ≤ 200 chars. | ### `open_library` Open the library: uploaded materials and extracted selling points. | | | | ------------ | ------------------------------------------------ | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | `library` (`ui://semicola/library/mcp-app.html`) | **Input** No arguments. ### `open_listing` Open the listing (branding & distribution) and the "How buyers see you" preview. | | | | ------------ | ---------------------------------------------------- | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | `media-kit` (`ui://semicola/media-kit/mcp-app.html`) | **Input** No arguments. ### `open_media_buy_timeline` Open the timeline for one media buy: stages, timestamps and where it is stuck. | | | | ------------ | ---------------------------------------------------------------------- | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | `media-buy-timeline` (`ui://semicola/media-buy-timeline/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ------------ | -------- | -------- | ---------- | | `mediaBuyId` | `string` | Yes | ≥ 1 chars. | ### `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_playbook` Open the playbook. | | | | ------------ | -------------------------------------------------- | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | `playbook` (`ui://semicola/playbook/mcp-app.html`) | **Input** No arguments. ### `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. | ### `open_seller_dashboard` Open the seller dashboard: RFP performance and delivery on your inventory. | | | | ------------ | ------------------------------------------------------------------------ | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | `seller-dashboard-v3` (`ui://semicola/seller-dashboard-v3/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ----------------- | -------- | -------- | ------------------------------ | | `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}$`. | ### `open_seller_setup` Open "Get ready to sell": readiness checks, inventory sources and demand coverage. | | | | ------------ | ---------------------------------------------------------- | | Effect | Read | | Risk | None | | Priority | P0 | | Opens widget | `seller-setup` (`ui://semicola/seller-setup/mcp-app.html`) | **Input** | Field | Type | Required | Notes | | ------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `focus` | `enum` | No | One of `acceptance_policy`, `billing_setup`, `currency`, `sales_agent`, `inventory_sources`, `source_setup`, `listing`, `publish_validation`, `first_intelligence_run`. | ### `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 | | | `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`. | | `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` | Yes | One of `media_kit`, `rate_card`, `deck`, `past_rfp`, `note`, `url`. | | `title` | `string` | Yes | 1–200 chars. | | `text` | `string` | No | ≤ 200000 chars. | | `assetRef` | `string` | No | | | `url` | `string` | No | Format `uri`. | | `action` | `const` | No | Always `"mark_reusable"`. | | `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. | | `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 | | | `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 | | ------------------------ | ------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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[]` | No | | | `request.productCount` | `integer` | No | > 0. | | `request.instruction` | `string` | No | ≤ 4000 chars. | | `strategy` | `object` | No | | | `clientRequestId` | `string` | Yes | ≥ 1 chars. | **Form 2: `action: "append_turn"`** | Field | Type | Required | Notes | | ------------------------ | ------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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[]` | No | | | `request.productCount` | `integer` | No | > 0. | | `request.instruction` | `string` | No | ≤ 4000 chars. | **Form 3: `action: "record_feedback"`** | Field | Type | Required | Notes | | --------------- | -------- | -------- | ------------------------------------ | | `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 | | ------------ | -------- | -------- | ------------------- | | `action` | `const` | Yes | Always `"endorse"`. | | `rfpId` | `string` | Yes | ≥ 1 chars. | | `commentary` | `string` | No | ≤ 4000 chars. | **Form 5: `action: "unendorse"`** | Field | Type | Required | Notes | | -------- | -------- | -------- | --------------------- | | `action` | `const` | Yes | Always `"unendorse"`. | | `rfpId` | `string` | Yes | ≥ 1 chars. | **Form 6: `action: "attach_response"`** | Field | Type | Required | Notes | | ------------ | -------- | -------- | --------------------------- | | `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 | | ------------------------- | -------- | -------- | ----------------------------------------------------- | | `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`. | **Form 8: `action: "cancel_representation"`** | Field | Type | Required | Notes | | ------------------ | -------- | -------- | --------------------------------- | | `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`. | | `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. |