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 and link a self-serve Ads Manager ad account after the user has confirmed the account details. Connector onboarding currently supports business advertiser accounts only; if the user wants an individual account, send them to Ads Manager. Use this only for non-sensitive account setup fields such as business URL, name, country, currency, timezone, and industry. Tell the user before calling that tenant/org ownership, country, currency, timezone, and business account type may not be changeable through the connector later. Do not use this for billing, tax ids, payment methods, or identity verification; send the user to Ads Manager for those steps.
get_ad
ChatGPTGet a single Ads Manager ad by ad id. If the user supplied names, resolve campaign, ad group, and ad ids first with the hierarchical list tools and name filters.
get_ad_account_insights
ChatGPTGet or rank performance insights across an ad account. For top campaigns, ad groups, or ads, set aggregation_level to that entity, use time_granularity='none' to aggregate the whole requested range, request the ranking metric in fields, and sort it descending. For example, top ads by CTR uses aggregation_level='ad', fields including ad.id, ad.name, and ctr, and sort field ctr descending.
get_ad_group
ChatGPTGet a single Ads Manager ad group by ad group id. If the user supplied names, resolve campaign and ad group ids first with list_campaigns(name=...) and list_ad_groups(..., name=...).
get_ad_group_insights
ChatGPTGet performance insights for one ad group, optionally grouped by time, segment, or aggregation level.
get_ad_insights
ChatGPTGet performance insights for one ad, optionally grouped by time, segment, or aggregation level.
get_campaign
ChatGPTGet a single Ads Manager campaign by campaign id. If the user supplied a name, resolve the id first with list_campaigns(name=...).
get_campaign_insights
ChatGPTGet performance insights for one campaign, optionally grouped by time, segment, or aggregation level.
get_conversion_insights
ChatGPTGet attributed conversion totals for Ads Manager campaigns, ad groups, or ads. Use entity_ids matching the requested aggregation_level.
get_identity_verification_status
ChatGPTGet status-only advertiser identity verification state for an Ads Manager ad account. Use this only to check whether Ads Manager still needs verification; the verification form and any legal identity details must stay in Ads Manager.
get_onboarding_status
ChatGPTGet safe self-serve onboarding status for an Ads Manager ad account. This returns setup state and the recommended next action. It returns an Ads Manager link only when account location or identity verification must be resolved there. It does not expose billing, tax, payment, legal identity, or detailed account-integrity review data. Pass the exact account name when its internal id is unavailable; the tool resolves the account before fetching status. Omit both account fields only to auto-select the sole accessible account.
list_ad_accounts
ChatGPTList Ads Manager ad accounts accessible by the signed-in user and resolve the account to use. Every data entry always includes its internal id. Always include each id when presenting account results. Pass ad_account_name when the user named an account. If resolved_ad_account_id is returned, immediately reuse it for the requested read operation; never ask the user to find or transcribe that id. If resolution is ambiguous or not_found, ask the user to choose from the returned account names; if names collide, include returned ids or URLs only to distinguish the options.
list_ad_groups
ChatGPTList ad groups for an Ads Manager ad account using public Sofa pagination and sort parameters. Use campaign_id resolved from list_campaigns when the user scopes to a campaign, or omit it to search across the account. Pass name when the user supplied an ad group name. Use include=['serving_issues'] to return reasons ad groups cannot serve.
list_ads
ChatGPTList ads for an Ads Manager ad account using public Sofa pagination and sort parameters. Use ad_group_id resolved from list_ad_groups when the user scopes to an ad group, or omit it to search across the account. Pass name when the user supplied an ad name. Use include=['serving_issues'] to return reasons ads cannot serve. Use get_ad for details about one resolved ad.
list_campaigns
ChatGPTList campaigns for a single Ads Manager ad account using public Sofa pagination and sort parameters. Pass name when the user supplied a campaign name. Use include=['serving_issues'] to return reasons campaigns cannot serve. Use the returned campaign ids with get_campaign or list_ad_groups.
list_onboarding_tenants
ChatGPTList tenants where the signed-in user can start self-serve Ads Manager onboarding. Use this before creating a new ad account to determine whether the user can create an account in an existing tenant or create a new tenant. Present tenants by name and keep each returned id internal for the subsequent create_self_serve_ad_account call. Do not show or ask the user for a tenant id unless duplicate names or a missing name require it for disambiguation. This does not collect billing, tax, payment, or legal identity details.
set_account_logo
ChatGPTSubmit a replacement logo for brand review on an existing Ads Manager ad account. The current public logo remains active until the submitted logo is approved. This is a substantial, destructive account change and requires platform approval. Before calling, show the user the exact logo and identify the selected account. Pass the file_id token returned by an account-scoped logo upload as favicon_file_id and provide a plain-language description of the approved image for the confirmation surface.
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 image file as an Ads Manager account logo and return an opaque file_id token. For an existing account, use the selected account so the upload is scoped to that account. Omit ad_account_id only when preparing a logo before self-serve account creation. Uploading does not change the active logo; use set_account_logo after showing the exact generated or uploaded image to the user. Do not use this for billing, tax, payment, or identity documents.
upload_account_logo_from_url
ChatGPTUpload an Ads Manager account logo from a public image URL and return an opaque file_id token. For an existing account, use the selected account so the upload is scoped to that account. Omit ad_account_id only when preparing a logo before self-serve account creation. Uploading does not change the active logo; use set_account_logo after showing the exact image to the user. Do not use this for billing, tax, payment, or identity documents.
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.
