# MCP tool reference > Every tool the Roasby MCP server offers AI assistants for Google Ads, Microsoft Ads and ChatGPT Ads, with its safety hints. These are the tools your AI assistant can call through the Roasby MCP server. **Read-only** tools never change anything. Tools that change your ad accounts follow the [safety model](/docs/safety-model). This list is always up to date. ## How changes work Every tool that changes something has a matching `preview_*` tool. - The preview checks the change without making it and returns a one-time confirmation token. - Your assistant is told to show you the change and ask you to confirm before it passes the token to the change tool. - See [Your assistant previews every change](/docs/safety-model#your-assistant-previews-every-change). When only a person can do something, a tool result lists it in `user_actions`. See [Limitations](/docs/mcp-tools#limitations) below. ### EU political ads declaration While a Google Ads campaign has no EU political ads declaration, the preview of any change in that account lists the campaigns to declare in `user_actions` (`declare_eu_political_ads`). Google Ads refuses changes until then. ## Workspaces Tools act in your current workspace in Roasby. See [Workspaces](/docs/workspaces). - `list_workspaces` lists every workspace you belong to: its ID, your role, `can_change_ads`, its number of ad accounts, and whether it is a demo workspace. - Every tool that works in a workspace takes an optional `workspace_id` to act in another one. Roasby checks that you belong to it on every call. - A confirmation token works only in the workspace of its preview. - `get_current_workspace` shows whether you may change ads in the workspace (`can_change_ads`). - `get_workspace_members` lists the people in the workspace (name, email and role) and the invitations that are still pending, one page at a time. ## Reading your accounts - `list_ad_accounts` lists the ad accounts in the workspace: platform, name, currency, time zone, status, whether it is still connected, its guardrails (with the optional `max_target_cpa_micros` and `min_target_roas_percent`), when Roasby last synced it, when it last read the conversion goals (`conversions_synced_at`), and whether the campaign settings read failed at the last sync (`settings_read_failing`). - `get_performance_summary` summarizes spend, conversion value, ROAS, conversions, clicks and impressions across platforms over the last 7, 30 or 90 complete days, with the period before for comparison, for every account or narrowed to one ad account (`ad_account_id`) or campaign (`campaign_id`), with a row for each day. Amounts are grouped per currency, never converted. - `list_ad_entities` finds the IDs of campaigns, ad groups, ads and keywords. `campaign_id` lists one campaign's ad groups, ads or keywords across its ad groups. An ad group under automated bidding has no `cpc_bid_micros` (the platform's placeholder is no bid you set). - `get_campaign_performance`, `get_search_terms` and `find_wasted_spend` read their results. `get_search_terms` adds `other_terms_cost`: the search campaigns' spend no reported search shows. ### Keyword insight `list_ad_entities` gives each keyword its `insight`: - The Quality Score and its three parts. - The first page, top of page and first position bid estimates, in micros and as money. - `below_first_page_bid`. - Its approval, serving and primary status, with the reasons. - A missing score or estimate comes with `quality_score_gap` or `estimates_gap`: - `not_enough_data` - `automated_bidding` - `not_reported_yet` `max_quality_score` and `below_first_page_bid` narrow the keywords. On other levels, only a null maximum and `false` are taken. ### Policy issues Each ad or keyword the platform disapproved, limited or is still reviewing has a `policy` object: - Its `state`, `review_status` (Google Ads) and `appeal_status` (Microsoft Ads). - Each finding in `issues`, with its `topic`, `category`, `label`, `type`, the `part` it is about and `where`, the `evidence`, the `countries` where it can't show, and `advice`. - The `user_actions` step in the ad platform, where reviews and appeals happen. `policy_issues_only` lists only the ads or keywords with a policy issue: disapproved, limited, or with a finding such as a prohibited headline. ### Impression share `get_campaign_performance`, and `list_ad_entities` with a `period` for campaigns and ad groups, give search campaigns an `impression_share`: - `search`, `lost_to_rank`, `lost_to_budget`, `top` and `absolute_top`. - `lost_to_budget`: Google Ads reports it for campaigns only, so a Google Ads ad group has none. - Each comes with: - a `value` from 0 to 1 - a `bound` (`below_10_percent` or `above_90_percent`) when the platform only reports that - its `clamped_days` - a `limit` (`below`: at most the value, `above`: at least it) - a `label` - Plus `days_with_data` and `missing_days`. ### Recommendations `list_recommendations` lists the changes Roasby suggests, each with the preview tool and arguments that approve it. See [Recommendations](/docs/recommendations). - A `raise_budget` names `preview_update_campaign_budget` with a budget within the guardrails. - When the guardrails leave no raise, it has no arguments, with `blocked_by` and `user_actions`. - `changed_since` while it waits for 14 days at a changed budget. - `preview_archive_recommendation` and `archive_recommendation` dismiss an open recommendation. Nothing changes in the ad account; Roasby just never suggests it again. ### Conversion actions and goals `list_conversion_actions` shows how each ad account tracks conversions. See [Conversions](/docs/conversions). - Every conversion action or Microsoft Ads conversion goal with its `source`, `status`, `category`, `goal`, `primary`, `counted_in_conversions`, `counting`, `attribution`, `shared`, `recording`, `last_received_at` and `recent_conversions` (the last 30 days). A campaign's Google Ads custom goal lists its actions in `custom_goal_conversion_action_ids`. - Per account: `readable`, `synced_at`, `bidding_goals` and `problems`. - `primary_only` and `include_removed` narrow or widen it. - Each account's `campaign_goals` lists the campaigns with goals of their own. `get_campaign_performance` gives each campaign its `conversion_goals`: - `level`, `custom_goal_name`, `bidding_goals` and `problems`. - Its Google Ads `goals` (each `key`, `label` and `biddable`). - Its Microsoft Ads `conversion_action_ids`. ### Alerts and the weekly report - `list_alerts` lists the [anomaly alerts](/docs/alerts): spend spikes, cost per conversion jumps and disapproved ads, each disapproved ad with its `policy`. - `get_weekly_report` gives the [weekly report](/docs/weekly-report) members get by email. ### Reading text assets `list_assets` lists the text assets linked in the workspace: sitelinks, callouts, structured snippets, prices and promotions. See [Assets](/docs/assets). - Each with the Roasby ID of its link (for pausing and enabling it), where it is linked (the whole ad account, a campaign or an ad group), its status and its content. - Whether a pause or enable of it is still being applied. - Narrow it with `ad_account_id`, `campaign_id` (the campaign and its ad groups), `ad_group_id`, `type` or `status`. Removed links are left out unless `include_removed` is true. - ChatGPT Ads has no such assets. ### Keyword research `get_keyword_ideas` and `get_keyword_volumes` ask the ad platform's keyword planner (Google Ads Keyword Planner or Microsoft Ads Ad Insight), in 1 to 10 countries and one language. See [Keyword research](/docs/keyword-research). - `get_keyword_ideas` starts from 1 to 20 seed keywords and/or a web page. - `get_keyword_volumes` reads exactly the keywords given (up to 1,000). Keywords that came back without a result are listed in `missing_keywords`. - Each keyword comes with its average monthly searches and monthly trend over the last 12 months, its competition and a bid estimate in the account currency, the most searched first. - A new request can take a few seconds and then answers with status `running`. The same request within a day is answered from Roasby's cache. ### Syncing Roasby reads from its own copy of your data. `run_ad_account_sync` asks Roasby to refresh one ad account's copy now, instead of waiting for the scheduled sync. - It only reads from the platform and never changes ads. - The sync runs in the background and usually takes a few minutes. `last_synced_at` on the ad account changes when it finishes, and `last_sync_error` is set when it fails. - It also reads the conversion goals again, so a new campaign can get its goals and targets. - It isn't needed after a change made through Roasby: applied changes are in Roasby's copy at once, and after new campaigns, ad groups, keywords, ads or assets Roasby syncs the account by itself a few minutes later (`follow_up_sync_due_at` in `list_ad_accounts`). - Each account can be synced this way only so often: Microsoft Ads and ChatGPT Ads accounts every 5 minutes, Google Ads accounts from once a day to every 15 minutes, by workspace. When it is too soon, or a sync is already on its way, `started` is false and `next_sync_allowed_at` says when. ## Single changes Each of these changes one item, and the change is logged and can be reverted. It is pending until the ad platform applies it. - `preview_pause_entity` and `pause_entity` pause a campaign, ad group, ad, keyword or asset link. - `preview_enable_entity` and `enable_entity` enable (resume) one. Enabling can start spending money, so a campaign above the ad account's max daily budget, or only partly created, is refused. - `preview_update_campaign_budget` and `update_campaign_budget` set a campaign's daily budget, within the ad account's guardrails. - `preview_update_bid` and `update_bid` set the max cost per click of an ad group or keyword, within the guardrails. Only items with `bids_adjustable` true can change: campaigns under automated bidding ignore these bids. - `preview_add_negative_keywords` and `add_negative_keywords` exclude keywords from a campaign or an ad group. Negative keywords it already has are left as they are, and reverting takes away exactly the ones added. See [Search terms](/docs/search-terms). ### Suspended ad accounts An ad account beyond the limit of active ad accounts of the workspace is suspended: read-only history. See [Ad accounts](/docs/ad-accounts). - `preview_activate_ad_account` and `activate_ad_account` make a suspended ad account active again (synced and changeable). Owners and admins only. - When the workspace is at its limit, `replace_ad_account_id` names the active account that becomes read-only in its place. - Nothing is disconnected or deleted, and the swap can be made again the other way. ## Many items at once ### Pause and enable - `preview_pause_entities` and `preview_enable_entities` check many campaigns, ad groups, ads, keywords and asset links of one ad account at once, and return one confirmation token for the items that pass. - `pause_entities` and `enable_entities` change them as one batch. - `list_ad_changes` shows the batch as one entry (`batch_id` lists its items, and `status` narrows them, for example to the failed ones). - `preview_revert_ad_change_batch` and `revert_ad_change_batch` undo it. ### Bulk bids `preview_update_bids` checks the max bids of many ad groups and keywords of one ad account at once, each against the same guardrails as `preview_update_bid`. `update_bids` changes them as one batch. Give them either: - `bids`: an amount per item, or - `entity_ids` (or every keyword of an `ad_group_id` or `campaign_id`, removed ones left out) with one `rule`: - `set` an amount - `change_percent` by a whole percent, rounded toward the current bid - `first_page_cpc` up to `cap_micros` With `limit_to_guardrails`, a bid beyond the max bid change per step or the max bid moves only as far as they allow: - It is marked `limited` (with `limited_by` and `requested_micros`), and `limited_count` says how many. - The preview and the result give a `next_step` (`bids` with the bids asked for, as absolute amounts, and `limit_to_guardrails`) for the bids the max bid change limited, so a later batch converges on them. `first_page_cpc` outcomes: - `no_first_page_estimate`: the keyword has no estimate (why in `detail`). - `first_page_cpc_keywords_only`: ad groups can't use it. - `no_change`: keywords at or above it are left as they are. ## Adding keywords, ad groups and ads See [Editing campaigns](/docs/editing-campaigns). ### New keywords - `preview_add_keywords` checks keywords to add to an existing ad group of a Google Ads or Microsoft Ads search campaign (text, match type, optional bid and final URL), each on its own. - `add_keywords` adds the ones that pass as one batch, every keyword paused. - `preview_enable_entities` enables them when you want. ### Ad groups - `preview_add_ad_groups` checks ad groups to add to an existing Google Ads or Microsoft Ads search campaign: a name, a default bid, and optionally keywords, negative keywords and up to 3 responsive search ads. - Each ad group is checked with all its parts, naming the part that breaks a rule (`detail`). - `add_ad_groups` adds the ones that pass as one batch, every ad group paused with its keywords and ads under it. ### Responsive search ads - `preview_add_responsive_search_ads` checks responsive search ads to add to existing ad groups of Google Ads or Microsoft Ads search campaigns in one ad account, each on its own, naming the part that breaks a rule. - `add_responsive_search_ads` adds the ones that pass as one batch, every ad paused. ### The shape of a new ad Every new ad has the same shape: - A `final_url`. - 3 to 15 `headlines` and 2 to 4 `descriptions`, each an object of `text` and an optional `pinned_position` (headlines 1 to 3, descriptions 1 to 2). - Optional `path1` and `path2`. - For an ad added to an ad group or a new ad group's ad, an optional `final_url_suffix`. Characters of Chinese, Japanese and Korean and emoji count as two toward the limits. ## Text assets `preview_add_assets` checks text assets (sitelinks, callouts, structured snippets, prices and promotions) to add to an ad account, a search campaign or one of its ad groups, or to several campaigns or ad groups of one ad account at once (`campaign_ids` or `ad_group_ids`, every asset to each). See [Assets](/docs/assets). - It names the refused ones with why: too long, too few values or rows, an asset that is there already, a Microsoft Ads campaign or ad group that is not paused, and so on. - On Google Ads each asset is linked paused. Microsoft Ads has no paused links, so there Roasby links only to paused campaigns and ad groups. - `add_assets` adds the ones that pass as one batch. Assets are pending until the ad platform adds them. - Reverting an asset pauses its link, or on Microsoft Ads takes it away; the asset itself stays. - The pause and enable tools (`preview_pause_entities`, `preview_enable_entities` and the single-item ones) also take asset links. ## Creating campaigns `create_search_campaign` (Google Ads and Microsoft Ads) and `create_chat_campaign` (ChatGPT Ads) always create campaigns paused. See [Creating campaigns](/docs/creating-campaigns). A new search campaign is one blueprint: - Its own `negative_keywords` and its `ad_groups`, each shaped like an ad group of `add_ad_groups`. - It is checked as a whole: if any part breaks a rule, nothing is created and the preview names every such part with its path. - Every part counts toward the items of one change, and the campaign must fit 10,000 operations (`campaign_too_large`: create part of its ad groups, then add the rest with `add_ad_groups`). - Roasby takes no file: your assistant reads yours and fills the blueprint. It takes: - Any number of countries, and who sees the ads there (`location_option`). - Search partners. - `languages` on Microsoft Ads. Google Ads matches languages itself, so there they are only noted. - A `final_url_suffix` and a `tracking_url_template`. ## Campaign settings `preview_update_campaign_settings` checks a settings change of one Google Ads or Microsoft Ads search campaign, each section before and after in `details`. `update_campaign_settings` makes it as one change. See [Editing campaigns](/docs/editing-campaigns). ### Sections - `countries`: the whole set. `locations_not_only_countries` refuses it for a campaign that also targets regions, cities or a radius. - `location_option`. - `search_partners`. - `final_url_suffix` and `tracking_url_template`: null clears one. - `ad_schedule`: the whole schedule of `day`, `start`, `end` and `bid_adjustment_percent`. Empty runs all day. Refusals: `too_many_schedule_slots`, `schedule_slots_overlap`. - `device_bid_modifiers`: a percent per device, -100 for no ads. Refusal: `bid_adjustment_out_of_range`. - `ad_rotation`. - `languages`: Microsoft Ads only (`no_language_targeting` on Google Ads). ### Bid adjustments Bid adjustments are checked for each device in each quarter hour that shows ads: - The device multiplier times the hour's multiplier may rise at most the max bid change per step from what that pair had before. - A device or hours that showed no ads count as 0% and get no rise in that step. No schedule is every hour at 0%. - Otherwise the change is refused (`bid_change_too_large`, naming the device and hours). - With `limit_to_guardrails`, it is lowered to the largest step, with a `next_step` (taking a schedule away may wait for it). ### Other refusals and syncing - `no_ad_groups_to_set`: refuses the ad rotation (and Microsoft Ads search partners) for a campaign without synced ad groups. - A section changed in the ad platform since Roasby last read it is not sent. The change log names it in its refusal reason, and Roasby syncs the account again. - `list_ad_entities` gives each search campaign its current `settings` (with the schedule's `time_zone`). `settings_not_synced` means Roasby hasn't read them yet. ## Conversion goals `preview_update_conversion_goals` checks a change of what a Google Ads or Microsoft Ads search campaign bids on. `update_conversion_goals` makes it. See [Bidding and goals](/docs/bidding-and-goals). - `level` `account`: the ad account's goals. - `level` `campaign`, with `goal_keys` (Google Ads goal keys) or `conversion_action_ids` (Microsoft Ads). - Its `details` name each chosen goal that is not recording, and say that the learning period restarts. - Reverting puts back the exact setup before. Goals that record nothing, under bidding toward conversions, are allowed: the preview names each action that is not recording. Refusals: - `conversion_goals_not_synced` - `unknown_conversion_goal` - `no_conversion_goals_chosen` - `goals_not_on_campaign_type` - `account_goals_not_supported`: a Microsoft Ads campaign moving to or from the account's goals. ## Bidding `preview_update_bidding` checks a change of how a Google Ads or Microsoft Ads search campaign bids. `update_bidding` makes it. See [Bidding and goals](/docs/bidding-and-goals). ### What you can change - `campaign_id` with a `strategy`, and `limit_to_guardrails`: - `manual_cpc` - `maximize_clicks` - `maximize_conversions`, with an optional `target_cpa_micros` - `maximize_conversion_value`, with an optional `target_roas_percent` - `target_impression_share`, with `impression_share_location`, `impression_share_percent` and `max_cpc_micros` - Or a Google Ads `ad_group_id` with its own `target_cpa_micros`. Null takes it away. A new one needs a campaign that maximizes conversions with a target CPA and its own strategy. Maximize clicks keeps a max cost per click the campaign has. ### What the preview says Its `details` say that automated bidding sets the bids itself, and describe the learning period, a strategy without a target and the guardrails. A guardrail holds only once a person sets it. Bidding toward conversions that are not recording, or toward conversion value with none seen, is allowed with a warning line. - `target_above_max_bid`: a ceiling above the max bid. - `target_above_max_target_cpa`: a target CPA above the account's max target CPA. - `target_below_min_target_roas`: a target ROAS below the account's min target ROAS. - `target_change_too_large`: measured from the most recent target Roasby set or took away when the campaign has none now. With `limit_to_guardrails`, a `bidding_next_step`. - `impression_share_incomplete`: without a location, share or ceiling. ### Refusals - `bidding_not_revertible`: bidding Roasby could not put back. - `bidding_not_synced`: unread bidding. - `ad_group_target_cpa_not_supported`: ad group targets on Microsoft Ads, or without a campaign target CPA. - `target_removal_not_supported`: on Microsoft Ads, a target CPA or ROAS added to or taken from a campaign that keeps its strategy. - `impression_share_not_supported`: target impression share on Microsoft Ads. ### Reading and reverting bidding - `list_ad_entities` gives each campaign its `bidding` (`strategy`, targets, `portfolio`, `changeable`, `label`) and `has_pending_bidding_change`, and each ad group its `target_cpa_micros`. - An ad group's pending target CPA shows as its `has_pending_bid_change`. - While bidding is automated, bid changes are refused. - Reverting restores the exact bidding before, except a Microsoft Ads max cost per click after a strategy switch: Microsoft doesn't take it again, so the revert comes back without it (the preview says so). - Your assistant's revert keeps the guardrails and the max bid change per step (`revert_past_guardrails`). You can revert on the **Change log** page, which restores the exact earlier target. ## Ad text `preview_update_ads` checks edits of the text of Google Ads and Microsoft Ads responsive search ads in place. `update_ads` makes the edits as one batch. See [Editing campaigns](/docs/editing-campaigns). ### Two ways to edit - `ads`, each with its `ad_id` and only the parts that change: - `headlines` or `descriptions`, each list whole with its pins - `path1`, `path2` (null takes one away) - `final_url` - A literal find and replace: `find`, `replace`, and the scope: `ad_account_id`, `campaign_id`, `ad_group_id` or `ad_ids` (a campaign, ad group or ads need no `ad_account_id`), `fields` (`headlines`, `descriptions`, `paths`, `final_url`) and `match_case`. Ads without a match, and edits that change nothing, are left out. ### Checks - Each new text passes the rules of every new ad. None may be empty (`empty_ad_text`). - An ad that breaks one is refused on its own, with `detail`. - Each item has `ad_text` with the whole text `before` and `after`, and each part's `changes`. - Only responsive search ads whose text Roasby read can be edited (`ad_type_not_editable`, `ad_text_not_synced`). - `list_ad_entities` gives each ad its `responsive_search_ad` text, `editable` and `has_pending_text_change`. ### After the edit - Each ad keeps its status, ID and history, and the ad platform reviews its new text again. - An ad changed in the ad platform since Roasby last read it is not sent. - Reverting writes the old text back. ## Keywords `preview_update_keywords` checks changes of Google Ads and Microsoft Ads keywords: `keywords`, each with its `keyword_id` and only what changes (`text`, `match_type`, `final_url`; null or empty takes the keyword's own final URL away). `update_keywords` makes them as one batch. See [Editing campaigns](/docs/editing-campaigns). ### In place or replace - A final URL, and a match type on Microsoft Ads, change in place. - A new text, and a new match type on Google Ads, are a replace: - The new keyword is added paused, with the old one's own bid and final URL. - The old one is paused, never removed. - So the keyword shows no ads until the new one is enabled. - `update_keywords`'s `keyword_next_step` says how to enable the new keywords once it is applied. `list_ad_changes` gives each as `replacement_id`, for `preview_enable_entities`. - Reverting a replace pauses the new keyword and gives the old one its status back. ### What each item says - `keyword_change`: `mode` (`in_place`, `replace` or `restore`), `replace`, and the keyword `before` and `after`. - `keyword_exists`: names the keyword the ad group already has, in `detail`. - `keyword_not_synced`: Roasby hasn't read the keyword's final URL yet. - `list_ad_entities` gives each keyword its own `final_url`, `editable` and `has_pending_keyword_change`. ## The change log and reverts `list_ad_changes` lists the change log of the workspace, newest first. See [Change log](/docs/change-log). - Every change made to its ads through Roasby (pauses and enables, daily budgets, bids and bidding, campaign settings, conversion goals, ad text, keywords, negative keywords, assets, and new campaigns, ad groups, ads and keywords), by a person, an AI assistant or the system, with the values before and after (budgets and bids in micros of the account currency). - Whether it is pending, applied (`partly_applied` when the platform refused part of it, with those parts in the reason) or failed (with the reason), and whether it was reverted. - A batch of changes confirmed together is one entry; `batch_id` lists that batch's items instead. `ad_account_id` narrows it to one ad account, `campaign_id` to one campaign (with everything in it and the change that created it), and `from` and `to` to those days (UTC). - `preview_revert_ad_change` and `revert_ad_change` revert one applied change. `preview_revert_ad_change_batch` and `revert_ad_change_batch` revert a batch, as a new batch. - A revert is itself a logged change, held to the same guardrails, and pending until the ad platform applies it. ## Support and docs - `preview_create_support_request` prepares a message to the Roasby support team (help with Roasby, billing, privacy or data requests, or an abuse report) without sending anything. - `create_support_request` sends it and returns a reference to quote in follow-ups. The team replies by email to your account address within 2 business days. It is limited to a few messages per hour, shared with the contact form. - `search_docs` searches the Roasby documentation and returns the best matching pages with a short summary and their slugs. - `get_doc` returns one documentation page as Markdown, by its slug. ## Read tools These tools only read: they never change your ad accounts. ### `get_current_workspace` **Get current workspace.** Returns the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names): its Roasby ID, name, URL slug, whether it is their personal workspace or a demo workspace (sample data, nothing is written to an ad platform), their role in it, whether they may change its ads (pause, enable, budgets, bids, reverts): owners and admins can, members only when the workspace allows it, and the max budget and bid change per step that newly connected ad accounts start with. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `list_workspaces` **List workspaces.** Lists the Roasby workspaces the connected user belongs to, by name: each one's Roasby ID (the workspace_id other tools take), name, the user's role, whether it is the user's current workspace on the web (the one tools act in without a workspace_id), whether it is their personal workspace or a demo workspace (sample data, nothing is written to an ad platform), whether the user may change its ads, and how many ad accounts it has (connected, or waiting to be reconnected). has_more is true when another page exists. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `get_workspace_members` **Get workspace members.** Lists the people in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) (name, email and role) and the invitations that are still pending, one page at a time. has_more_members or has_more_invitations is true when another page exists. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `list_ad_accounts` **List ad accounts.** Lists the ad accounts (Google Ads, Microsoft Ads, ChatGPT Ads) in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names): platform, name, platform account ID, currency, time zone, status, whether it is still connected, its guardrails (max daily budget, max bid, max target CPA, min target ROAS and the max rise per step for budgets and bids, set by people in Roasby; each holds only once set, and changes outside them are refused), and when Roasby last synced it (data comes from the copy in Roasby, refreshed on a schedule or on request, not live from the platform; null means not synced yet). Accounts of a disconnected login are read-only history (needs_reconnect: the access ended, because the platform ended it or the person who connected it left, and a person reconnects it in Roasby), and so are suspended accounts (beyond the limit of active ad accounts of the workspace); people connect and disconnect platforms on the Ad accounts page in Roasby. has_more is true when another page exists. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `list_ad_entities` **List campaigns, ad groups, ads or keywords.** Lists one level of the ads in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names): campaigns, ad groups, ads or keywords (entity_type), with their Roasby IDs, status, daily budget (campaigns, in micros of the account currency), keyword match type, and whether a status or budget change to them is still being applied. period (7d, 30d or 90d) adds the spend, clicks, conversions, conversion value and ROAS of each item over that many complete days (the same numbers as the Campaigns page), and for campaigns and ad groups the search impression share with the share lost to ad rank and to budget. Each keyword also has its insight from the ad platform: the Quality Score (1 to 10) with its expected click-through rate, ad relevance and landing page experience, the first page, top of page and first position bid estimates (micros and formatted), whether it is below the first page bid, and its approval, serving and primary status with the reasons; a missing score or estimate comes with the reason (not enough data, or not offered under automated bidding). Each responsive search ad has its text (headlines and descriptions with their pins, display paths, final URL) and whether Roasby can edit it; each keyword its own final URL and whether Roasby can change it. Each ad has its approval status (approved, under review, disapproved... or unknown when the platform reports none). An ad or keyword the ad platform disapproved, limited or is still reviewing has a policy object: each policy finding with the policy in plain words, how it limits serving, the headline or description it is about, the evidence the platform names, the countries where it cannot show, what can be changed, and whether the decision can be appealed (Microsoft Ads). Narrow it with ad_account_id, parent_id (the campaign of ad groups, the ad group of ads and keywords), campaign_id (the campaign of ad groups, ads or keywords), status, a name search, for keywords max_quality_score or below_first_page_bid, and for ads and keywords policy_issues_only. has_more is true when another page exists. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `list_ad_changes` **List ad changes.** Lists the change log of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names), newest first: every pause, enable, daily budget change, bid change, negative keyword change and new campaign made to its ads through Roasby, by a person, an AI assistant or the system, with the values before and after (budgets and bids in micros of the account currency), whether it is pending, applied (partly_applied when the platform refused part of it) or failed (with the reason), and whether it was reverted. A batch of changes confirmed together is one entry (batch, with its counts and status); batch_id lists that batch's items instead, and status narrows them to one status. ad_account_id narrows it to one ad account. has_more is true when another page exists. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `get_performance_summary` **Get performance summary.** Summarizes the cross-platform ad performance (Google Ads, Microsoft Ads, ChatGPT Ads) of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) over the last 7, 30 or 90 complete days (ending yesterday, in each ad account's own days): spend, conversion value, ROAS, conversions, clicks and impressions, with the totals of the period before for comparison, every day of the period, and the split by platform and by ad account, largest spend first. Narrow it with ad_account_id or campaign_id. Amounts are in micros (1/1,000,000) and grouped per currency, never converted. Data comes from the copy in Roasby, refreshed on a schedule or on request, and includes disconnected and suspended accounts' history. The same numbers appear on the dashboard in Roasby. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `get_campaign_performance` **Get campaign performance.** Lists the campaigns of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) with their performance over the last 7, 30 or 90 complete days (ending yesterday): spend, conversion value, ROAS, conversions, clicks and impressions, plus status, type and daily budget, and for search campaigns the search impression share with the share lost to ad rank and to budget and the top and absolute top impression shares (a value the platform only reports as below 10% or above 90% is given as that bound), and its conversion goal setup (the account's goals or its own, what bidding aims for and problems such as a goal without an enabled conversion action), sorted by spend (or another metric), largest first. Narrow it with ad_account_id or campaign_id. Amounts are in micros (1/1,000,000) of each campaign's account currency, never converted. Data comes from the copy in Roasby, refreshed on a schedule or on request. has_more is true when another page exists. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `get_search_terms` **Get search terms.** Lists what people searched before the ads of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) showed, over the last 7, 30 or 90 complete days (ending yesterday), per ad group: the matched keyword, spend, conversions, conversion value, clicks and impressions, sorted by spend (or another metric), largest first, and whether the term is already excluded, by a Roasby change or in the ad platform (added_as_negative). Narrow it with ad_account_id, campaign_id, ad_group_id or a text search. Amounts are in micros of each account's currency. has_more is true when another page exists. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `find_wasted_spend` **Find wasted spend.** Finds money spent without results in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) over the last 7, 30 or 90 complete days (ending yesterday): the costliest search terms (per ad group) and keywords that brought no conversion, at or above min_cost_micros, and per currency the total spent on search terms without conversions. Search terms already excluded, by a Roasby change or in the ad platform, are left out. Narrow it with ad_account_id or campaign_id. Amounts are in micros of each account's currency. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `list_recommendations` **List recommendations.** Lists the changes Roasby recommends in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names), the same list as its Recommendations page: search terms to exclude as negative keywords (they cost money without a conversion in the last 30 days and Roasby's AI judged them unrelated to the advertiser), keywords to pause (many clicks, no conversion) and daily budgets to raise (search campaigns that lose search impressions to their budget while converting at or below their ad account's cost per conversion), costliest first, each with its cost in micros of the account currency, its clicks and a short explanation. A budget raise has the suggested daily budget, within the ad account's guardrails (max daily budget, max change per step), never above them; when they leave no raise, blocked_by names the guardrail and user_actions the step for a person. Each open one that can be approved carries approve_with and approve_arguments: the preview and the arguments that approve it. status closed returns approved, resolved and dismissed ones; has_more is true when another page exists. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `list_alerts` **List anomaly alerts.** Lists the anomaly alerts of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names), the same list as its Alerts page: campaigns whose spend spiked on the last complete day or whose cost per conversion jumped over the last 7 days (or that kept spending without any conversion), and enabled ads the ad platform disapproved, each with the policy findings (the policy in plain words, the evidence, the countries, what can be changed and whether it can be appealed). Open alerts come most severe first (severity 1–5), each with its numbers in micros of the account currency and a short summary; an alert resolves on its own when the numbers settle or the ad is fixed. status resolved returns past alerts; has_more is true when another page exists. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `list_conversion_actions` **List conversion actions.** Lists how the ad accounts of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) track conversions: each conversion action (Google Ads) or conversion goal (Microsoft Ads) with where its conversions come from (website tag, Google Analytics 4 import, app, phone calls, upload, store), its status, category and goal, whether it is primary (counted toward bidding and the Conversions column), how it counts and gives credit, whether it is managed outside the account, and whether it is recording, with the last conversion Google Ads received (for Google Analytics 4 imports, only its day). Each account comes with what bidding aims for and the problems found (no primary conversion action in the goals bidding uses, a primary action that stopped recording). Narrow it with ad_account_id or primary_only; removed actions are left out unless include_removed is true. Data comes from the copy in Roasby, read every few hours, when an ad account is synced on request, and after a new search campaign. ChatGPT Ads conversion tracking is not read. has_more is true when another page exists. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `list_assets` **List sitelinks, callouts and other assets.** Lists the text assets linked in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names): sitelinks, callouts, structured snippets, prices and promotions, each with the Roasby ID of its link (for pausing and enabling it), where it is linked (the whole ad account, a campaign or an ad group), its status and its content, and whether a pause or enable of it is still being applied. Narrow it with ad_account_id, campaign_id (the campaign and its ad groups), ad_group_id, type or status; removed links are left out unless include_removed is true. Data comes from the copy in Roasby, read at every sync. ChatGPT Ads has no such assets. has_more is true when another page exists. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `get_keyword_ideas` **Get keyword ideas.** Gets keyword ideas for an ad account of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) from its ad platform's keyword planner (Google Ads Keyword Planner or Microsoft Ads Ad Insight), from 1 to 20 seed keywords and/or a web page, in 1 to 10 countries and one language. Each keyword comes with its average monthly searches and monthly trend over the last 12 months, its competition (low, medium or high; Google Ads adds an index from 0 to 100) and a bid estimate in the account currency (Google Ads: the low and high top-of-page bid; Microsoft Ads: a suggested bid), the most searched first. A value is null when the platform has no number for it. The numbers are estimates and may be rounded. It reads the ad platform live, so a new request can take a few seconds and then answers with status running; the same request within a day is answered from Roasby's cache. ChatGPT Ads has no keyword research. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | Yes | ### `get_keyword_volumes` **Get keyword search volumes.** Gets the search volume and bid estimates of exactly the keywords given (up to 1,000) for an ad account of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) from its ad platform's keyword planner (Google Ads Keyword Planner or Microsoft Ads Ad Insight), in 1 to 10 countries and one language: the average monthly searches and monthly trend over the last 12 months, the competition (low, medium or high; Google Ads adds an index from 0 to 100) and a bid estimate in the account currency (Google Ads: the low and high top-of-page bid; Microsoft Ads: a suggested bid), the most searched first. A value is null when the platform has no number for it, Google Ads combines close variants into one result, and keywords that came back without a result are listed in missing_keywords. The numbers are estimates and may be rounded. It reads the ad platform live, so a new request can take a few seconds and then answers with status running; the same request within a day is answered from Roasby's cache. ChatGPT Ads has no keyword research. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | Yes | ### `get_weekly_report` **Get weekly report.** Returns the latest weekly report of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) (or the one with report_id), the same report its members get by email on Mondays and see on the Reports page: the last 7 complete days against the week before per currency (amounts in micros, never converted), the split by ad platform, the campaigns whose conversions rose or fell most, the search campaigns that lost a meaningful share of their impressions to budget or ad rank, the open alert and recommendation counts and the ad accounts to reconnect, with the short summary Roasby's AI wrote (summary_by_ai is false when there is none). Reports keep the numbers they were sent with. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `search_docs` **Search Roasby docs.** Searches the Roasby documentation (setup, connecting AI assistants, the safety model, tool reference) and returns the best matching pages with a short summary and their slugs. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `get_doc` **Read a Roasby docs page.** Returns one Roasby documentation page as Markdown, by its slug (for example "connect-your-ai" or "safety-model"). | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ## Preview tools Each preview checks a change without making it and returns a one-time confirmation token for its change tool. ### `preview_activate_ad_account` **Preview making an ad account active.** Shows whether a suspended ad account (read-only because the workspace has more ad accounts than its limit) in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) can be made active again, without changing anything. When the workspace is at its limit, replace_ad_account_id names the active account that becomes read-only in its place. When it is allowed, it returns a confirmation_token, valid for 10 minutes, once. Owners and admins only. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_archive_recommendation` **Preview dismissing a recommendation.** Shows whether an open recommendation in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) can be dismissed, without changing anything. Dismissing changes nothing in the ad account; Roasby just never suggests it again. When it is allowed, it returns a confirmation_token, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_pause_entity` **Preview pausing an ad item.** Shows what pausing a campaign, ad group, ad, keyword or asset link in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do, and whether Roasby's safety rules allow it, without changing anything. When it is allowed, it returns a confirmation_token, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_enable_entity` **Preview enabling an ad item.** Shows what enabling (resuming) a paused campaign, ad group, ad, keyword or asset link in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do, and whether Roasby's safety rules allow it, without changing anything. Enabling can start spending money, so a campaign above the ad account's max daily budget, or only partly created, is refused. When it is allowed, it returns a confirmation_token, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_pause_entities` **Preview pausing ad items together.** Shows what pausing many campaigns, ad groups, ads, keywords and asset links (sitelinks, callouts and other assets) of one ad account in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) together would do, and whether Roasby's safety rules allow each one, without changing anything: the items that may change, the refused ones with why, and the totals. When some may change, it returns one confirmation_token for all of them, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_enable_entities` **Preview enabling ad items together.** Shows what enabling (resuming) many paused campaigns, ad groups, ads, keywords and asset links (sitelinks, callouts and other assets) of one ad account in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) together would do, and whether Roasby's safety rules allow each one, without changing anything: the items that may change, the refused ones with why (such as a campaign above the ad account's max daily budget), and the totals. When some may change, it returns one confirmation_token for all of them, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_update_campaign_budget` **Preview a campaign budget change.** Shows what setting a campaign's daily budget in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do (the budget before and after, in micros and formatted in the account currency) and whether the ad account's guardrails and Roasby's safety rules allow it, without changing anything. When it is allowed, it returns a confirmation_token, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_update_campaign_settings` **Preview a campaign settings change.** Shows what changing the settings of a Google Ads or Microsoft Ads search campaign in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do: any of its countries, location option, search partners, final URL suffix, tracking template, ad schedule, device bid adjustments, ad rotation and (Microsoft Ads) languages, each section before and after, and whether the guardrails and safety rules allow it, without changing anything. All sections are one change. When it is allowed, it returns a confirmation_token, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_update_conversion_goals` **Preview a conversion goals change.** Shows what changing the conversion goals a Google Ads or Microsoft Ads search campaign in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) bids on would do: the ad account's goals, or goals chosen for the campaign, before and after, which chosen goals are not recording conversions, and whether the safety rules allow it, without changing anything. When it is allowed, it returns a confirmation_token, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_update_bidding` **Preview a bidding change.** Shows what changing the bidding strategy and targets of a Google Ads or Microsoft Ads search campaign in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do (manual cost per click, maximize clicks, maximize conversions with an optional target CPA, maximize conversion value with an optional target ROAS, or target impression share), or a Google Ads ad group's own target CPA: before and after, whether its conversion goals record conversions, the guardrails, and whether the safety rules allow it, without changing anything. When it is allowed, it returns a confirmation_token, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_update_bid` **Preview a bid change.** Shows what setting the max cost per click of an ad group or keyword in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do, and whether Roasby's safety rules and the ad account's guardrails allow it, without changing anything. Only items with bids_adjustable true can change: campaigns under automated bidding ignore these bids. When it is allowed, it returns a confirmation_token, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_update_bids` **Preview bid changes together.** Shows what setting the max cost per click of many ad groups and keywords of one ad account in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) together would do, and whether Roasby's safety rules and the ad account's guardrails allow each one, without changing anything: each new bid (an amount per item, one amount for all, a change in percent, or each keyword's first page bid estimate up to a cap), the refused items with why, the bids the guardrails limited, and the totals. When some may change, it returns one confirmation_token for all of them, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_add_negative_keywords` **Preview adding negative keywords.** Shows what excluding keywords from a campaign or an ad group in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do (every keyword with its match type) and whether Roasby's safety rules allow it, without changing anything. When it is allowed, it returns a confirmation_token, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_add_keywords` **Preview adding keywords to an ad group.** Shows what adding keywords (text, match type, optional bid and final URL) to an ad group of a search campaign in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do, and whether Roasby's safety rules allow each one, without changing anything: the keywords that may be added, the refused ones with why (too long, duplicates, blocked by a negative keyword, above the max bid...), and the totals. Every keyword is created paused. When some may be added, it returns one confirmation_token for all of them, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_add_ad_groups` **Preview adding ad groups to a campaign.** Shows what adding ad groups (each with a name, a default bid, and optionally keywords, negative keywords and a responsive search ad) to a search campaign in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do, and whether Roasby's safety rules allow each one with its parts, without changing anything: the ad groups that may be added, the refused ones with why and the part that breaks the rule (a name the campaign has, a keyword that is too long, a bid above the max bid...), the totals and the platform operations. Every ad group is created paused, with its keywords and ad under it. When some may be added, it returns one confirmation_token for all of them, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_add_responsive_search_ads` **Preview adding responsive search ads to ad groups.** Shows what adding responsive search ads (headlines and descriptions, each optionally pinned to a position, a final URL, display paths and a final URL suffix) to ad groups of search campaigns in one ad account of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do, and whether Roasby's safety rules allow each one, without changing anything: the ads that may be added, the refused ones with why and the part that breaks the rule (a headline that is too long, two headlines that are the same, pins that leave a position empty...), the totals and the platform operations. Every ad is created paused. When some may be added, it returns one confirmation_token for all of them, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_add_assets` **Preview adding sitelinks, callouts and other assets.** Shows what adding text assets (sitelinks, callouts, structured snippets, prices and promotions) to an ad account, a search campaign or one of its ad groups (or several campaigns or ad groups of one ad account, every asset to each) in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do, and whether Roasby's safety rules allow each one, without changing anything: the assets that may be added, the refused ones with why (too long, too few values or rows, an asset that is there already, a Microsoft Ads campaign or ad group that is not paused...), and the totals. On Google Ads each asset is linked paused; Microsoft Ads has no paused links, so there Roasby links only to paused campaigns and ad groups. When some may be added, it returns one confirmation_token for all of them, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_update_ads` **Preview ad text edits.** Shows what editing the text of responsive search ads of one ad account in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do, and whether Roasby's safety rules allow each edit, without changing anything: the given headlines, descriptions (with their pins), display paths or final URL of each ad, or a literal find and replace across the ads of an ad account, campaign or ad group. It lists each ad's whole text after and each part that changes before and after, the ads refused with why and the text they would have had, and the totals. When some may change, it returns one confirmation_token for all of them, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_update_keywords` **Preview keyword changes.** Shows what changing the text, match type or own final URL of keywords of one ad account in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do, and whether Roasby's safety rules allow each change, without changing anything. A final URL, and a match type on Microsoft Ads, change in place; a new text, and a new match type on Google Ads, replace the keyword: the new keyword is added paused to the same ad group with the old one's own bid and final URL, and the old one is paused, never removed. It lists each keyword before and after, whether it is a replace, the keywords refused with why, and the totals. When some may change, it returns one confirmation_token for all of them, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_create_search_campaign` **Preview a new search campaign.** Shows the complete search campaign that would be created in one of the ad accounts of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) (budget, bidding, countries, the advertiser's EU political ads declaration, its negative keywords and its ad groups with their keywords, negative keywords and responsive search ads) and whether Roasby's safety rules allow it, without changing anything. The campaign is created paused and its daily budget must stay within the account's max daily budget. If any part breaks a rule, the preview names every part that does. When it is allowed, it returns a confirmation_token, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_create_chat_campaign` **Preview a new ChatGPT Ads campaign.** Shows the complete ChatGPT Ads campaign that would be created in one of the ChatGPT Ads accounts of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) (budget, bidding, countries, context hints and the chat card ad with its image) and whether Roasby's safety rules allow it, without changing anything. The campaign is created paused and its daily budget must stay within the account's max daily budget. When it is allowed, it returns a confirmation_token, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_revert_ad_change` **Preview reverting an ad change.** Shows what reverting an applied ad change in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do and whether Roasby's safety rules allow it, without changing anything. When it is allowed, it returns a confirmation_token, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_revert_ad_change_batch` **Preview reverting a batch of ad changes.** Shows what reverting a batch of ad changes in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do (each item it applied gets its value before back) and whether Roasby's safety rules allow each item, without changing anything. When some may change, it returns one confirmation_token, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_create_support_request` **Preview a message to Roasby support.** Prepares a message from the connected user, about the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names), to the Roasby support team (help with Roasby, billing, privacy or data requests, or an abuse report) without sending anything. It returns a confirmation_token, valid for 10 minutes, once. The team replies by email to the user's account address. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ## Change tools These tools change something. A change tool with a preview makes only the change its preview checked, after you confirm it. ### `run_ad_account_sync` **Sync an ad account now.** Asks Roasby to refresh its copy of the data of one ad account of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) (campaigns, ad groups, ads, keywords, metrics, search terms) from the ad platform now, instead of waiting for the scheduled sync. It only reads from the platform and never changes ads. The sync runs in the background and usually takes a few minutes; last_synced_at on the ad account changes when it finishes, and last_sync_error is set when it fails. It also reads the conversion goals again. Changes made through Roasby are in its copy without it: applied values at once, and new campaigns, ad groups, keywords, ads and assets with a sync Roasby runs by itself a few minutes later (follow_up_sync_due_at on the ad account). Each account can be synced this way only so often; the answer says when it is allowed again. started is false when the account was synced too recently, or when a sync is already on its way (next_sync_allowed_at is then about when its new data shows). | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | No | Yes | ### `activate_ad_account` **Make an ad account active.** Makes a suspended ad account in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) active again (synced and changeable); with replace_ad_account_id, that active account becomes read-only in its place. Requires the confirmation_token from a preview of the same change. Nothing is disconnected or deleted, and the swap can be made again the other way. Owners and admins only. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | No | No | ### `archive_recommendation` **Dismiss a recommendation.** Dismisses an open recommendation in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names), so Roasby never suggests it again. Nothing changes in the ad account. Requires the confirmation_token from a preview of the same change. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | Yes | No | ### `pause_entity` **Pause an ad item.** Pauses a campaign, ad group, ad, keyword or asset link in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names). Requires the confirmation_token from a preview of the same change. The change is logged and can be reverted; it is pending until the ad platform applies it. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | No | No | ### `enable_entity` **Enable an ad item.** Enables (resumes) a paused campaign, ad group, ad, keyword or asset link in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names), so it can start spending money. Requires the confirmation_token from a preview of the same change. The change is logged and can be reverted; it is pending until the ad platform applies it. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | Yes | No | ### `pause_entities` **Pause ad items together.** Pauses many campaigns, ad groups, ads, keywords and asset links (sitelinks, callouts and other assets) of one ad account in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) as one batch. Requires the confirmation_token from a preview of the same batch; only the items that preview allowed change. Each item is logged and can be reverted, alone or with its batch; items are pending until the ad platform applies them. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | No | No | ### `enable_entities` **Enable ad items together.** Enables (resumes) many paused campaigns, ad groups, ads, keywords and asset links (sitelinks, callouts and other assets) of one ad account in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) as one batch, so they can start spending money. Requires the confirmation_token from a preview of the same batch; only the items that preview allowed change. Each item is logged and can be reverted, alone or with its batch; items are pending until the ad platform applies them. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | Yes | No | ### `update_campaign_budget` **Update a campaign budget.** Sets the daily budget of a campaign in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names). Requires the confirmation_token from a preview of the same change. The budget must stay within the ad account's guardrails. The change is logged and can be reverted; it is pending until the ad platform applies it. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | Yes | No | ### `update_campaign_settings` **Update campaign settings.** Changes the settings of a Google Ads or Microsoft Ads search campaign in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) (countries, location option, search partners, final URL suffix, tracking template, ad schedule, device bid adjustments, ad rotation, languages) as one change. Requires the confirmation_token from a preview of the same change. Bid adjustments must stay within the ad account's max bid change. The change is logged and can be reverted; it is pending until the ad platform applies it. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | Yes | No | ### `update_conversion_goals` **Update conversion goals.** Changes the conversion goals a Google Ads or Microsoft Ads search campaign in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) bids on: the ad account's goals, or goals chosen for the campaign. Requires the confirmation_token from a preview of the same change. The change is logged and can be reverted; it is pending until the ad platform applies it. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | Yes | No | ### `update_bidding` **Update bidding.** Changes the bidding strategy and targets of a Google Ads or Microsoft Ads search campaign in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names), or a Google Ads ad group's own target CPA. Requires the confirmation_token from a preview of the same change. Targets stay within the guardrails set on the ad account (max bid for a max cost per click, max target CPA, min target ROAS, and the max bid change for a rise). The change is logged and can be reverted; it is pending until the ad platform applies it. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | Yes | No | ### `update_bid` **Update a bid.** Sets the max cost per click of an ad group or keyword in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names). Requires the confirmation_token from a preview of the same change. The bid must stay within the ad account's guardrails. The change is logged and can be reverted; it is pending until the ad platform applies it. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | Yes | No | ### `update_bids` **Update bids together.** Sets the max cost per click of many ad groups and keywords of one ad account in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) as one batch. Requires the confirmation_token from a preview of the same batch; only the items that preview allowed change, each within the ad account's guardrails. Each bid is logged and can be reverted, alone or with its batch; items are pending until the ad platform applies them. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | Yes | No | ### `add_negative_keywords` **Add negative keywords.** Excludes keywords from a campaign or an ad group in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names), so its ads stop showing for those searches. Requires the confirmation_token from a preview of the same change. Negative keywords the target already has are left as they are. The change is logged and can be reverted (reverting takes away exactly the negative keywords it added); it is pending until the ad platform applies it. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | No | No | ### `add_keywords` **Add keywords to an ad group.** Adds keywords to an ad group of a search campaign in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) as one batch, each created paused. Requires the confirmation_token from a preview of the same keywords; only the keywords that preview allowed are added. Each keyword is logged and can be reverted (paused), alone or with its batch; keywords are pending until the ad platform adds them. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | No | No | ### `add_ad_groups` **Add ad groups to a campaign.** Adds ad groups to a search campaign in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) as one batch, each created paused with its keywords, negative keywords and responsive search ad under it. Requires the confirmation_token from a preview of the same ad groups; only the ad groups that preview allowed are added. Each ad group is logged and can be reverted (paused), alone or with its batch; ad groups are pending until the ad platform adds them. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | No | No | ### `add_responsive_search_ads` **Add responsive search ads to ad groups.** Adds responsive search ads to ad groups of search campaigns in one ad account of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) as one batch, each created paused. Requires the confirmation_token from a preview of the same ads; only the ads that preview allowed are added. Each ad is logged and can be reverted (paused), alone or with its batch; ads are pending until the ad platform adds them. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | No | No | ### `add_assets` **Add sitelinks, callouts and other assets.** Adds text assets (sitelinks, callouts, structured snippets, prices and promotions) to an ad account, a search campaign or one of its ad groups (or several campaigns or ad groups of one ad account, every asset to each) in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) as one batch: on Google Ads each linked paused, on Microsoft Ads linked to a paused campaign or ad group. Requires the confirmation_token from a preview of the same assets; only the assets that preview allowed are added. Each asset is logged and can be reverted (its link paused, or on Microsoft Ads taken away; the asset itself stays), alone or with its batch; assets are pending until the ad platform adds them. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | No | No | ### `update_ads` **Update ad text.** Edits the text of responsive search ads of one ad account in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) in place, as one batch: headlines, descriptions with their pins, display paths and final URLs, given per ad or by a literal find and replace. Requires the confirmation_token from a preview of the same batch; only the ads that preview allowed change. Each ad keeps its status, ID and history, and the ad platform reviews the new text again. Each edit is logged and can be reverted, alone or with its batch; items are pending until the ad platform applies them. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | Yes | No | ### `update_keywords` **Update keywords.** Changes the text, match type or own final URL of keywords of one ad account in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) as one batch. Requires the confirmation_token from a preview of the same batch; only the keywords that preview allowed change. A final URL, and a match type on Microsoft Ads, change in place, keeping the keyword's status, ID and history; a new text, and a new match type on Google Ads, replace the keyword: the new keyword is added paused and the old one is paused, never removed, so it shows no ads until the new one is enabled. Each change is logged and can be reverted, alone or with its batch; items are pending until the ad platform applies them. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | Yes | No | ### `create_search_campaign` **Create a search campaign.** Creates a complete search campaign, paused, in one of the ad accounts of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names): its budget, bidding, countries, negative keywords and every ad group with its keywords, negative keywords and responsive search ads, as one change. Requires the confirmation_token from a preview of the same change. Nothing runs until the user enables the campaign. The change is logged; reverting it pauses the campaign. It is pending until the ad platform creates it. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | No | No | ### `create_chat_campaign` **Create a ChatGPT Ads campaign.** Creates a complete ChatGPT Ads campaign, paused, in one of the ChatGPT Ads accounts of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names): its budget, bidding, countries, one ad group with context hints and one chat card ad whose image ChatGPT Ads fetches from image_url. Requires the confirmation_token from a preview of the same change. Nothing runs until the user enables the campaign; ChatGPT Ads reviews the ad once it is created. The change is logged; reverting it pauses the campaign. It is pending until the ad platform creates it. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | No | No | ### `revert_ad_change` **Revert an ad change.** Reverts an applied ad change in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) (restores the value before it). Requires the confirmation_token from a preview of the same change. The revert is itself a logged change, held to the same guardrails and limits; it is pending until the ad platform applies it. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | Yes | No | ### `revert_ad_change_batch` **Revert a batch of ad changes.** Reverts a batch of ad changes in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names): each item the batch applied gets its value before back, as a new batch. Requires the confirmation_token from a preview of the same revert. The revert is itself logged, held to the same guardrails; its items are pending until the ad platform applies them. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | Yes | No | ### `create_support_request` **Send a message to Roasby support.** Sends a message from the connected user, about the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names), to the Roasby support team. Requires the confirmation_token from a preview of the same message. Returns a reference to quote in follow-ups; the team replies by email within 2 business days. Limited to a few messages per hour, shared with the contact form. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | No | No | ## Limitations - There are no delete tools, and no tools to connect ad platforms, set guardrails or safety defaults, manage billing or change account settings: people do those in Roasby on the web. - When only a person can do something, a tool result lists it in `user_actions` (what, why, where and a link when there is one). - Your assistant is told to explain each step and never claim it did it. - Steps marked `optional` are choices, such as raising a guardrail instead of making a smaller change. - The confirmation token proves a preview ran, not that you agreed. - A batch changes one ad account at a time, with only so many items in one batch. - Bulk bid changes: - They keep the max bid change per step, so a larger rise takes several batches (a cut takes one). - First page bid estimates exist only for keywords, never under automated bidding. - Conversion tracking: - It is as of Roasby's last read (every few hours). ChatGPT Ads conversion tracking is not read. - Conversion actions are never changed. `preview_update_conversion_goals` changes only which goals a Google Ads or Microsoft Ads search campaign bids on, and never creates a custom goal. - Keyword research (`get_keyword_ideas`, `get_keyword_volumes`): - It asks the ad platform live: a new search can take a few seconds. - Its numbers are estimates kept for a day. - A workspace runs only so many new searches an hour. - ChatGPT Ads has none. - Impression share: - It covers search campaigns and their ad groups only, as of the last sync. - Google Ads reports below 10% and lost above 90% only as bounds. - On Google Ads, ad groups have no `lost_to_budget`: Google reports the share lost to budget for campaigns only. - Keyword insight: - It is as of the last sync. - Microsoft Ads reports it only for keywords with recent activity and has no below first page bid status. - Adding keywords works on Google Ads and Microsoft Ads search campaigns only, one add at a time per ad group, and every keyword is added paused. - Adding ad groups: - It works on Google Ads and Microsoft Ads search campaigns only, one add at a time per campaign. - Every ad group is added paused. - Each ad group, keyword, negative keyword and ad counts toward the items of one batch. - Ad text edits: - They work on Google Ads and Microsoft Ads responsive search ads only, once synced, one edit at a time per ad. - A find and replace looks at up to 10,000 ads. - Keyword changes: - They work on Google Ads and Microsoft Ads search campaigns only, once a sync read the keyword's own final URL. - One change at a time per keyword: a pending replace or its revert holds both keywords, and a keyword named twice in one call is refused the second time. - Reverting a replace whose new keyword was removed already only gives the old keyword its status back. - A new text, and a new match type on Google Ads, replace the keyword (the new one added paused, the old one paused, never removed). - Bidding changes (`preview_update_bidding`): - They work on a Google Ads or Microsoft Ads search campaign's own strategy, once synced. - Only when Roasby could set the bidding before back exactly (`bidding_not_revertible`). - Ad group target CPAs on Google Ads only, under a campaign target CPA. - A max cost per click stays within the max bid, a target CPA within the max target CPA, a target ROAS at or above the min target ROAS, each once set, and each moves at most the max bid change per step. - Maximize conversions and conversion value aim at nothing until the goals record conversions: the preview warns. - On Microsoft Ads, Roasby doesn't change target impression share yet, and never adds a target CPA or ROAS to, or takes one from, a campaign that keeps its strategy. - Campaign settings: - They work on Google Ads and Microsoft Ads search campaigns only, once synced. - A bid adjustment rises at most one max bid change per step. - Regions, cities, a radius, excluded places and the Google Display Network are changed in the ad platform. See every limit by platform on [Limitations](/docs/limitations).