Omneky

Edit an existing finished image with a natural-language prompt. Calls Creative Brief synchronously and **returns the edited image URL** when done (often 30–120s). There is **no** ``job_id`` to poll with ``get_generation_status`` — wait for this tool call to finish. ## When to use - Change copy, colors, layout, product placement, or style on an existing ad - Apply a look / font via ``reference_images`` - Not for net-new ads (use ``generate_image_ad``) and not for aspect-ratio canvas changes alone (use ``resize_ad``) ## Required inputs - ``images`` — 1+ HTTPS URLs of the source image(s) - ``prompt`` — concrete edit instruction ## Optional inputs - ``brand_id``, ``job_id``, ``mask``, ``reference_images``, ``size``, ``model_name`` ## Returns ``presigned_url`` on success. Present the image to the user; do not describe it only as a URL. This is a paid edit (**5 credits**) settled when the edit succeeds. If the account is short on credits the tool returns ``credit_insufficient`` and does **not** run the edit. ## Intent keywords edit ad, restyle creative, change copy on ad, retouch image, paid-media edit

edit_image

Full catalogue record for one product: name, description, images, and URL. Ground a product-specific ad or video in this data. ## When to use - Need imagery and copy for a known ``product_id`` ## When not to use - Not for listing every product (use ``list_brand_products``) ## Intent keywords product details, product images, catalogue item, SKU

fetch_product_details

Fetch candidate multi-scene video narratives and scripts for a product. Calls Creative Brief's narratives endpoint and returns a list of story options (narrative, script, segments, music / hook direction). This can take up to ~120s — allow a long tool timeout and do **not** treat a slow response as a failure. ## When to use - Before ``generate_product_video``, when you need the user (or you) to pick a story beat for a short product commercial - After you already know ``product_name`` and 1–3 ``product_image_urls`` ## Required inputs - ``brand_id`` - ``product_name`` - ``product_image_urls`` — 1 to 3 HTTPS image URLs of the product (prefer user-selected imagery) ## Optional inputs - ``product_description``, ``product_type`` — improves narrative quality when known ## Agent flow 1. Confirm the creative is for a **specific product** (this tool is product-centric). If the user wants a brand-general ad instead, prefer ``generate_image_ad``. Resolve the product via ``list_brand_products`` / ``get_product_details`` and gather 1–3 product image URLs. 2. Call this tool; present the returned narratives clearly (title / hook / short summary) and ask the user to pick one — or pick with explicit user permission. 3. Pass the chosen narrative's fields into ``generate_product_video``. 4. Do **not** auto-trigger video generation in the same turn unless the user already chose a narrative. Returns ``{"narratives": [...], "error": null}`` on success. ## Intent keywords product video script, narrative options, multi-scene story, commercial beats

fetch_product_video_narratives

App-only Range-GET chunk for widget blob: autoplay assembly. Not for the model. Used when poll cannot inline a full ``data:video`` (size/timeout). Claude's media-src allows ``blob:`` (KB-0038).

fetch_video_chunk

Commit a scraped product draft into the catalogue with the chosen fields and images. Not ``upsert_brand_product``. ## When to use - A scrape draft is ready to save (fields and selected images chosen) ## When not to use - Not for a hand-built product (use ``create_product`` / ``upsert_brand_product``) ## Intent keywords finalize scrape, save catalogue draft, product import

finalize_scraped_product

Queue a new static image ad for the signed-in user's brand. Starts an async Creative Brief render and returns a ``job_id`` quickly — it does **not** wait for the finished image. ## Host widget (preferred) This tool declares an MCP Apps progress/preview UI. When the host opens that widget, do **not** ask the user to "check back", and do **not** call ``get_generation_status`` in a loop — the widget polls and shows the image. ## Text-only hosts (no widget) Share the ``job_id``, stop the turn, and on the user's follow-up call ``get_generation_status(job_id, kind="image")`` **once**. When the job is complete this returns the finished image **inline as an image** (plus a link) — just present it; do not describe it as a URL. Follow ``next_action``. Do **not** poll in the same turn. ## When to use - Net-new product / lifestyle / campaign image ads - Redesigns or concept variants grounded in brand + product context - Not for editing an existing finished ad (use ``edit_image``) and not for video (use ``generate_product_video``) ## Required inputs (typical) - ``brand_id``, ``brand_name``, ``company_id``, ``user_id`` — resolve via ``list_brands`` / ``get_brand_details`` / ``get_current_user`` - ``ad_concept`` — the full creative prompt (product, offer, visual direction, copy cues). This is the prompt field; do not invent a separate ``prompt`` arg - ``gpt_ad_gen_id`` — unique job key: ``<short-slug>-<uuid4>``. Never reuse across variants or retries ## Recommended optional inputs - ``aspect_ratio`` — one of ``1:1`` (default / feed), ``4:5``, ``9:16`` (Stories/Reels/TikTok), ``16:9`` - ``user_assets`` / product imagery when the brief needs a specific product shot - ``headline`` / ``subheadline`` / ``cta`` when the user already chose copy ## Agent flow (public connector) 1. Ask whether the ad is for a **specific product** or the **brand in general**. If product-specific, resolve via ``list_brand_products`` / ``get_product_details`` (or ask which product) and gather product imagery. If brand-general, use ``get_brand_details`` identity/assets and skip product selection. 2. Confirm aspect ratio(s) and ad goal with the user if missing. 3. Call this tool once per distinct creative concept (for multiple placements, generate once at a primary ratio, then ``resize_ad`` for each remaining ratio in one parallel tool round). 4. If a generation widget appears, briefly confirm the job is running and let the widget finish — do not narrate a manual status loop. 5. If no widget appears, share ``job_id`` and wait for the user to ask for status. This is a paid render: it deducts **5 credits** when the job is submitted. If the account is short on credits the tool returns a ``credit_insufficient`` result and does **not** start the render — relay that to the user and do not retry until they top up. Confirm intent before calling. ## Intent keywords image ad, static ad, paid-media creative, Meta ad creative, Facebook ad, Instagram ad, Google image ad, TikTok static, catalogue creative, product shot

generate_image_ad

Queue a multi-scene product video commercial for the signed-in brand. Starts an async Creative Brief multi-scene render and returns a ``job_id`` quickly — it does **not** wait for the finished clip (typical wall clock 3–7 minutes). ## Host widget (preferred) This tool declares an MCP Apps progress/preview UI. When the host opens that widget, do **not** ask the user to "check back", and do **not** call ``get_generation_status`` in a loop — the widget polls and shows the video (or an open link if in-iframe playback is blocked). ## Text-only hosts (no widget) Share the ``job_id``, stop the turn, and on the user's follow-up call ``get_generation_status(job_id, kind="video")`` **once**. Deliver ``assets.url`` / ``assets.video_url`` when complete. Follow ``next_action``. Do **not** poll in the same turn. ## When to use - Short product commercials / multi-beat narrative videos - After ``fetch_product_video_narratives`` when a narrative has been selected - Prefer this over single-shot product motion when the story needs multiple scenes or is longer than ~8 seconds ## Prerequisites 1. Product name + 1–3 product image URLs 2. A chosen narrative (from ``fetch_product_video_narratives``) including narrative / script / segments / music_direction / hook_strategy as required by the tool schema 3. ``brand_id``, ``company_id``, and a fresh ``job_id`` (``<slug>-<uuid4>``) ## Orientation Derive from the brief's aspect ratio: - ``9:16`` → ``portrait`` - ``16:9`` → ``landscape`` - ``1:1`` → ``square`` ## Agent flow (public connector) 1. Confirm product vs brand-general intent; for brand-general creatives use ``generate_image_ad`` instead. Gather product + images; confirm aspect / duration / creative prompt. 2. ``fetch_product_video_narratives`` → present options → wait for selection. 3. Call this tool with the selected narrative + imagery + orientation. 4. If a generation widget appears, briefly confirm the job is running and let the widget finish — do not narrate a manual status loop. 5. If no widget appears, share ``job_id`` and wait for the user to ask for status; then ``get_generation_status`` **once** and follow ``next_action``. This is a paid render: it deducts **30 credits** when the job is submitted. If the account is short on credits the tool returns a ``credit_insufficient`` result and does **not** start the render — relay that to the user and do not retry until they top up. ## Intent keywords product video, multi-scene commercial, TikTok video ad, Reels video, paid-media video

generate_product_video

Custom conversion / property definitions available on the brand for launch or reporting. Also listed as ``get_custom_properties``; both names invoke the same tool. ## When to use - Need a custom conversion event or property before a launch ## When not to use - Not performance metrics ## Intent keywords custom conversions, conversion events, pixel events

get_ad_custom_properties

List ad sets / ad groups under a campaign (targeting, budget, status). Typically scoped with ``campaign_id`` (and ``ad_group_ids`` when known). An unscoped brand-wide list may return ``status=timeout``. ## When to use - Inspect ad sets before adding ads or changing targeting/budget ## When not to use - Not for creating an ad set (use ``launch_*`` with ``campaign_spec``) ## Intent keywords ad sets, ad groups, Meta ad set, Facebook ad set, campaign structure

get_ad_groups

List ads in an ad set (creative, status, destination). ## When to use - Inspect live ads before pause, delete, or a new launch into the same set ## When not to use - Not for creating an ad (use ``launch_*`` with ``ad_group_spec``) ## Intent keywords ads, creatives in flight, Meta ads, Facebook ads, ad objects

get_ads

Company plan, Stripe customer/subscription flags, and prepaid credit snapshot for the signed-in account. Account-level — not brand ROAS or campaign spend. Does not start a plan change, open the Customer Portal, or start a prepaid-credit top-up Checkout (that is ``create_credit_topup_checkout``). ## When to use - User asks which plan they are on, whether billing is set up, or remaining credits before a plan change ## When not to use - Not paid-media performance - Not a live Stripe price catalog (this tool has no dollar amounts) ## Intent keywords plan, subscription, billing, Stripe, account owner

get_billing_summary

Fetch one Omneky brand record by id (name, company, basic fields). ## When to use - Look up a known ``brand_id`` before analytics or launches ## When not to use - Not for logo, colors, copy, or creative assets (use ``get_brand_details``) - Not for listing every brand (use ``list_brands``) ## Intent keywords brand record, brand_id, advertiser

get_brand

Fetch brand identity used for ads: logo, colors, copy, company_id, and creative assets. ## When to use - Need brand look-and-feel for a launch or creative brief - Need ``company_id`` or brand assets after ``list_brands`` ## When not to use - Not for product SKUs (use ``list_brand_products``) - Not for ROAS / CTR / spend (use analytics tools) ## Intent keywords brand book, logo, colors, brand assets, company_id

get_brand_details

Fetch one Omneky brand record by id (name, company, basic fields). Also listed as ``get_brand``; both names invoke the same tool. ## When to use - Look up a known ``brand_id`` before analytics or launches ## When not to use - Not for logo, colors, copy, or creative assets (use ``get_brand_details``) - Not for listing every brand (use ``list_brands``) ## Intent keywords brand record, brand_id, advertiser

get_brand_summary

Name lookup for campaigns and ad groups — useful when matching user language to ids. ## When to use - Resolve a campaign or ad-set name the user said out loud ## When not to use - Not a full entity listing with status/budget (use ``get_campaigns`` / ``get_ad_groups``) ## Intent keywords campaign names, ad set names, name lookup

get_campaign_ad_group_names

List paid-media campaigns for a brand and channel (Meta/Facebook, Google, TikTok, LinkedIn, Reddit, X Ads via ``channel='twitter'``): ids, status, budget. Pinterest has ``get_pinterest_campaigns``. ## When to use - Inspect existing campaigns before launching, pausing, or reporting ## When not to use - Not for creating a campaign (use the matching ``launch_*`` tool) ## Intent keywords campaigns, Meta campaigns, Facebook campaigns, Google campaigns, TikTok, LinkedIn, Reddit, X Ads, Twitter ads, Pinterest

get_campaigns

Current budget / spend snapshot for a paid-media channel on the brand. ## When to use - Check how much is allocated or spent on Meta, Google, TikTok, LinkedIn, or Reddit ## When not to use - Not the historical ROAS/CTR series (use ``get_daily_metrics``) ## Intent keywords budget, spend, channel budget, media spend, Meta, Google, TikTok

get_channel_budget

OAuth / self-connect URL for an ad channel (facebook, google, linkedin, tiktok, reddit, twitter, pinterest). Wire name for X Ads is ``twitter``, never ``x``. After the user finishes consent, ``list_authorized_ad_accounts`` then ``link_ad_channel_account``. ## When to use - Brand is missing a Pinterest, X Ads, or other ad-channel connection and the user wants to link it ## When not to use - Not HubSpot / Semrush / Ahrefs / GSC (those have no OAuth URL on this surface; connect on the brand settings page) - Not OpenAI Ads (use ``connect_openai_ads``; no OAuth URL) - Not Google Drive (use ``get_google_drive_connect_url``) - Not campaign performance ## Intent keywords connect Pinterest, connect X Ads, connect Twitter, OAuth URL, ad account link, self-connect

get_channel_connect_url

Whether the brand's Meta/Facebook, Google, TikTok, LinkedIn, Reddit, Pinterest, or X Ads (``twitter``) ad account is connected and launchable. ## When to use - Before any ``launch_*`` call, to see which paid-media channels are linked ## When not to use - Not campaign performance - Not HubSpot / Semrush / Ahrefs / GSC (use those connectors' status tools) - Pinterest also has ``get_pinterest_connection_status`` (same check) ## Intent keywords ad account connected, Meta Business, Google Ads link, TikTok ads manager, LinkedIn Campaign Manager, Reddit ads, Pinterest ads, X Ads, Twitter ads

get_channel_connection_status

Signed-in company's identity and subscription fields (name, plan type, Stripe customer/subscription flags). Does not include the prepaid credit snapshot. ## When to use - Need company_id / plan fields without the prepaid credit snapshot ## When not to use - Not brand list or brand details ## Intent keywords company, subscription type, account, Stripe customer

get_company

Peek at an existing image or video generation ``job_id``. Does not start a render. Returns status and, when complete, asset URLs plus a ``next_action``. Typical use is a single call per user ask. ## When to use - User has a ``job_id`` from an Omneky image/video generation and asks whether it is ready - No host widget is already polling the job ## When not to use - Not for starting a new image or video (those tools live on the full Omneky connector) - Not a substitute for analytics (ROAS / CTR) ## Intent keywords job status, generation ready, creative job_id, render status

get_generation_status

Return the signed-in Omneky user's identity from the session JWT (``user_id``, email, company). Needed as ``user_id`` on several analytics and creative calls. ## When to use - A later tool needs ``user_id`` (``get_trending``, daily metrics, image ad generation) - The host needs to know who is signed in ## When not to use - Not a substitute for ``list_brands`` or brand performance data ## Intent keywords user id, signed-in user, session identity, omneky account

get_current_user

Custom conversion / property definitions available on the brand for launch or reporting. ## When to use - Need a custom conversion event or property before a launch ## When not to use - Not performance metrics ## Intent keywords custom conversions, conversion events, pixel events

get_custom_properties

Day-by-day paid-media time series for a brand and date range: spend, impressions, clicks, CTR, conversions, ROAS, and related metrics. Use for charts and period totals. ``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, …). ## When to use - User asks how ads performed over time (this week, last month) - Need a chart of spend, ROAS, CTR, CPA, or conversions - Compare daily paid-media performance ## When not to use - Not for a ranked breakdown by campaign/creative/channel (use ``get_dimension_summary``) - Not for what rose or fell vs the prior period (use ``get_trending``) - Not a SQL / warehouse query (there is no ``run_sql_query`` on this surface) - Not a score / lift endpoint ## Intent keywords ROAS, CTR, CPA, CPC, CPM, spend, impressions, clicks, conversions, daily metrics, time series, paid media performance, Meta, Facebook, Google Ads, TikTok, LinkedIn, Reddit

get_daily_metrics

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'. ``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, …). ## When to use - Which creatives, campaigns, or channels have the best ROAS / CTR - Ranked leaderboard of paid-media entities - Breakdown of Meta, Google, TikTok, LinkedIn, or Reddit performance ## When not to use - Not for a day-by-day chart (use ``get_daily_metrics``) - Not for what changed vs last period (use ``get_trending``) - Not a SQL / warehouse query (there is no ``run_sql_query`` on this surface) - Not a score / lift endpoint ## Intent keywords ROAS, CTR, spend, creative breakdown, campaign performance, channel mix, Meta ads, Facebook ads, Google Ads, TikTok ads, LinkedIn ads, Reddit ads, paid media

get_dimension_summary

Whether the brand has a connected Google Search Console account (email / connected_at only — never OAuth tokens). No connect or disconnect tool on this surface (Nexus has no GSC auth-url in V1). Also included in ``list_connector_statuses``. ## When to use - Before listing GSC properties or querying Search Analytics ## When not to use - Not paid-media ROAS (use analytics tools) ## Intent keywords GSC connected, Google Search Console, Search Console connection

get_gsc_connection_status

Google Drive OAuth URL for the brand. The user opens it in the browser; this tool does not exchange the callback code. ## When to use - Brand needs Google Drive connected for assets ## When not to use - Not a status check (use ``get_google_drive_connection_status``) - Not a disconnect (use ``disconnect_google_drive``) ## Intent keywords connect Google Drive, Drive OAuth, brand assets

get_google_drive_connect_url

Whether the brand has connected Google Drive (no tokens). ## When to use - Check Drive before asking the user to connect or after they finish OAuth ## When not to use - Not the OAuth URL (use ``get_google_drive_connect_url``) ## Intent keywords Google Drive connected, brand assets, Drive OAuth

get_google_drive_connection_status

Whether the brand has a connected HubSpot portal (hub / portal id only — never OAuth tokens). No connect or disconnect tool exists on this surface. ## When to use - Before searching HubSpot contacts, companies, or deals ## When not to use - Not paid-media ROAS (use analytics tools) ## Intent keywords HubSpot connected, HubSpot portal, CRM connection

get_hubspot_connection_status

Whether the brand has a connected OpenAI Ads account (account name / last-four only — never the API key). To connect, call ``connect_openai_ads``. This surface does not expose Omneky-managed OpenAI launch tools. ## When to use - Check OpenAI Ads before a connect, or after ``connect_openai_ads`` ## When not to use - Not Meta/Google/TikTok launch preflight (use ``get_channel_connection_status``) ## Intent keywords OpenAI Ads connected, API key last four, ChatGPT ads

get_openai_ads_connection_status

Card on file for the company (brand, last4, expiry only — never the PAN). Does not collect a new card number. ## When to use - Check whether a saved card exists before a plan change ## When not to use - Not a card-PAN collection form ## Intent keywords card on file, last4, payment method, Stripe

get_payment_method_summary

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'. Also listed as ``get_dimension_summary``; both names invoke the same tool. ``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, …). ## When to use - Which creatives, campaigns, or channels have the best ROAS / CTR - Ranked leaderboard of paid-media entities - Breakdown of Meta, Google, TikTok, LinkedIn, or Reddit performance ## When not to use - Not for a day-by-day chart (use ``get_daily_metrics``) - Not for what changed vs last period (use ``get_performance_movers``) - Not a SQL / warehouse query (there is no ``run_sql_query`` on this surface) - Not a score / lift endpoint ## Intent keywords ROAS, CTR, spend, creative breakdown, campaign performance, channel mix, Meta ads, Facebook ads, Google Ads, TikTok ads, LinkedIn ads, Reddit ads, paid media

get_performance_breakdown

What rose or fell versus the prior period for a brand's paid-media metrics (spend, ROAS, CTR, conversions, and similar). Also listed as ``get_trending``; both names invoke the same tool. ``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, …). ## When to use - What is trending up or down in ad performance - Winners and losers vs last week / last period ## When not to use - Not for a full ranked table (use ``get_performance_breakdown``) - Not for a daily time series (use ``get_daily_metrics``) - Not a SQL / warehouse query (there is no ``run_sql_query`` on this surface) - Not a score / lift endpoint ## Intent keywords trending, period-over-period, ROAS change, CTR change, paid media winners, Meta, Facebook, Google, TikTok

get_performance_movers

List Pinterest ad groups. Prefer ``campaign_id``. Same as ``get_ad_groups(channel='pinterest')``. ## When to use - Inspect Pinterest ad groups under a known campaign ## When not to use - Not an unscoped brand-wide list when ``campaign_id`` is known ## Intent keywords Pinterest ad groups, Pinterest ad sets, Pins

get_pinterest_ad_groups

List Pinterest ads (promoted Pins). Same as ``get_ads(channel='pinterest')``. ## When to use - Inspect promoted Pins in a campaign or ad group ## When not to use - Not campaign performance (use analytics tools) ## Intent keywords Pinterest ads, promoted Pins, Pin ads

get_pinterest_ads

List Pinterest campaigns for a brand. Same as ``get_campaigns(channel='pinterest')``. ## When to use - Inspect existing Pinterest campaigns before launch or pause ## When not to use - Not Meta/Google/X Ads (use ``get_campaigns`` with that channel) ## Intent keywords Pinterest campaigns, Pins, paid social

get_pinterest_campaigns

Whether the brand has a connected Pinterest ad account. Same check as ``get_channel_connection_status(channel='pinterest')``. ## When to use - Before listing Pinterest campaigns or calling ``launch_pinterest_*`` ## When not to use - Not campaign performance (use analytics tools) ## Intent keywords Pinterest connected, Pinterest ads account, Pins

get_pinterest_connection_status

Whether the brand has a connected PostHog project (host / project_id only — never API keys). To connect, call ``connect_posthog``. ## When to use - Check PostHog before or after a connect ## When not to use - Not a connect or disconnect (use ``connect_posthog`` / ``disconnect_posthog``) ## Intent keywords PostHog connected, PostHog project, product analytics

get_posthog_connection_status

Full catalogue record for one product: name, description, images, and URL. Ground a product-specific ad or video in this data. Also listed as ``fetch_product_details``; both names invoke the same tool. ## When to use - Need imagery and copy for a known ``product_id`` ## When not to use - Not for listing every product (use ``list_brand_products``) ## Intent keywords product details, product images, catalogue item, SKU

get_product_details

AI creative / media recommendations for a brand based on recent paid-media performance. May return ``status=timeout`` or truncated; a tighter date window is typical. ## When to use - User asks what to try next, which creatives to scale, or recommendations ## When not to use - Not raw metrics (use ``get_dimension_summary`` / ``get_daily_metrics``) - Not a launch or generate-creative action ## Intent keywords recommendations, scale winners, creative advice, paid media insights

get_recommendations