MCP Tool Reference
All 21 Connect Atlas Tools

This page describes every tool on the Connect Atlas MCP server. You normally never call these by name: you ask your assistant for what you want in plain language, and it picks the right tool. The reference exists so you know exactly what your assistant can and cannot do. For setup, see Connect Atlas MCP server.

A few conventions shared by all tools:

• Results come back as JSON your assistant reads and explains.
• Errors come back as a short code plus a plain-English message, in the shape { "error": "code", "message": "explanation" }. The full code list is on the main MCP page.
• Every tool except whoami requires an active or trialing subscription.
• whoami is the recommended first call to confirm a new connection.

Read tools

Five tools that look at your account without changing anything.

whoami

Returns the SaaS Ads Studio account the connection is acting as (user id and email) plus the permissions granted. Call it first to confirm a new connection works.

Takes no parameters.

list_automations

Lists Atlas’s Google Ads optimisation automations, each with its id, name, run cadence, whether it is advisory only, and whether it is currently enabled on your account. Also reports whether a Google Ads account is connected and your current approval tier.

Takes no parameters. See Atlas automations for what each automation does.

list_actions

Lists Atlas’s recent actions on your account (what it proposed or did), newest first.

Parameter	Required	Notes
status	No	Filter by status, for example pending, completed, requires_action or failed
limit	No	1 to 50, default 20

get_action

Returns one action in full, including its individual items, for example the specific negative keywords Atlas proposed. Use it to review the detail before approving or rejecting.

Parameter	Required	Notes
action_id	Yes	An action id from list_actions

Returns not_found if the id does not exist or is not yours.

get_performance_metrics

Returns your Google Ads performance summary: KPI totals and period-over-period changes for the chosen window. The verbose day-by-day breakdown is left out on purpose, since totals and changes are what a summary needs.

Parameter	Required	Notes
days	No	7, 30 or 90, default 30

Manage Google Ads

Four tools that run Atlas’s management and control how changes get applied. On Google Ads, Atlas manages the account for real: approved changes are applied.

run_automation

Runs one of Atlas’s optimisation automations now, instead of waiting for its schedule. Atlas analyses your account and proposes changes. Whether they apply immediately or wait for you depends on your approval tier.

Parameter	Required	Notes
automation_id	Yes	An id from list_automations, for example search_term_review_quick

Each automation has a 1 hour cooldown, so the same automation can be run on demand at most once per hour (cooldown error). If an action of the same type is already waiting for review, you get pending_exists and should review that one first.

approve_action

Approves an Atlas action, executing the change on your Google Ads account. Approve the whole action, or only specific items within it.

Parameter	Required	Notes
action_id	Yes	The action to approve
item_ids	No	Approve only these items within the action
feedback	No	A note recorded with your decision

Assistants are instructed to confirm with you before calling this. Safety rails still gate execution, so a converting or brand keyword cannot be blocked even if approved.

reject_action

Rejects an Atlas action (or specific items within it), so the proposed change is not made.

Parameter	Required	Notes
action_id	Yes	The action to reject
item_ids	No	Reject only these items within the action
feedback	No	Optionally say why, recorded with the decision

set_approval_tier

Sets how Atlas applies changes, globally or for a single automation.

Parameter	Required	Notes
tier	Yes	manual, smart, auto, or default (see below)
automation_id	No	Apply the tier to this automation only

The tiers: manual means you approve every change. smart means low-risk changes apply automatically and the rest wait for you. auto means changes apply automatically, still within Atlas’s safety rails. Passing default together with an automation_id clears that automation’s override so it follows your global tier again (default is not valid as a global tier).

Build a Google Ads campaign

Nine tools that take you from business profile to a created campaign. The natural order is: check status, check the profile, set the config, generate then save keywords, generate then save ads, create, verify. Your assistant will walk this flow for you.

The most important fact in this section: campaigns are always created paused. Nothing spends until you unpause the campaign in Google Ads yourself.

gads_get_status

Reports the state of your campaign build: whether a Google Ads account is connected, whether your business profile is complete (and which fields are missing), whether config is saved, how many keywords and RSA sets are prepared, how many conversion goals exist, and which campaigns have already been created. The right first call when starting or resuming a build.

Takes no parameters.

get_business_profile

Returns the business profile that drives generation quality: company, product, target customers and language, plus your saved target countries. Flags any gaps worth filling in the app before generating.

Takes no parameters.

gads_set_campaign_config

Saves the campaign configuration. Budget and countries are the two decisions your assistant must confirm with you. Bidding, network and tracking settings use sensible defaults, and currency comes from your connected Google Ads account.

Parameter	Required	Notes
monthlyBudget	Yes	400 to 50000, in your account currency
countries	Yes	At least one country, names or ISO codes
includeBrandCampaign	No	Also build a brand campaign
brandBudgetPercentage	No	Share of budget for the brand campaign

gads_generate_keywords

Generates high-intent buying keywords from your business profile and groups them into themed ad groups. Returns the groups for you to review. Saves nothing.

Parameter	Required	Notes
theme	No	Bias generation toward a theme
existingKeywords	No	Keywords to build around or avoid duplicating

If your business profile is too thin to generate from, you get generation_empty with advice to fill it in.

gads_save_keywords

Saves your curated, grouped keywords for the campaign. Wrap a keyword to set its match type: [square brackets] for exact match, "quotes" for phrase match, bare text for broad match.

Parameter	Required	Notes
groups	Yes	A list of groups, each with an optional name and its keywords
replace	No	Must be true to overwrite previously saved keywords

Saving replaces what was saved before, so if keywords already exist the tool refuses with exists until you confirm and it is called again with replace: true.

gads_generate_rsas

Generates a responsive search ad for each saved ad group: headlines, descriptions, sitelinks, callouts and a display path, written against the ad group’s target keyword and your landing page. Returns everything for review. Saves nothing.

Parameter	Required	Notes
landingPageUrl	No	The page the ads should send people to

Requires saved keywords first, otherwise you get no_keywords.

gads_save_rsas

Saves the reviewed ads (one per ad group) as a single set and returns its set_id, which gads_create_campaign uses.

Parameter	Required	Notes
rsasByAdGroup	Yes	The ads from gads_generate_rsas, after any edits you asked for

gads_create_campaign

Creates the campaign in Google Ads from your saved config, keywords and ad set. The campaign is created paused. The response includes any partialFailures, meaning individual keywords or ads Google rejected while the rest succeeded.

Parameter	Required	Notes
set_id	No	The RSA set to use, from gads_save_rsas
force	No	Must be true to create another campaign when one already exists

If a campaign already exists you get already_created until you confirm and it is called again with force: true. Assistants are instructed to confirm with you before calling this tool at all.

gads_verify_campaign

Confirms whether your Google Ads account has at least one live (enabled) campaign. Useful as a final check after you unpause.

Takes no parameters.

Generate for Meta, apply it yourself

Three tools for Facebook and Instagram. They generate plans and assets from your business profile. They never create or change anything in your Meta account. You take the output and build it in Meta Ads Manager yourself, which usually takes a few minutes.

fb_generate_audiences

Generates Meta audience ideas, both prospecting and remarketing, from your business profile.

Takes no parameters.

fb_generate_copy

Generates Meta ad copy variants (primary text, headline and description) across different persuasion angles.

Parameter	Required	Notes
additional	No	Pass true to generate more variants after a first batch

fb_generate_creatives

Generates Meta creative concept briefs, for example before-and-after, testimonial, founder and mockup formats, ready to hand to whoever produces your creative.

Takes no parameters.

Errors

Every tool reports failures as { "error": "code", "message": "explanation" }. The canonical code table lives on the main MCP page, covering no_subscription, missing_permission, unknown_automation, not_found, query_failed, exists, already_created, cooldown, pending_exists and generation_empty.