MCP tool reference

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. 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.

When only a person can do something, a tool result lists it in user_actions. See 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.

• 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.

• 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.

• 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: spend spikes, cost per conversion jumps and disapproved ads, each disapproved ad with its policy.
• get_weekly_report gives the 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.

• 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.

• 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.

Suspended ad accounts

An ad account beyond the limit of active ad accounts of the workspace is suspended: read-only history. See 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.

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.

• 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.

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.

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.

• 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.

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.

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.

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.

• 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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").

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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).

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.