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
readorwrite. 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.
Shared tools
Available on every account, buyer or seller. Start every session here.get
Read one object by kind and id, with optional includes. Use it to check on long operations you started.
Input
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.
Input
The input is one of 2 forms. Send exactly one; fields from different forms do not mix.
Form 1:
report: "campaign_delivery"
Form 2:
report: "seller_delivery"
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.
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.
Input
No arguments.
open_page
Open a page by name. The page field lists the buyer and seller pages; arguments focus the page.
Input
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.
Input
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.
Input
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.
Input
search
Find objects, docs or spec pages by text and/or kind (advertiser, campaign, proposal, rfp, …). Needs query or kind.
Input
switch_account
Switch the active account (a customerId from get_status, or “home”). Returns the new status.
Input
Buyer tools
Listed when the active account is a buyer (advertiser or agency).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.
Input
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).
Input
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.
Input
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.
Input
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.
Input
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.
Input
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.
Input
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).
Input
delete_property_list
Archive a property list: it stops shaping future discovery and media buys.
Input
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.
Input
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.
Input
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.
Input
get_creative_confirmation
Re-show a campaign’s creative card (its creatives with status and format coverage). Read-only: it attaches nothing.
Input
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.
Input
get_optimization_suggestion
Read one optimization suggestion: the proposed budget change, its rationale and the pacing recommendation.
Input
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.
Input
get_property_list_report
Get the bucket summary of an earlier property list check by reportId (kept 7 days).
Input
get_update_proposal
Poll a media buy update proposal: PENDING until the seller approves (APPROVED) or declines (REJECTED, with rejectionReason).
Input
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.
Input
list_catalogs
List the advertiser’s catalog feeds with health, item counts, versions, refresh runs, transform and activation jobs.
Input
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.
Input
list_optimization_suggestions
List optimization suggestions for your media buys, optionally by campaign, media buy or status (received = waiting for your approval).
Input
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.
Input
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.
Input
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.
Input
log_event
Log up to 10,000 conversion events to an event source (server-to-server).
Input
open_advertisers_page
Open the advertisers list. Use it for any request to see or pick advertisers.
Input
No arguments.
open_campaign_receipt
Open Review & go live for a draft campaign: plan, staged buys, budget, creative coverage and blockers.
Input
open_campaigns_page
Open campaigns for the advertiser in scope, or one campaign workspace when campaignId is given.
Input
open_connections_page
Open the sellers page. Use it for “where can I advertise” and any request to see or manage sellers.
Input
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.
Input
preview_catalog_activation_plan
Preview what activating a catalog would create: campaign groups, creative assets and which connected sellers can take the catalog.
Input
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.
Input
refresh_catalog
Fetch a URL catalog feed now and store a new version when items changed.
Input
reject_optimization_suggestion
Reject an optimization suggestion, with an optional reason. Nothing changes.
Input
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.
Input
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.
Input
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.
Input
The input is one of 4 forms. Send exactly one; fields from different forms do not mix.
Form 1: with
name, idempotencyKey
Form 2: with
advertiserId
Form 3: with
advertiserIds, isArchived
Form 4: with
resolveBrand
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.
Input
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).
Input
The input is one of 2 forms. Send exactly one; fields from different forms do not mix.
Form 1: with
name, idempotencyKey
Form 2: with
campaignId, expectedRevision
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.
Input
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.
Input
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.
Input
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.
Input
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.
Input
The input is one of 4 forms. Send exactly one; fields from different forms do not mix.
Form 1:
operation: "save_draft"
Form 2:
operation: "finalize_approved_output"
Form 3:
operation: "select_output"
Form 4:
operation: "approve_output"
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.
Input
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.
Input
save_measurement_source
Create or update a conversion event source for the advertiser (event types, allowed domains). Performance goals and reporting read its events.
Input
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.
Input
The input is one of 4 forms. Send exactly one; fields from different forms do not mix.
Form 1: with
fromProposalId, idempotencyKey
Form 2: with
campaignId, sellerId, products, idempotencyKey
Form 3:
isArchived: true
Form 4: with
mediaBuyId, isPaused
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.
Input
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.
Input
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.
Input
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).
Input
upload_creative_asset
Open the upload task so the person can add images, video or audio to the library.
Input
Seller tools
Listed when the active account is a seller (a storefront).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.
Input
approve_sponsored_buyer
Approve a pending buyer on your storefront so it can transact (optionally set prepay or credit). Asks the person to confirm.
Input
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.
Input
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.
Input
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.
Input
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).
Input
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.
Input
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).
Input
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.
Input
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.
Input
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.
Input
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.
Input
open_approvals
Open approvals & operations: media buy approvals, creative reviews and failed forwards.
Input
open_media_buys_page
Open every media buy on the storefront, most urgent first.
Input
open_proposal_pass
Open one RFP turn: request, decision, products, allocations and history.
Input
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.
Input
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.
Input
publish_discovery
Set listing visibility: marketplace, public (served on the verified public listing domain), or private (unlists everywhere; confirm first).
Input
reactivate_sponsored_buyer
Reactivate a suspended buyer on your storefront. Asks the person to confirm.
Input
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.
Input
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.
Input
run_inventory_source_discovery_test
Run a discovery test against an inventory source and refresh its products.
Input
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.
Input
save_discovery_hostname
Save, replace (confirmReplace) or remove the storefront’s public listing domain. Returns the one CNAME record to add at the registrar.
Input
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.
Input
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.
Input
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.
Input
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.
Input
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).
Input
The input is one of 8 forms. Send exactly one; fields from different forms do not mix.
Form 1:
action: "create"
Form 2:
action: "append_turn"
Form 3:
action: "record_feedback"
Form 4:
action: "endorse"
Form 5:
action: "unendorse"
Form 6:
action: "attach_response"
Form 7:
action: "request_representation"
Form 8:
action: "cancel_representation"
save_seller
Update the storefront identity, setup intent, capabilities and listing (description, channels, countries, links, marketplace participation).
Input
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.
Input
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.
Input
save_wholesale_product
Create or update a wholesale product: channels, delivery type, format kinds and pricing options with floors.
Input
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.
Input
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.
Input
suspend_sponsored_buyer
Suspend a buyer on your storefront: new media buys and edits are blocked. Asks the person to confirm.
Input
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.
Input
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.
Input
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.
Input
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.
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.