create_ad
ChatGPTCreate an ad using only supported public Sofa ad fields exposed by this tool. This is a consequential write; use only after the user approves the selected account and full request body, or when the request is within an explicitly approved bounded automation policy for that account. Resolve the parent ad group id from names where possible. Use upload_image or upload_image_file first when the creative needs an image, then pass its file_id token unchanged as creative.file_id. For chat_card, recommend a title of at most 24 characters and description of at most 48 to reduce placement truncation; the hard limits are 50 and 100. For product_ad_template, keep the title template to at most 30 characters instead. For ad creative images, use a square PNG or JPG that is at least 256 x 256 pixels. Recommend 640 x 640 through 1200 x 1200 pixels, with 1200 x 1200 preferred when available; do not recommend images larger than 1200 x 1200. Prefer status paused unless the user explicitly requested active.
create_ad_group
ChatGPTCreate an ad group using only supported public Sofa ad group fields exposed by this tool. This is a consequential write; use only after the user approves the selected account and full request body, or when the request is within an explicitly approved bounded automation policy for that account. Resolve the parent campaign id from names internally where possible, then read the parent campaign. Match its bidding type: impressions requires billing_event_type='impression', while clicks or conversions requires billing_event_type='click'. Only propose CPC for a new clicks campaign flow. For a manual create, show and confirm the maximum bid; for automation, keep it within the approved policy. State that it uses the account currency without guessing an unavailable currency code. Prefer status paused unless the user explicitly requested active.
create_campaign
ChatGPTCreate a campaign using only supported public Sofa campaign fields exposed by this tool. This is a consequential write; use only after the user approves the selected account and full request body, or when the request is within an explicitly approved bounded automation policy for that account. Resolve ids from names internally where possible. If budget is unspecified, propose a daily 100.00 in the account currency; if the objective is unspecified, propose bidding_type='clicks' for CPC. Show and confirm these recommendations for a manual create, or include them in the approved automation policy, rather than silently applying them. Prefer status paused unless the user explicitly requested active.
create_self_serve_ad_account
ChatGPTCreate one self-serve business ad account after list_onboarding_tenants. Do not use for individual advertisers or agencies creating accounts for clients. Show the Advertising Terms (https://openai.com/policies/advertising-terms/), Privacy Policy (https://openai.com/policies/privacy-policy/), and all fields, then obtain explicit approval. For industry_name, send only one exact canonical value from retail_and_ecommerce, consumer_goods, software_and_technology, education, media_and_entertainment, gaming, financial_services, beauty_and_personal_care, healthcare, travel_and_hospitality, real_estate, automotive, jobs_and_recruiting, local_services, professional_services, politics_and_government, gambling, dating, nonprofit, other; never localize or paraphrase it. Warn that tenant ownership, country, currency, timezone, and advertiser type may not be changeable. Billing, tax, payment, and identity stay in Ads Manager.
get_ad
ChatGPTGet details for one ad whose id is already known. Do not use for discovery, ranking, or performance analysis; resolve names with the hierarchical list tools and use get_ad_insights for metrics.
get_ad_account_insights
ChatGPTAnalyze or rank performance across an entire ad account. Use this for account-wide campaign, ad-group, or ad comparisons, not one resolved resource or conversion totals. For rankings, select the entity aggregation, use time_granularity='none', request the metric, sort it, and set the limit.
get_ad_group
ChatGPTGet details for one ad group whose id is already known. Do not use for discovery, ranking, or performance analysis; resolve names with list tools and use an insights tool for metrics.
get_ad_group_insights
ChatGPTAnalyze performance within one resolved ad group, optionally by time, segment, or child ad. Do not use for account-wide rankings, ad-group discovery, or conversion totals.
get_ad_insights
ChatGPTAnalyze performance for one resolved ad, optionally by time or segment. Do not use for account-wide rankings, ad discovery, or conversion totals.
get_campaign
ChatGPTGet details for one campaign whose id is already known. Do not use for discovery, ranking, or performance analysis; resolve names with list_campaigns and use an insights tool for metrics.
get_campaign_insights
ChatGPTAnalyze performance within one resolved campaign, optionally by time, segment, ad group, or ad. Do not use for account-wide rankings, campaign discovery, or conversion totals.
get_conversion_insights
ChatGPTGet attributed conversion totals for specified campaigns, ad groups, or ads. Use only for conversions, not general performance metrics or resource discovery, and match entity_ids to the requested aggregation_level.
get_identity_verification_status
ChatGPTCheck only advertiser identity-verification status after onboarding status indicates verification is needed. Do not use for other setup, integrity, or delivery issues. The form and all legal identity details stay in Ads Manager.
get_onboarding_status
ChatGPTCheck self-serve account-setup progress and the recommended next action; do not use for campaign delivery or general account details. Pass the exact account name when its id is unknown and follow recommended_next_step. An accessible account can create a paused first campaign while brand review or billing is pending. This returns only safe setup state; billing, tax, payment, legal identity, and detailed integrity data stay in Ads Manager.
list_ad_accounts
ChatGPTDiscover accessible Ads Manager ad accounts or resolve an account name to an id. Use this only when the account id is unknown, not for setup status or performance. Every data entry always includes its internal id; include it when presenting results. Reuse resolved_ad_account_id immediately. Ask the user to choose only when returned names are ambiguous; never ask them to transcribe an id returned by this tool.
list_ad_groups
ChatGPTDiscover ad groups, resolve an ad-group name, or paginate choices. Include a campaign_id when the request targets one campaign; otherwise search the account. Do not use for performance analysis. Request serving_issues only when the user asks about delivery.
list_ads
ChatGPTDiscover ads, resolve an ad name, or paginate choices. Include an ad_group_id when the request targets one ad group; otherwise search the account. Do not use for performance analysis. Request serving_issues only when the user asks about delivery.
list_campaigns
ChatGPTDiscover campaigns, resolve a campaign name, or paginate campaign choices in one account. Set include_performance_metrics=true when the user needs to choose among campaigns so the gated picker shows spend, clicks, and CTR from the last 7 days. Do not use for performance analysis; use an insights tool. Request serving_issues only when the user asks about delivery. Use returned ids with get_campaign or list_ad_groups.
list_conversion_sources
ChatGPTList connected conversion sources and pixel ids for one Ads Manager account.
list_onboarding_tenants
ChatGPTStart self-serve business-account setup by listing eligible tenants. Use only when the user asks to set up Ads Manager, or confirms setup after no accounts are found; never use for an existing account. Present tenants by name and keep ids internal. Then collect business details and a logo, show the Advertising Terms (https://openai.com/policies/advertising-terms/) and Privacy Policy (https://openai.com/policies/privacy-policy/), obtain explicit approval, create the account, and check onboarding status. If the user lacks a logo, offer image generation but use it only after acceptance. A first campaign is optional; billing and identity stay in Ads Manager.
set_account_logo
ChatGPTApply an uploaded replacement logo to one existing account; do not use during new account creation. Before calling, show the exact logo and selected account and get approval. The replacement enters brand review and the current public logo remains active until approval.
update_ad
ChatGPTUpdate an ad by ad id using only supported public Sofa ad fields exposed by this tool. This is a consequential write; use only after the user approves the selected account, target ad, and exact update body. Resolve ad ids from names internally where possible. Use upload_image or upload_image_file first when the creative needs an image, then pass its file_id token unchanged as creative.file_id.
update_ad_group
ChatGPTUpdate an ad group by ad group id using only supported public Sofa ad group fields exposed by this tool. This is a consequential write; use only after the user approves the selected account, target ad group, and exact update body. Resolve ad group ids from names internally where possible.
update_campaign
ChatGPTUpdate a campaign by campaign id using only supported public Sofa campaign fields exposed by this tool. This is a consequential write; use only after the user approves the selected account, target campaign, and exact update body. Resolve campaign ids from names internally where possible.
upload_account_logo_file
ChatGPTUpload a ChatGPT- or Codex-provided file specifically as an account logo and return a file_id. Use a JPEG, PNG, or WebP image no larger than 10 MiB and at least 128 x 128 pixels. A square image is recommended. Before uploading, show the exact image and explain that the approved logo will appear in ads. Use only for self-serve setup or an explicitly requested logo change, not ad creative or identity documents. For an existing account, include ad_account_id; omit it only before account creation. Uploading alone does not change the logo.
upload_account_logo_from_url
ChatGPTUpload a public HTTP(S) image URL specifically as an account logo and return a file_id. Prefer a direct link to the exact image. For an image uploaded in ChatGPT or Codex, use upload_account_logo_file instead; never pass a local path. Use a JPEG, PNG, or WebP image no larger than 10 MiB and at least 128 x 128 pixels. A square image is recommended. Before uploading, show the exact image and explain that the approved logo will appear in ads. Use only for self-serve setup or an explicitly requested logo change, not ad creative or identity documents. For an existing account, include ad_account_id; omit it only before account creation. Uploading alone does not change the logo.
upload_image
ChatGPTUpload an image from a URL through the public Sofa /upload endpoint and return an opaque file_id token. This is a consequential write; use only after the user approves the selected account, image_url, and optional purpose. Pass the returned file_id token unchanged in public ad creative fields that accept file_id. For ad creative images, use a square PNG or JPG that is at least 256 x 256 pixels. Recommend 640 x 640 through 1200 x 1200 pixels, with 1200 x 1200 preferred when available; do not recommend images larger than 1200 x 1200.
upload_image_file
ChatGPTUpload a Codex-provided image file through the public Sofa /upload endpoint and return an opaque file_id token. This is a consequential write; use only after the user approves the selected account, file, and optional purpose. Pass the returned file_id token unchanged in public ad creative fields that accept file_id. For ad creative images, use a square PNG or JPG that is at least 256 x 256 pixels. Recommend 640 x 640 through 1200 x 1200 pixels, with 1200 x 1200 preferred when available; do not recommend images larger than 1200 x 1200.
