Omneky

Use this when the user asks how many people a targeting setup would reach on a channel. A channel that cannot estimate reach returns unsupported_channel with the supported channels. Pass non-empty targeting_fragments from search_targeting for the same channel. Example: channel "google". Intents: audience size, reach estimate, how many people Do not use for targeting ids (search_targeting). Side effects: none. Retry: safe. Errors: unsupported_channel → retry with a channel from supported; empty targeting_fragments → search_targeting then retry; channel_not_connected → call get_connect_link for that channel; brand_required → call list_brands and retry with brand_id.

estimate_reach

Use this when: App-only Range-GET chunk for widget blob autoplay assembly when the poll cannot inline a full data:video. Not a generation start. Intents: video chunk, widget autoplay, Range GET Do not use to create or change anything. Side effects: none. Retry: safe.

fetch_video_chunk

Use this when the user wants to pick an AI presenter (avatar) or a voice for an avatar video. include: avatars, voices, both (default) or filters. Intents: avatars, presenters, AI actor, voices, voiceover options Do not use to render the video (generate_avatar_video_ad) or to clone the user's own voice (clone_voice). Side effects: none. Retry: safe.

find_avatars_and_voices

Use this when the user wants a talking-head (UGC-style) avatar video ad: a person on screen speaking a short line about the brand or product. Returns job_id. One of avatar_url or person_image_url is required: a stock portrait from find_avatars_and_voices, or an image from the user's own brand assets of a person who has consented to appear. user_prompt (the spoken line) is limited to about 30 seconds. Adding product_image_url changes the cost. Costs credits. After an ambiguous timeout do not resubmit; check list_creatives. Check progress with get_creative_status kind=video. Intents: avatar video, UGC talking head, talking-head ad, avatar_url, person_image_url, voice_id Do not use for job status (get_creative_status) or to edit/resize an existing asset (edit_image, resize_creative). Side effects: spends credits; creates an asset. Retry: check get_creative_status first; a resubmit is a new job and a new charge.

generate_avatar_video_ad

Use this when the user asks for a new static image ad, 2-3 different ads at once (pass them all in concepts: one call, one widget), or 2-3 variations of a concept or of an existing ad (count, base_ad_url). Act only when the user asks for a new or changed creative; for vague asks such as 'make my ads better', give recommendations first (get_recommendations) and ask before generating. A product URL or image already in the chat is enough; no catalogue lookup is needed. Example: ad_concept "Summer sale on trail sandals", user_assets [product image URL], count 3. Intents: make an image ad, 3 image ads, product image ad, variations, 3 versions, A/B creatives Do not use to change an existing image (edit_image), to change only its size (resize_creative), for video, or for job status (get_creative_status). Side effects: spends credits and creates assets. The balance is checked before the job starts (a short balance starts nothing); the result shows the credits charged, so state it and proceed. Retry: reusing the same gpt_ad_gen_id returns the original job (no second charge); a new gpt_ad_gen_id is a new job. Check get_creative_status before retrying. Errors: credit_insufficient or payment_required → nothing started and nothing was charged; explain the shortfall (required vs balance); brand_required → call list_brands and retry with brand_id.

generate_image_ad

Use this when the user wants a new multi-scene video ad for a product (for example a Reels or TikTok-style product video). It renders the video and returns job_id; check progress with get_creative_status. Two ways to call it: pass a narrative_id chosen from plan_product_video (the server fills in script, segments, music and hook), or omit narrative_id and narrative and pass the user's script or direction as user_prompt to generate right away (target_duration 10–30 seconds; default 12). Always pass the brand and product fields (product_name, product_description, product_image_urls). Costs credits: a short balance returns credit_insufficient with required and balance; credits_charged on the result says whether credits were spent. credit_insufficient or narrative_unresolved means no job started. Example: product_name "Trail Sandal", orientation "portrait", target_duration 15. Intents: turn this product into a video ad, product video ad, video ad, video commercial, turn product into video, make a product video, narrative_id, Reels video Do not use for job status (get_creative_status) or to edit/resize an existing asset (edit_image, resize_creative). Side effects: spends credits; creates an asset. Retry: check get_creative_status first; a resubmit is a new job and a new charge.

generate_product_video

Use this when: Queue a short or long commercial video. Cost scales with target_duration (omit for the 10-second default). Returns job_id. No progress widget — poll get_creative_status with that job_id and kind=video. Optional stock avatar_id when someone is on screen. A short balance returns credit_insufficient and nothing starts. Credits are charged when the job starts. Intents: professional video ad, short commercial, long commercial, commercial video, job_id Do not use for job status (get_creative_status) or to edit/resize an existing asset (edit_image, resize_creative). Side effects: spends credits; creates an asset. Retry: check get_creative_status first; a resubmit is a new job and a new charge.

generate_professional_video_ad

Use this when the user asks who they are signed in as, which company or subscription they have, how many credits are left, whether a card is on file, or where credits went. Read-only: returns the user, company, plan, credit balance and a payment-method summary (card brand, last four digits and expiry only, never the full card number). It cannot charge, buy or change anything. Set include_credit_history=true only when the user asks where credits went (example: history_days 30). Intents: my account, credits left, credit balance, subscription, payment method, credit history, who am I Do not use to buy credits or change plans (tell the user to do that on omneky.com), or for ad spend (get_performance_summary). Side effects: none. Retry: safe. Errors: a section marked status=error is unavailable; answer from the rest.

get_account

Use this when the user wants a brand's record or brand kit: name, website, logo, colors, fonts, tone and saved assets. Example: brand_id 4821 (optional with one brand). Intents: brand kit, logo, brand colors, brand details, brand voice Do not use to list brands (list_brands), to research the market (analyze_brand), or for products (get_products). Side effects: none. Retry: safe. Errors: brand_required → call list_brands and retry with brand_id.

get_brand

Use this when the user wants to connect any ad channel or data source (Meta, Google, TikTok, LinkedIn, Reddit, Pinterest, X, OpenAI Ads, Google Drive, HubSpot, PostHog, Semrush, Ahrefs). Returns a connect card with a link to the brand's Connections page in the Omneky web app, where the user signs in to the provider or enters a key. This tool only returns the link; it does not connect anything itself or handle credentials. Never ask for a key in chat. Example: connector "tiktok". Intents: connect my TikTok, link Google Ads, connect Drive, connect Pinterest, connect OpenAI Ads, connect PostHog, connect HubSpot Do not use to check status (list_connections) or to choose an ad account (link_ad_account). Side effects: none; the user connects on the Omneky site. Retry: safe. Errors: invalid_argument → use a connector from the allowed list.

get_connect_link

Use this when the user asks whether an image or video job is ready, or you need a finished job's asset URLs, and you have its job_id. One call per ask; it never starts a render. When this poll sees the job finish or fail, it settles that job's credit charge (marks it completed or failed) once, so it is a write, not a pure read. Example: job_id "img_8f2c", kind "auto". Intents: is my video ready, is my image done, job status, render progress Do not use to start a render (generate_image_ad and the video tools). Side effects: settles credits once when the job completes; later polls do not charge again. Retry: safe. Errors: not_found → the job_id is wrong or from another account; ask the user.

get_creative_status

Use this when the user asks which keywords a domain ranks for (pass domain) or one keyword's volume and difficulty (pass keyword, example "hiking sandals"). Intents: keywords we rank for, keyword volume, keyword difficulty Do not use for a domain's overall SEO standing (get_seo_domain_overview). Side effects: none. Retry: safe. Errors: not connected → list_connections, then get_connect_link.

get_keyword_insights

Use this when the user asks for a channel's minimum budget, or a launch needs custom conversion events or properties. Example: channel "tiktok", objective "traffic". include: minimum_budget (default), custom_properties. Intents: minimum budget, custom conversions, pixel events, launch requirements Do not use as a routine step before every launch (launch tools state their own limits), to launch (launch_*_ad), or for audience size (estimate_reach). Side effects: none. Retry: safe. Errors: channel_not_connected → call get_connect_link for that channel; brand_required → call list_brands and retry with brand_id.

get_launch_requirements

Use this when the user wants to see their marketing plans, one plan's steps, or a plan run's progress. Omit plan_id to list plans; pass run_id for a run. Example: plan_id "88". Intents: my marketing plans, plan steps, plan progress, run status Do not use to create (create_marketing_plan) or change (revise_marketing_plan). Side effects: none. Retry: safe. Errors: brand_required → call list_brands and retry with brand_id.

get_marketing_plan

Use this when: Ranked paid-media breakdown by a dimension — creative, campaign, ad set, ad, channel, or similar — with spend, ROAS, CTR, and conversions. Use for 'which ads/campaigns are winning'. ``date_range`` is two inclusive ``YYYY-MM-DD`` dates, ``[start, end]``. Pass ``filters`` as ``[]`` when not filtering. ``selected_conversion_metric_value`` is the brand's configured goal and varies per channel. Totals across channels mix incompatible goals; group by channel or use a named metric (purchases, clicks, …). There is no ``run_sql_query`` or score / lift endpoint on this surface. Intents: which ads should I make more of, winning ads, best creatives, ROAS, CTR, spend, creative breakdown, campaign performance, channel mix, Meta ads, Facebook ads, Google Ads, TikTok ads, LinkedIn ads, Reddit ads, paid media Do not use to create or change anything. Side effects: none. Retry: safe.

get_performance_breakdown

Use this when: What rose or fell versus the prior period for a brand's paid-media metrics (spend, ROAS, CTR, conversions, and similar). Pass ``end_date`` (``YYYY-MM-DD``) and ``period_days`` (default 7). Do not send ``date_range``. ``selected_conversion_metric_value`` is the brand's configured goal and varies per channel. Totals across channels mix incompatible goals; group by channel or use a named metric (purchases, clicks, …). There is no ``run_sql_query`` or score / lift endpoint on this surface. Intents: trending, period-over-period, ROAS change, CTR change, paid media winners, Meta, Facebook, Google, TikTok Do not use to create or change anything. Side effects: none. Retry: safe.

get_performance_movers

Use this when the user asks how their ads did overall or over time: totals and a daily series of spend, ROAS, CTR and conversions, optionally filtered by channel or campaign. Dates are optional: without them it covers the last 30 full days (ending yesterday, UTC). Set include_coverage=true when results are empty or the user asks whether data exists. Intents: how did my ads do, spend last 30 days, ROAS trend, daily metrics, do we have data Do not use to rank campaigns, ads or creatives (get_performance_breakdown), for change versus the prior period (get_performance_movers), or to list what is running (list_live_ads). Side effects: none. Retry: safe. Errors: empty result → retry once with include_coverage=true; brand_required → call list_brands and retry with brand_id.

get_performance_summary

Use this when the user asks to see their product catalogue or one product's details. Omit product_id to list; pass product_id (example: "17") for one product. Intents: my products, product list, catalogue, product details Do not use before launching or generating: a product URL, name or image already in the chat is enough, so this lookup is not needed. Not for adding products (create_product / import_product_from_url) or changing them (update_product). Side effects: none. Retry: safe. Errors: brand_required → call list_brands and retry with brand_id.

get_products

Use this when: AI creative / media recommendations for a brand based on recent paid-media performance. Requires ``brand_id``. ``start_date`` and ``end_date`` are inclusive ``YYYY-MM-DD``; omit both for the last 30 days. A longer window is capped at 30 days. May return ``status=timeout``; narrow the dates and do not retry the same call in one turn. Intents: which ads should I make more of, scale winners, recommendations, creative advice, paid media insights Do not use to create or change anything. Side effects: none. Retry: safe.

get_recommendations

Use this when the user asks about a domain's SEO standing: domain rating, backlinks or organic traffic. Uses whichever of Ahrefs and Semrush is connected. Example: domain "northline.example". Intents: domain rating, DR, backlinks, organic traffic, SEO overview Do not use for keyword data (get_keyword_insights). Side effects: none. Retry: safe. Errors: every provider failed → list_connections, then get_connect_link.

get_seo_domain_overview

Use this when you need a video's duration, resolution or file size, for example before cloning it. Reads the file only. Example: video_url "https://cdn.example.com/a.mp4". Intents: how long is this video, video size, video resolution Do not use to assess cloning (check_clone_video) or to render (clone_video_ad). Side effects: none. Retry: safe.

get_video_metadata

Use this when: Confirm this Omneky MCP connector is reachable. Returns ok status, server identity, and code_version_id (deploy fingerprint, same as GET /status). Not a source of advertising data. Not for application deployment or DNS records. Intents: omneky health, connector status, ping, reachability Do not use to create or change anything. Side effects: none. Retry: safe.

health_check

Use this when the user gives a product page URL and wants that product in the catalogue. Call with the url (example: "https://northline.example/sandals"): it checks the page is a single product (status=not_a_product_page for a listing or category page: ask for one product URL), then scrapes name, description and images into an unsaved draft (its product_id is the draft_id). Show it, then save it with save_imported_product. Intents: import this product page, add product from link, scrape my product Do not use to save the draft (save_imported_product), for typed details with no URL (create_product), or to change a saved product (update_product). Side effects: creates an unsaved draft only; nothing is added to the catalogue. Retry: safe (a new draft). Errors: a scrape failure → ask the user for the details and use create_product.

import_product_from_url

Use this when the user wants to launch paid Google Ads ads for the signed-in brand: creates the campaign, ad set (ad_group) and ad, or adds to an existing campaign / ad set via ``campaign_spec.id`` / ``ad_group_spec.id``. Pick ``objective`` (performance_max, demand_gen). ``campaign_spec.status_on_launch`` decides whether the new campaign goes live (ACTIVE / ENABLED) or is created paused (PAUSED / DISABLED); set it from what the user asked. The server applies no default, so when it is omitted the ad network's own default applies. Spend is the budget you pass; state it and proceed. performance_max (PMax / Shopping) needs ``ad_group_spec.link_url``, 3+ headlines, 2+ descriptions, square_marketing_images and logo_image. demand_gen (YouTube / Discover / Gmail) needs ``ad_group_spec.targeting_fragments`` from ``search_targeting``. Not for drafts, creatives (generate_image_ad), reporting (get_performance_breakdown), or pausing / budget / targeting changes on live entities (set_ad_status, set_ad_budget, update_ad_targeting). Example: objective 'performance_max' with campaign_spec, ad_group_spec and ad_specs[].media_url. On a channel_not_connected error call get_connect_link; on a 400 fix the field it names and retry once. A creative URL and product URL already in the chat are enough: no catalogue (get_products) or requirements lookup is needed unless an id is missing. Intents: Google Ads, Performance Max, PMax, Demand Gen, YouTube ads Do not use for drafts, creatives, or reporting. Side effects: changes live ad accounts and can spend ad budget. Retry: not idempotent; check list_live_ads first.

launch_google_ad

Use this when the user wants to launch paid LinkedIn ads for the signed-in brand: creates the campaign, ad set (ad_group) and ad, or adds to an existing campaign / ad set via ``campaign_spec.id`` / ``ad_group_spec.id``. Pick ``objective`` (brand_awareness, website_visits, engagement, conversions). ``campaign_spec.status_on_launch`` decides whether the new campaign goes live (ACTIVE / ENABLED) or is created paused (PAUSED / DISABLED); set it from what the user asked. The server applies no default, so when it is omitted the ad network's own default applies. Spend is the budget you pass; state it and proceed. ``start_date`` is required when creating a new campaign group. Location targeting from ``search_targeting`` must include a ``urn:li:adTargetingFacet:locations`` entry or the API returns 400. Targeting goes in ``ad_group_spec.targeting_criteria``. Not for drafts, creatives (generate_image_ad), reporting (get_performance_breakdown), or pausing / budget / targeting changes on live entities (set_ad_status, set_ad_budget, update_ad_targeting). Example: objective 'brand_awareness' with campaign_spec, ad_group_spec and ad_specs[].media_url. On a channel_not_connected error call get_connect_link; on a 400 fix the field it names and retry once. A creative URL and product URL already in the chat are enough: no catalogue (get_products) or requirements lookup is needed unless an id is missing. Intents: LinkedIn ads, B2B ads, sponsored content Do not use for drafts, creatives, or reporting. Side effects: changes live ad accounts and can spend ad budget. Retry: not idempotent; check list_live_ads first.

launch_linkedin_ad

Use this when the user wants to launch paid Meta (Facebook / Instagram) ads for the signed-in brand: creates the campaign, ad set (ad_group) and ad, or adds to an existing campaign / ad set via ``campaign_spec.id`` / ``ad_group_spec.id``. Pick ``objective`` (sales, leads, traffic, awareness, video_views). ``campaign_spec.status_on_launch`` decides whether the new campaign goes live (ACTIVE / ENABLED) or is created paused (PAUSED / DISABLED); set it from what the user asked. The server applies no default, so when it is omitted the ad network's own default applies. Spend is the budget you pass; state it and proceed. Set ``account='omneky_managed'`` when the brand has no connected Meta account: it runs on Omneky's prepaid ad account and page with an Omneky-hosted landing page (objectives traffic, video_views, awareness only; do not pass a landing-page URL). If the prepaid balance is short it returns ``status=payment_required`` and creates nothing; the user adds funds on omneky.com, then retry or check ``get_account``. sales = purchases / ROAS; leads = lead forms (set ``lead_gen_form_id``); traffic = link clicks; awareness = reach. Targeting goes in ``ad_group_spec.targeting``. Not for drafts, creatives (generate_image_ad), reporting (get_performance_breakdown), or pausing / budget / targeting changes on live entities (set_ad_status, set_ad_budget, update_ad_targeting). Example: objective 'sales' with campaign_spec, ad_group_spec and ad_specs[].media_url. On a channel_not_connected error call get_connect_link; on a 400 fix the field it names and retry once. A creative URL and product URL already in the chat are enough: no catalogue (get_products) or requirements lookup is needed unless an id is missing. Intents: Meta ads, Facebook ads, Instagram ads, launch campaign, paid social Do not use for drafts, creatives, or reporting. Side effects: changes live ad accounts and can spend ad budget. Retry: not idempotent; check list_live_ads first.

launch_meta_ad

Use this when the user wants to launch paid OpenAI Ads (ads in ChatGPT) ads for the signed-in brand: creates the campaign, ad set (ad_group) and ad, or adds to an existing campaign / ad set via ``campaign_spec.id`` / ``ad_group_spec.id``. Pick ``objective`` (clicks, impressions). ``campaign_spec.status_on_launch`` decides whether the new campaign goes live (ACTIVE / ENABLED) or is created paused (PAUSED / DISABLED); set it from what the user asked. The server applies no default, so when it is omitted the ad network's own default applies. Spend is the budget you pass; state it and proceed. Set ``account='omneky_managed'`` when the brand has no connected OpenAI Ads account: it runs on Omneky's prepaid OpenAI Ads account with an Omneky-hosted landing page; pass the brand website as ``ad_specs[].destination_url``. If the prepaid balance is short it returns ``status=payment_required`` and creates nothing; the user adds funds on omneky.com, then retry or check ``get_account``. Geo targeting is optional — omit ``campaign_spec.targeting`` to reach all eligible locations. To restrict geography, call ``search_targeting`` and paste a result's ``campaign_spec_fragment`` into ``campaign_spec.targeting``. New campaigns reject a daily budget below $25. Image ``chat_card`` only. Title 3–50 characters; body ≤100; ``destination_url`` required. New ad groups need ``max_bid_dollars``. Not for drafts, creatives (generate_image_ad), reporting (get_performance_breakdown), or pausing / budget / targeting changes on live entities (set_ad_status, set_ad_budget, update_ad_targeting). Example: objective 'clicks' with campaign_spec, ad_group_spec and ad_specs[].media_url. On a channel_not_connected error call get_connect_link; on a 400 fix the field it names and retry once. A creative URL and product URL already in the chat are enough: no catalogue (get_products) or requirements lookup is needed unless an id is missing. Intents: OpenAI Ads, ChatGPT ads, chat_card, sponsored answers Do not use for drafts, creatives, or reporting. Side effects: changes live ad accounts and can spend ad budget. Retry: not idempotent; check list_live_ads first.

launch_openai_ad

Use this when the user wants to launch paid Pinterest ads for the signed-in brand: creates the campaign, ad set (ad_group) and ad, or adds to an existing campaign / ad set via ``campaign_spec.id`` / ``ad_group_spec.id``. Pick ``objective`` (awareness, traffic, sales, leads, video_views). ``campaign_spec.status_on_launch`` decides whether the new campaign goes live (ACTIVE / ENABLED) or is created paused (PAUSED / DISABLED); set it from what the user asked. The server applies no default, so when it is omitted the ad network's own default applies. Spend is the budget you pass; state it and proceed. Pin title max 100 characters. Targeting goes in ``ad_group_spec.targeting``. Not for drafts, creatives (generate_image_ad), reporting (get_performance_breakdown), or pausing / budget / targeting changes on live entities (set_ad_status, set_ad_budget, update_ad_targeting). Example: objective 'awareness' with campaign_spec, ad_group_spec and ad_specs[].media_url. On a channel_not_connected error call get_connect_link; on a 400 fix the field it names and retry once. A creative URL and product URL already in the chat are enough: no catalogue (get_products) or requirements lookup is needed unless an id is missing. Intents: Pinterest ads, promoted pins, shopping pins Do not use for drafts, creatives, or reporting. Side effects: changes live ad accounts and can spend ad budget. Retry: not idempotent; check list_live_ads first.

launch_pinterest_ad

Use this when the user wants to launch paid Reddit ads for the signed-in brand: creates the campaign, ad set (ad_group) and ad, or adds to an existing campaign / ad set via ``campaign_spec.id`` / ``ad_group_spec.id``. Pick ``objective`` (awareness, traffic, conversions, leads, video_views). ``campaign_spec.status_on_launch`` decides whether the new campaign goes live (ACTIVE / ENABLED) or is created paused (PAUSED / DISABLED); set it from what the user asked. The server applies no default, so when it is omitted the ad network's own default applies. Spend is the budget you pass; state it and proceed. Reddit ``bid_value`` is microcurrency (dollars × 1,000,000); $5/day is ``5000000``. Communities, interests and geolocations go in ``ad_group_spec.targeting``. Not for drafts, creatives (generate_image_ad), reporting (get_performance_breakdown), or pausing / budget / targeting changes on live entities (set_ad_status, set_ad_budget, update_ad_targeting). Example: objective 'awareness' with campaign_spec, ad_group_spec and ad_specs[].media_url. On a channel_not_connected error call get_connect_link; on a 400 fix the field it names and retry once. A creative URL and product URL already in the chat are enough: no catalogue (get_products) or requirements lookup is needed unless an id is missing. Intents: Reddit ads, subreddit targeting, community ads Do not use for drafts, creatives, or reporting. Side effects: changes live ad accounts and can spend ad budget. Retry: not idempotent; check list_live_ads first.

launch_reddit_ad

Use this when the user wants to launch paid TikTok ads for the signed-in brand: creates the campaign, ad set (ad_group) and ad, or adds to an existing campaign / ad set via ``campaign_spec.id`` / ``ad_group_spec.id``. Pick ``objective`` (traffic, conversions, leads, video_views). ``campaign_spec.status_on_launch`` decides whether the new campaign goes live (ACTIVE / ENABLED) or is created paused (PAUSED / DISABLED); set it from what the user asked. The server applies no default, so when it is omitted the ad network's own default applies. Spend is the budget you pass; state it and proceed. ``ad_group_spec.location_ids`` is required: get them from ``search_targeting`` first or TikTok returns 400. ``ad_group_spec.name`` maps to ``adgroup_name``. Not for drafts, creatives (generate_image_ad), reporting (get_performance_breakdown), or pausing / budget / targeting changes on live entities (set_ad_status, set_ad_budget, update_ad_targeting). Example: objective 'traffic' with campaign_spec, ad_group_spec and ad_specs[].media_url. On a channel_not_connected error call get_connect_link; on a 400 fix the field it names and retry once. A creative URL and product URL already in the chat are enough: no catalogue (get_products) or requirements lookup is needed unless an id is missing. Intents: TikTok ads, launch TikTok campaign, short video ads Do not use for drafts, creatives, or reporting. Side effects: changes live ad accounts and can spend ad budget. Retry: not idempotent; check list_live_ads first.

launch_tiktok_ad

Use this when the user wants to launch paid X (Twitter) ads for the signed-in brand: creates the campaign, ad set (ad_group) and ad, or adds to an existing campaign / ad set via ``campaign_spec.id`` / ``ad_group_spec.id``. Pick ``objective`` (awareness, traffic, engagements, followers, video_views). ``campaign_spec.status_on_launch`` decides whether the new campaign goes live (ACTIVE / ENABLED) or is created paused (PAUSED / DISABLED); set it from what the user asked. The server applies no default, so when it is omitted the ad network's own default applies. Spend is the budget you pass; state it and proceed. Check ``list_connections(channel='twitter')`` first. Targeting goes in ``ad_group_spec.targeting``. Not for drafts, creatives (generate_image_ad), reporting (get_performance_breakdown), or pausing / budget / targeting changes on live entities (set_ad_status, set_ad_budget, update_ad_targeting). Example: objective 'awareness' with campaign_spec, ad_group_spec and ad_specs[].media_url. On a channel_not_connected error call get_connect_link; on a 400 fix the field it names and retry once. A creative URL and product URL already in the chat are enough: no catalogue (get_products) or requirements lookup is needed unless an id is missing. Intents: X ads, Twitter ads, promoted posts, followers campaign Do not use for drafts, creatives, or reporting. Side effects: changes live ad accounts and can spend ad budget. Retry: not idempotent; check list_live_ads first.

launch_x_ad

Use this when the user has chosen an ad account (and Facebook page on meta) from list_ad_accounts and wants the brand to use it. Example: channel "meta", channel_account_id "act_998877". Intents: use this ad account, link ad account, pick this Facebook page Do not use to list the accounts (list_ad_accounts) or to check connection status (list_connections). Side effects: changes the brand's linked ad account. Retry: safe. Errors: channel_not_connected → call get_connect_link for that channel; brand_required → call list_brands and retry with brand_id.

link_ad_account

Use this when after OAuth the user must choose which ad account (and Facebook page) the brand uses. Lists the ad accounts the connection can use (and Facebook pages on meta). OpenAI Ads uses an API-key connection and does not support this OAuth account list; check it with list_connections instead. Example: channel "meta". Intents: which ad accounts, list my ad accounts, Facebook pages Do not use to link the chosen account (link_ad_account) or to check connection status (list_connections). Side effects: none. Retry: safe. Errors: channel_not_connected → call get_connect_link for that channel; brand_required → call list_brands and retry with brand_id.

list_ad_accounts

Use this when the signed-in user needs to pick an advertising brand before a branded ad, product video, catalogue list, or performance question and ``brand_id`` is not already chosen. Returns id, name, and company. Stick to the chosen brand afterwards. Intents: brands, advertiser accounts, brand_id, omneky brands Do not use to create or change anything. Side effects: none. Retry: safe.

list_brands

Use this when the user asks what is connected, or whether one ad channel or data source is connected and usable. Omit connector for all; pass one for a single check (example: connector "tiktok"). Also returns linked ad account ids. Intents: is Meta connected, what's connected, connection status, which ad accounts, is HubSpot connected Do not use to connect something (get_connect_link) or to choose an ad account (link_ad_account). Side effects: none. Retry: safe. Errors: brand_required → call list_brands and retry with brand_id.

list_connections

Use this when the user wants their saved creatives or ad library: generated images and videos they can launch, edit or clone. Intents: my creatives, ad library, saved ads, my generated images and videos Do not use for ads running on a channel (list_live_ads) or performance (get_performance_breakdown). Side effects: none. Retry: safe. Errors: brand_required → call list_brands and retry with brand_id.

list_creatives

Use this when the user wants to see what is running on an ad channel: campaigns, ad groups or ad sets, or ads, with status and budget, or to find an id by name. level campaign (default), ad_group (parent_id = campaign id) or ad (parent_id = ad group id); set name_query to search by name. Example: channel "meta", level "campaign". Intents: my campaigns, live ads, ad sets, what's running, campaign budget, find campaign id Do not use for metrics (get_performance_breakdown) or the saved creative library (list_creatives). Side effects: none. Retry: safe. Errors: channel_not_connected → call get_connect_link for that channel; brand_required → call list_brands and retry with brand_id.

list_live_ads

Use this when the user wants script or story options for a product video before it is rendered. Returns narratives; pass the chosen one to generate_product_video. Example: product_name "Trail Sandal", product_image_urls [image URL]. Intents: video script ideas, story options, video concepts Do not use to render the video (generate_product_video); skip this step when the user just wants the video made. Side effects: saves the narratives for the next step; no credits. Retry: safe.

plan_product_video

Use this when: App-only status check for the image generation widget. Hosts with MCP Apps call this from the iframe. Proxies Central get_generation_status; a terminal status can settle credits. Intents: image generation poll, widget status, job_id Do not use for a simple lookup. Side effects: may start a job, save data, or settle credits. Retry: check status or the list tool before repeating.

poll_image_generation

Use this when: App-only status check for the video generation widget. Hosts with MCP Apps call this from the iframe. Proxies Central get_generation_status; a terminal status can settle credits. Intents: video generation poll, widget status, job_id Do not use for a simple lookup. Side effects: may start a job, save data, or settle credits. Retry: check status or the list tool before repeating.

poll_video_generation