Adrails Docs

MCP tools reference

Explore every Adrails MCP tool, its inputs, read and write permissions, review requirements, rate limits and errors before connecting your AI assistant.

The server has 78 tools. 57 are the tools the Adrails agent uses in the app; the other 21 cover accounts, integrations, campaign drafts, automations, Knowledge and job status.

tools/list returns a tool only when the connection's permissions and your role allow at least one of its operations. The same catalog, searchable, is on the MCP page in Adrails.

Calling a tool

The arguments of every call share one shape. The tool's own inputs go in input; the rest frames the call.

ArgumentTypeRequiredWhat it is
inputobjectNo, empty by defaultThe tool's inputs, listed under each tool below.
idempotencyKeystring, 8 to 128 charactersFor a change, a proposal or a billable readYour key for this call. Reuse it only to retry the exact same call.
accountIdsarray of string, 1 to 100NoNarrows an agent tool to some of the workspace's ad accounts. It can never add one. The 22 other tools refuse it and take accountId or adAccountId in input instead.
userStatementstring, at most 8,000 charactersYes for launch_brief, otherwise noThe latest verbatim request or free-text answer, nonempty for launch_brief, kept in the connection's history as an unverified statement. It is never a permission or evidence. An amount the person wrote in it applies as given on campaigns_change_budget, and a period, columns or all my ads in it shape the file of ads_export, as their words do in the app.

Any other argument is refused. No tool takes a workspace or a user: both come from the connection.

{
  "name": "performance_period",
  "arguments": {
    "input": { "accountId": "<account id>", "level": "campaign", "since": "2026-09-01", "until": "2026-09-30" },
    "idempotencyKey": "performance-september-001"
  }
}
{
  "name": "integrations_connect",
  "arguments": { "input": { "provider": "shopify" }, "idempotencyKey": "connect-shopify-001" }
}

The inputs below are the top-level fields of input. A field typed object follows the JSON Schema your client receives in tools/list.

What a call does

Each tool's Access line says what a call does, the permission it needs and what your role must allow, operation by operation where they differ.

  • read returns data and changes nothing.
  • change acts at once, inside Adrails' own rules, with no approval step: a setup link, a sync, a draft, a template, a Knowledge entry, an automation, a channel message. It needs an idempotencyKey.
  • proposal for approval prepares one exact advertising change and returns a link to approve it in Adrails. Nothing reaches Meta or Google Ads before you approve. It needs an idempotencyKey.

Approving a proposal

A proposal comes back with status set to awaiting_approval, its actionId, a preview of the change, expiresAt and an approvalUrl, https://adrails.ai/oauth/actions/<actionId>. Its message says Review the exact change in Adrails. Nothing has been applied. On Preview it also carries planRequired set to true and a planUrl to the Plan tab of Settings, and its message adds that applying the change needs a plan.

  1. Open the link. The Review advertising change page names the AI client, the workspace and the ad account, and shows the change field by field.
  2. Choose Approve this change or Decline.

Any current owner or admin of the same workspace can open the link and approve it, signed in as themselves, on an active plan (on Preview the page says so and links to the plan choice; Decline still works), with the connection still allowed to prepare advertising changes and the ad account still in the workspace. On approval Adrails reads the platform again and applies the exact change once, or blocks it if the entity changed in the meantime, as Review and undo explains. A proposal expires 24 hours after it is prepared. In-app chat proposals keep their 30-minute window. Non-admin members see an explanation asking them to share the link with an owner or admin.

Your AI client may ask you to allow a tool call. That is the client's own permission, not an approval, and neither is the consent you gave when connecting.

Retries and idempotency

  • The same idempotencyKey with the same arguments returns the first result and does nothing twice. For a proposal, the retry reports where it stands now: applied, reverted, approved, closed or expired.
  • The same key with other arguments is refused.
  • A call cut off before it finished keeps its key blocked. Check it with jobs_status, kind set to operation, before you use a new key.
  • Keys belong to one connection and one tool.

One call at a time

Calls on one connection run one after another. The grant lock expires after at most 125 seconds if a process stops, and is released when the call returns or throws. A call sent while another is running is refused without running: retry it once the first has finished, with the same idempotencyKey if the call requires a key.

Launch questions and context

MCP clients have no Adrails card renderer. Call launch_brief with the latest verbatim userStatement, ask its open questions in the conversation using the returned labels and named options, and accept free-text answers. Pass confirmed choices in input and the latest answer in userStatement. A free-text publication mode such as live is a preference for the proposal only. Never invent an account ID or treat these answers as approval to spend; show the browser approval link for a proposed advertising change.

A new user statement with launch intent clears the saved brief and starts a fresh context boundary. Repeating the same statement across tools continues that brief. After two hours without an agent tool turn, the next agent call also resets implicit context. Older history remains available through explicit recall. MCP does not supply a reliable cross-client chat ID, so unrelated short conversations without a new launch request can still share recent context. Idempotency keys and existing approval links survive a context reset; a completed retry does not reset context again.

Who can call what

  • Permission. Each operation needs the permission its Access line names, and every call also needs Read workspace data. See Permissions.
  • Role. Each call is checked against what your current role in the workspace allows, as Settings > Roles sets it, not the role you had when you connected. The Access line names what the role must allow beyond reading. The built-in Member allows all of it; a custom role may allow less.
  • Plan. Preview prepares proposals like any plan, so you can read the exact change. Applying one needs an active plan: on Preview the proposal says so with a link to choose one, and Approve this change on the review page waits until the workspace has one. Every other tool follows the plan rules it follows in the app, such as the limits on automations.
  • Credits. MCP tool calls cost 0 credits, reads and changes alike: your AI client does the thinking. They are listed in the usage log in Settings > Plan as MCP tool call. Mutations require an idempotencyKey; reuse it only for the exact same operation. A completed retry is not run twice. Your AI client's inference charges are separate. See The agent and credits.

Results

  • structuredContent.result holds the exact data. Read this one in code.
  • The text content is the same result as readable Markdown: tables, chart series as tables, approval links. No AI model writes it.
  • A result is at most 256,000 bytes. A larger one is refused whole, with no partial figures: ask for a shorter period, a narrower selection or a page.
  • A request is at most 1 MB.
  • Listings that page return nextCursor: pass it as after.

Report files

A report the app offers as CSV and PDF buttons comes back with its files as links: the ad file of ads_export, with its text for Claude, the change report of actions_recent, and any other report a result lists as files. The table's downloads holds them, and the text lists them under the table.

  • Each link opens one file, for the person who connected the client, and works for 1 hour. Ask for the file again after that.
  • Opening it reads the report again from the platform, with that person's current role and ad account access, as the app's button does. A link stops working when the connection is revoked or the person leaves the workspace.
  • The link opens only once you are signed in to Adrails, as the person who connected the client. Anyone else is sent to sign in, then refused.

Rate limits

LimitValue
Calls, per access token60 per minute
Changes and proposals, per access token10 per minute
Calls, per person in the workspace180 per minute
Calls, per workspace600 per minute

An authenticated tools/call over a limit returns HTTP 200 with result.isError: true and a retry message. Other requests use HTTP 429 and rate_limited. Its message says how many seconds to wait; the Retry-After header says 60.

Sign-in has its own limits, per IP address: 10 client registrations and 300 other OAuth requests a minute. They answer 429 with a Retry-After header.

Errors

Authenticated tool argument, missing-scope and rate-limit errors are JSON-RPC tool results with isError: true, so the model can correct the call. Invalid JSON, authentication, origin and infrastructure failures remain HTTP errors.

Refused requests

Transport failures return an HTTP error with a JSON body, {"error": "<code>", "message": "<sentence>"}.

CodeStatusWhen
invalid_token401No token, or an invalid, expired or revoked one. The WWW-Authenticate header points to the discovery document: sign in again.
insufficient_scope200 for tool calls, otherwise 403The tool result names the missing scope and explains how to reconnect with that permission. Other requests include the scope in WWW-Authenticate.
forbidden403Your role does not grant the operation, or you no longer belong to the workspace. The message names the missing permission.
invalid_arguments200 for tool callsThe tool result names the invalid field and accepted values or constraints. Correct the arguments and call again.
unknown_tool200 for tool callsNo tool has that name.
rate_limited200 for tool calls, otherwise 429A rate limit is reached.
temporarily_unavailable503Adrails could not complete the request. Check the operation's status before retrying a change.
result_too_large200 for tool callsThe result exceeds the response limit. Request a narrower period, selection or page. No partial figures were returned.
request_failed200 for tool argument errors; otherwise 400, 403, 413, 503Anything else, said in the message: a change or billable read without idempotencyKey, a body over 1 MB or not JSON, a browser origin that is not allowed, signing keys briefly unavailable.

Errors inside a tool

Once a tool runs, an error comes back as a tool result with isError set to true and a sentence, over a normal HTTP 200.

MessageWhy
Another call is running on this connection. Wait for it to finish, then retry with the same idempotencyKey and arguments.Calls on one connection run one at a time. Nothing ran.
This idempotency key was already used with different arguments.Use a new key for a new call.
This operation is pending or its outcome requires review. Check its status before retrying.The first call with this key did not finish. Check jobs_status with kind set to operation.
A selected resource is outside this connection's access.An accountIds value is not an ad account of the workspace.
Use this product tool’s input accountId or adAccountId selector instead of accountIds.accountIds is for agent tools only.
This proposal is no longer available to this connection.A retried proposal no longer belongs to this connection's workspace.
This result exceeds the response limit. Request a narrower period, selection or page. No partial figures are returned.The result is over 256,000 bytes.
The operation could not complete. Check its status before retrying a mutation.An unexpected failure. A change may or may not have happened: check before retrying.

Adrails' own refusals, such as a validation error, a plan limit or a role rule, come back the same way, in Adrails' words. So does a proposal refused before it is prepared: a lifetime budget, a workspace spend cap, an ad set's ID given to campaigns_duplicate_to_draft, or meta_duplicate's question about posts. The sentence is the one the Adrails agent reads in the app, and it names the tool to call next when there is one. A role rule names the permission it lacks, for example Your role can't publish drafts and launches. Ask an admin. It is checked again on every call, so a role changed since the connection was made applies at once. An ad account outside your access answers You don't have access to these ad accounts. Ask an admin.

Analysis and reporting

Reads over the connected ad accounts and the workspace's own rules. None of them changes anything.

reporting_overview

Spend, attributed revenue and named conversion events for the workspace's connected ad accounts, Meta and Google Ads alike. Without dates, each account's latest synchronized window, with entity settings and status. With entityIds, those campaigns, ad groups or ads, and for a campaign its last seven days against the seven before. On Meta, from and to together read an exact calendar period of at most 93 days, with gaps reported; compare adds the period of the same length just before it to each row, and chart draws the period day by day in the Adrails chat. Accounts in several currencies are also given as one combined row in the workspace's reporting currency, or in currency (an ISO code such as USD), the period before converted at the same rates. Store orders are read with store_revenue. Meta figures count each ad set's own attribution setting; a userStatement naming a window (7-day click only, 1-day click, without views, 1-day view, engaged view) counts Meta's purchases and revenue in it, one asking click versus view adds both windows beside Ads Manager's figure, and the result names the window. Outbound clicks and a lifetime budget's remaining amount come with each row.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
fromdateNo
todateNo
lastDaysintegerNo
accountIdsarray of stringNo
entityIdsarray of stringNo
actionTypestringNo
comparebooleanNo
chartbooleanNo
currencystringNo

performance_period

One ad account's figures for an exact date range, read from Meta or Google Ads at the account, campaign, ad set (ad group or asset group on Google) or ad level: spend, results, purchases, revenue, ROAS, cost per purchase and per result, impressions, clicks, CTR, CPC, CPM, and reach and frequency on Meta. On Meta the figures are the ones Ads Manager shows by default: each ad set's own attribution setting, purchases as its Purchases column counts them, CTR and CPC on link clicks, and archived and deleted ads included and named so. compareSince and compareUntil read a second range and give each entity's change. breakdown cuts the period by age, gender, country, placement, device or hour of the day, each slice's rates worked out from its sums, the rows sorted and capped with what was left out said; on Google Ads a placement is the network an ad ran on, countries are where people were, and region and city keep people located in a place apart from people interested in it, with the Shopify store's sales by shipping region beside a region, and parental and income cut it by parental status and household income. Google Ads also cuts by day (with each day's impression shares, to see since when a campaign is capped by budget or rank), day_of_week, click_type (the headline, a sitelink, a Shopping product), slot (top of the page or other) and conversion_lag (days from the ad to the conversion, conversions only). Google rows add the impression share family (Search, top and absolute top, lost to budget and to rank, click share, exact match, Display), all, view-through, cross-device, current-model and by-conversion-date conversions, invalid clicks, and a video's TrueView views and quartiles; when the period ends on days still filling in, the conversions by conversion date stand beside the estimate. On Google Ads, level also reads each keyword (match type, status, quality score and its three parts now and over the period, impression shares), each search_term, Performance Max's included (the keywords that matched it, where Google's match came from: the advertiser's keyword, AI Max or Performance Max, and whether a negative keyword already excludes it), each product of Shopping and Performance Max (its custom labels, category, product type, brand, channel and condition, Google's cart data where the account sends it: orders, revenue, cost of goods, gross profit and return on profit, the products bought in the same orders, the Shopify product behind the feed item and what the store's orders tied to Google bought of it, the products losing money after their spend by each source, the feed's refused products with Google's reasons, and the Merchant Center link; tag groups the products by a custom label, category, product type, brand, channel or condition), each conversion_action (what it recorded and its last day, its last conversion and tag fire ever, how it counts, the account's tracking status, an enabled purchase action silent for 7 days named as a tracking problem, beside Adrails' own Data Manager uploads of store purchases), each asset of the ads, asset groups, campaigns and account (its status, why it is limited, whether Google made it, its figures, and what Google asks to add to an asset group for its ad strength), each landing_page people landed on (the pages final URL expansion chose, Google's mobile and speed scores, and the Shopify product it shows with the orders Google's visits brought it) each placement (the sites, apps and YouTube channels Display, YouTube, Demand Gen and Performance Max ran on, the ones that look like junk said, nothing excluded) and each audience a campaign or an ad group adds (remarketing and customer lists, interests, custom and combined audiences, with whether it targets or only observes, its bid adjustment and a list's sizes on Search and Display). Dates are YYYY-MM-DD in the account's time zone, 400 days at most.

A Google campaign read adds each campaign's cart data and its new and returning customers, by Google's classification and by the store's orders tied to Google, side by side.

On Meta, the figures count each ad set's own attribution setting, as Ads Manager does. A userStatement naming a window (7-day click only, 1-day click, without views, 1-day view, engaged view) counts Meta's purchases and revenue in it, and one asking click versus view (view-through) adds both windows beside Ads Manager's figure; the result names the window. 7-day and 28-day view are not offered: Meta has returned no data for them since January 12, 2026. A userStatement asking by region or state, DMA, frequency, catalog product or customer segment cuts the period that way instead: region and DMA come without purchases, and a region sits beside the store's net sales by shipping region, matched by name within the store's countries, when a store sells for the account; frequency gives reach per bucket; product names each catalog product, the product set's purchases and the store product tied to it; customer segments are those of Advantage+ sales campaigns, and the result says when the account defines no existing customers. A read of 12 ads or fewer adds each ad's outbound and unique clicks, hook and hold rates, ThruPlays, quartile plays and Instant Experience time.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
accountIdstringYes
breakdownone of age, gender, country, region, city, placement, device, hour, parental, income, day, day_of_week, click_type, slot, conversion_lagNo
campaignIdsarray of stringNo
compareSincedateNo
compareUntildateNo
entityIdsarray of stringNo
levelone of account, campaign, adset, ad, keyword, search_term, product, conversion_action, asset, landing_page, placement, audienceYes
metricSetone of standard, additiveNo
offsetintegerNo
sincedateYes
tagstringNo
untildateYes

A read gives 40 rows by spend, or 8 per group when it compares. It says which rows of how many it gives, and the offset that reads the next ones.

When userStatement asks what moved on the ads (what moved this week, which ads are dying), performance_period and reporting_overview return the report of what moved instead: every ad of the Meta and Google Ads accounts in scope, from their latest sync, each with its ad set or ad group, grouped as spending more, spending less, stopped, dying slowly or at a low ROAS against the period before, over the period the statement names or the last 7 days. On Google Ads a Performance Max line is an asset group. Only the call's own userStatement counts, not an earlier call's.

Use metricSet: "additive" for spend, conversion, revenue and efficiency questions. Complete campaign daily data collected within 15 minutes can be reused; incomplete or stale coverage falls back to Meta. Reach and frequency may be unavailable in this mode. The default standard mode reads those metrics for the exact period.

tag groups the period's ads by a part of their names, read from the account's naming convention: a part's name (creator, concept, hook) or one of its values (ABHISHEK, 004). The naming is learned from the ad names; the parts the person named are kept per ad account in the business memory.

ads_export

A file of each account's ads over a date range, Meta's and Google Ads', as CSV, PDF and a text for Claude: the Ads Manager columns, each Meta ad's share of spend by age, gender, placement and country, and the ad text. At ad level, the text for Claude is Markdown with one section per ad: its ids, audience, copy, figures with their definitions, video retention and, once a video was analyzed in the Adrails chat, its scenes. It comes as one link per part of 200 ads. A Google Ads account gives its ads and the asset groups Performance Max has instead of ads; filters.level set to keyword, asset, product, search_term, landing_page, placement or audience gives its keywords, its assets (Performance Max's too, with their status), its Shopping and Performance Max products with their attributes, its search terms, the pages people landed on, where its ads ran or the audiences its campaigns and ad groups add, with Google's figures; filters.by a custom label (custom_label_0), category, product type or brand gives one product row per value. Rows carrying Google's cart data add Google orders, revenue, cost of goods, gross profit, margin and return on profit. On Meta, filters.by also takes region, dma, frequency, product or user_segment, each alone: region, DMA and product rows hold no purchases, and frequency rows hold reach alone. A Meta file by asset, asked as by headline, by primary text or by asset, gives each asset of the 10 ads with most spend whose texts, headlines, images or videos come in several versions, with what Meta's asset breakdown credits it. Returns the file's title, the accounts it holds, up to 5 preview rows and its file links. Nothing is read from Meta until a link is opened. By default a file holds each account's top 15 ads by spend; top asks for up to 50, and the person's words "all my ads" or "every ad", passed verbatim as userStatement, ask for every ad that spent, as in the app.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
accountIdsarray of stringNo
filtersobjectNo
kindcommentsNo
sincedateNo
topintegerNo
untildateNo

since and until are needed for a file of ads.

filters takes the columns, breakdowns, sort, levels and the attribution window the app's ad file takes. Read figures to answer a question with performance_period: ads_export always returns the file.

kind comments, or a userStatement asking for the comments, is not available yet. Meta has not approved Adrails to read the comments under ads (pages_read_user_content), so until it does the call answers that no comment can be read, names the missing permission, and returns no file. Comments stay readable in Meta Business Suite.

performance_diagnose

Compares two equal-length, non-overlapping past periods of one Meta account, from its saved snapshot: coverage, changes, facts, unknowns and what to verify next. A missing row is never counted as zero.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
languageone of fr, enYes
responseModeone of evidence, answerNo
accountIdstringYes
beforeobjectYes
afterobjectYes
campaignIdstringNo
actionTypestringNo

metrics_daily

Daily series the integrations measure: traffic, sessions, conversion rate, sales and average order value on the store side; emails received, opened and clicked on the marketing side; net profit, CPA and ROAS on the analytics side. Without metrics it returns everything measured over the period, which is how to discover the names. breakdown splits by product, traffic source or country.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
fromdateNo
todateNo
breakdownstringNo
metricsarray of stringNo

metric_compare

Compares one observed value with a positive target: signed difference, relative difference, attainment percentage, and above, below or equal. Arithmetic only.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
observednumberYes
targetnumberYes

portfolio_review

Reviews the selected accounts and campaigns against each campaign's actual objective, ad set events, budget owner and period coverage, with freshly evaluated rules. Separates provider issues, policy differences, hypotheses and unknowns, includes campaigns without findings, and gives at most three portfolio priorities. Paginated.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
languageone of fr, enYes
responseModeone of evidence, answerNo
accountIdsarray of stringNo
offsetintegerNo
limitintegerNo

budget_recommend

For one account, evaluates the campaigns or ad sets that own a budget: maintain, increase, reduce or investigate, comparing the latest two complete seven-day windows in the account's time zone. Without entityId and entityType it finds the budget owners itself. It suggests no amount.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
languageone of fr, enYes
responseModeone of evidence, answerNo
accountIdstringYes
entityIdstringNo
entityTypeone of campaign, adsetNo
limitintegerNo
offsetintegerNo

business_review

Checks a bounded business explanation or calculation, such as unit economics, revenue reconciliation or budget pacing, from explicit inputs. Every number must quote its source word for word, from the person's own statement or a tool result in this connection's history.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
languageone of fr, enYes
responseModeone of answer, evidenceNo
currencystringNo
reviewobjectYes

planning_calculate

Budget pacing, budget allocation totals or first-order acquisition unit economics, computed from the inputs given, in one currency, with their sources and periods stated in evidence. Returns the arithmetic and its limits, not a forecast.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
currencystringYes
evidencestringYes
calculationobjectYes

changes_review

Reviews the actions recorded on one account: when they were applied, their baseline, and their observations, with pending, failed and skipped kept apart from measured results. Paginated.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
languageone of fr, enYes
responseModeone of evidence, answerNo
accountIdstringYes
actionIdstringNo
limitintegerNo
offsetintegerNo

findings_review

What the rule engine found on the selected Meta and Google Ads campaigns, against the workspace's own standard. Each finding carries its evidence, snapshot date, campaign objective, currency, budget owner and classification. Filter with family, minSeverity and limit.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
familyone of creative, targeting, tracking, fatigue, healthNo
limitintegerNo
minSeverityone of low, medium, high, criticalNo

Commerce and subscriptions

Reads over the connected stores, billing and product analytics.

store_revenue

Revenue of the connected stores over a period: gross, refunded and net sales kept apart, with the order count, in each store's own currency, never converted. With ad accounts connected, it also gives MER (blended ROAS), the net sales over every ad account's spend on the same days in one currency, and the platforms' own ROAS, each part named.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
fromdateNo
todateNo

store_orders

Orders one by one, newest first: totals, financial status, fulfilment status and line count. At most 50 per call.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
fromdateNo
todateNo
financialStatusstringNo
limitintegerNo

store_customers

Customers imported from the selected Stripe or commerce connection, newest first: name, email domain, country, creation date, order count and imported lifetime spend. Full email addresses are not stored. Paginated with offset.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
limitintegerNo
offsetintegerNo
searchstringNo

store_products

Products of the connected stores: title, price range, inventory, status, type and vendor. search filters on the title.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
limitintegerNo
searchstringNo
statusstringNo

saas_performance

Stripe billing, RevenueCat revenue metrics and PostHog product events: active subscriptions, trials, normalized MRR, ARR, collected payments, refunds and daily product events, with customer and subscription counts by billing cadence when customer-level data is available. Each source and currency stays separate.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
fromdateNo
todateNo

Creatives

Reads over creative assets and their results. None of them uploads or launches anything.

creative_insights

Groups Meta ads by the image or video asset they use, across ads and accounts: performance, winners, fatigue, repeated use, and missing metadata such as angle, offer, product, persona or creator.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
accountIdsarray of stringNo
limitintegerNo

creative_market_evidence

Per-ad performance, copy and media identifiers, and the parent ad set's configured countries, with the snapshot period and freshness. It is not a breakdown of delivery by country. For 1 to 3 adIds, whatever their age or status, it adds each ad's live detail: video retention, plays, hook and hold rates, placements, the video's scenes once it was analyzed in the Adrails chat, and, with Triple Whale connected, the orders, revenue and ROAS Triple Whale credits to the ad, beside Meta's and never added to them. For an ad with several primary texts, headlines, images or videos, it gives each one's spend, CTR, purchases, CPA and ROAS from Meta's asset breakdown: approximate per asset, not adding up to the ad's total. A named ad's detail adds its outbound and unique clicks and Instant Experience time. Past three, the answer names the next ones to read in another call.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
accountIdsarray of stringNo
adIdsarray of stringNo
includeone of pictures, commentsNo
limitintegerNo

For the first three adIds, include: "comments" reads the comments under each ad's Facebook and Instagram posts, when the Meta connection holds the comment permissions; without them the answer says which one is missing. Meta has not approved Adrails for these permissions yet, so comments are not available yet. include: "pictures" shows the ads' images to the Adrails chat only: an MCP client gets none.

creative_review

Reviews the creative evidence of selected ads: available copy, asset IDs, configured goal, period and limits. With focus set to copy_test it proposes one text-order test; with market_transfer it keeps the source asset and copy for the destination named. It prepares no campaign.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
languageone of fr, enYes
responseModeone of evidence, answerNo
focusone of review, copy_test, market_transferNo
destinationstringNo
accountIdsarray of stringNo
adIdsarray of stringNo
limitintegerNo
offsetintegerNo

drive_folder

Reads a Google Drive folder of creatives shared with the workspace's Google address: every image and video down to three levels, with its path, ratio, pixel size, duration and file size, and how Adrails would group them into ads by default, each top-level file as one ad and each subfolder as one ad with the same creative in several ratios. Without folderId, finds shared folders whose name contains query. A folder that is not shared with the address cannot be read.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
adPerFilebooleanNo
folderIdstringNo
querystringNo

Campaign setup and research

What a new campaign needs, read from the accounts and the platforms.

site_brief

Reads the public website or store a launch request names, before launch_brief: the page and, for a Shopify store, its public product list. Returns the brand, what the site says it sells, its declared language and currency, the first products with prices, short value propositions and the main links; then the launch_brief values this settles (destination, purpose, copy to write, a proposed campaign name, the Sales objective when products were found, the declared language) and, for a Google Ads account, suggested Search keywords, headlines of 30 characters and descriptions of 90 for google_ads_build. It never settles the account, the budget, the countries, the dates, the Page or the pixel. Only public addresses are read: private and local networks are refused, the read stops at 8 seconds, 1.5 MB and 3 redirects.

Access: read, adrails:read, role allows Drafts and launches: create.

InputTypeRequired
urlstringYes

launch_brief

The first step of any new Meta launch. Pass only what the person said or chose; it returns what a clean launch still needs, as questions with options: the ad account, where the ads go, then objective, pixel and event, countries, languages, budget, dates, Page, EU beneficiary, link and copy. The EU beneficiary is asked once per ad account and kept for its next launch or edit. When nothing is missing it returns the complete brief for campaigns_launch. A campaign alone (campaignOnly) or a launch without creatives yet (source none) asks only what that draft holds, and ends in a draft saved in Campaigns rather than ads on Meta. With source posts, posts the Page or its Instagram account already published are boosted, one ad each, named in metaSettings.ad.existingPosts by the ids targeting_options page-post returns or by their links, as Ads Manager's Use existing post: nothing is uploaded, and each ad keeps its post's likes and comments. They go into an ad set that runs, or a new ad set or campaign for Engagement, Traffic or Sales. A Facebook post boosted for clicks needs a link of its own; an Instagram post takes the destinationUrl behind its button. A Leads launch on an instant form takes the form's id from userStatement or from metaSettings.ad.leadFormId, as targeting_options lead-form lists a Page's forms, and asks no pixel: Meta counts the lead on the form. Adrails keeps the brief's answers for this connection, so the server counts the call as a change.

Access: change, adrails:read, role allows Drafts and launches: create.

InputTypeRequired
adPerFilebooleanNo
adNameTemplatestringNo
adSetNamestringNo
bidStrategyone of Cost cap, Bid cap, Minimum ROASNo
bidEvidencestringNo
bidAmountnumberNo
interestsarray of stringNo
customAudiencesarray of stringNo
excludedAudiencesarray of stringNo
placementsarray of stringNo
callToActionstringNo
publishAsone of draft, paused, live, uploadNo
ageMinintegerNo
ageMaxintegerNo
genderone of Men, WomenNo
campaignBudgetbooleanNo
startAtstringNo
accountIdstringNo
budgetCurrencystringNo
headlinestringNo
primaryTextstringNo
descriptionstringNo
copiesarray of objectNo
beneficiarystringNo
campaignNamestringNo
campaignOnlybooleanNo
conversionEventstringNo
copyModeone of shared, per_adNo
copyone of generate, reuse, providedNo
countriesarray of stringNo
dailyBudgetnumberNo
destinationUrlstringNo
urlParametersstringNo
folderIdstringNo
driveFileIdsarray of stringNo
creativeCountintegerNo
creativeKindone of image, videoNo
creativeOrderone of latestNo
creativeNamesarray of stringNo
adSetGroupsobjectNo
settingsFromAdSetstringNo
excludeFoldersarray of stringNo
onlyFoldersarray of stringNo
includeFoldersarray of stringNo
formatsone of send_missing, as_isNo
languagesarray of stringNo
layoutone of one_ad_set, ad_set_per_ad, campaign_per_ad, ad_set_per_folderNo
objectiveone of Sales, Traffic, Leads, Engagement, Awareness, App promotionNo
pageIdstringNo
pixelIdstringNo
purposestringNo
schedulestringNo
imageUrlsarray of URLNo
startDatedateNo
endDatedateNo
sourceone of drive_folder, images, reuse, none, postsNo
targetstringNo
metaSettingsobjectNo

campaigns_setup

Lists the selected Meta accounts with their accountId, currency, snapshot freshness and the Page IDs, pixel IDs and image hashes available. These are candidates, not confirmed choices. Without an account selection it returns a picker rather than choosing, limited to the accounts of platform when the request is about one.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
accountIdsarray of stringNo
platformone of meta, google_adsNo

campaigns_structure

How an account's campaigns are built, from the last sync, on either platform: campaigns with type, status, budget and bidding; ad sets or ad groups with their keywords (match type, status, quality score, review, spend and conversions over the sync's days, the ones that spent most kept on a large campaign); ads with format, copy, final URL and review. On Google Ads it also gives each campaign's negative keywords, the shared negative keyword lists it uses, the keywords, Performance Max assets and extensions Google disapproved or limits, with the policy it names, and its controls: the portfolio strategy it bids with and the target actually in force with what sets it, Google's suggested budget, the placement exclusion and brand lists it uses, labels, ad schedule and device bid adjustments. At account level: the portfolio strategies, every shared list with its first entries, what the whole account excludes, and its user lists with their sizes. For Shopping ad groups and Performance Max asset groups, the products their listing groups include and exclude, by brand, category, product type, custom label or item id. On Meta, the custom conversions the ad sets optimise for, with their rule, event, default value, datasets and last event; one without an event for a week is called silent. Read it before building under or editing what exists, and use its IDs. campaignId narrows it to one campaign.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
accountIdstringNo
campaignIdstringNo
campaignNamestringNo

A Google Ads account's pictures (asset ID, address, size: the newest that fit with the account's count, or those whose name holds the words of search), its YouTube videos, its audience lists and its audiences. Pictures and videos are reused by ID in google_ads_build; audience lists are what an ad group's audienceLists name, and audiences name a Performance Max audience signal.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
accountIdstringYes
searchstringNo

google_keyword_planner

Google's Keyword Planner for a Google Ads account. With mode set to volumes, monthly searches and the top-of-page bid range of keywords; with ideas, keywords suggested by a few words or an https url. Counts are for the given countries and language, or everywhere. Keywords Google gives no figure for are listed apart.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
accountIdstringYes
countriesarray of stringNo
keywordsarray of stringNo
languagestringNo
modeone of volumes, ideasYes
urlURLNo

editor_settings_reference

Every setting of the Meta campaign editor that launch_brief takes in metaSettings, with its allowed values and format: up to five primary texts and headlines, places with a radius, pins and excluded places, detailed targeting, Advantage+ audience, conversion locations such as calls, apps, profiles and instant forms with the form a Leads ad opens, special ad categories, lifetime budgets, spend and frequency caps, attribution, the button and text optimization. A launch applies them over what it proposes, and the editor's own checks judge the result. tool returns another tool's format instead, one at a time so each fits one answer: meta_edit's lists, meta_audience_create's audience or lead_form_create's form.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
toolstringNo

targeting_options

Looks up the real Meta or Google Ads IDs of custom audiences, interests, languages or locations, and on Meta of detailed targeting (behaviors and demographics), saved audiences, catalogs and their product sets, lead forms, instant experiences, Page events, a Page's latest posts, and the apps the account can advertise with their stores and app events. A Meta custom audience comes with its kind, Meta's size estimate, retention, state and creation date. A Page or a catalog lookup names the Page or catalog it reads. Candidates, not confirmed choices.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
platformone of meta, google_adsYes
accountIdstringYes
kindone of app, catalog, custom-audience, detailed, instant-experience, interest, language, lead-form, location, page-event, page-post, product-set, saved-audienceYes
querystringNo

audience_estimate

Estimates Meta reach for proposed targeting with the account's audience service. An estimate, not measured performance.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
accountIdstringYes
ageMinimumintegerYes
ageMaximumintegerYes
countriesarray of stringNo
gendersarray of 1 or 2No
interestsarray of objectNo
locationsarray of objectNo
languagesarray of objectNo
customAudiencesarray of objectNo

Advertising changes

Every tool here but actions_recent prepares a proposal: the exact change, waiting for your approval in Adrails. See Approving a proposal.

actions_recent

Recent proposed and applied actions: IDs, evidence, execution state, whether undo is available, and 24-hour, 3-day and 7-day observations. At most 10 per call, paginated with offset. By default, returns supporting evidence without displaying a journal table. Set showTable: true when the user explicitly requests the history table; actions prepared through this connection then carry their Adrails review link. For performance questions, cite relevant applied changes in words and continue the period comparison. With since and accountIds it adds each account's own log, Meta's activity log or Google Ads' change history (the last 30 days, as Google keeps them: who changed what in Google Ads, Editor, a script, a rule or Google's auto-applied recommendations), as one report whose CSV and PDF over all of them come as file links; by keeps one person's changes: me for the person who connected the platform, others for everyone else, or a name, an email address on Google Ads.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
accountIdsarray of stringNo
limitintegerNo
offsetintegerNo
sideone of adrails, metaNo
bystringNo
campaignIdsarray of stringNo
showTablebooleanNo
sincestringNo
untilstringNo

campaigns_pause

Pauses a campaign, ad group or ad on Meta or Google Ads, by the ID an earlier read returned.

Access: proposal for approval, adrails:actions:prepare, role allows Agent chats and actions: create.

InputTypeRequired
accountIdstringYes
entityIdstringNo
entityIdsarray of stringNo
entityTypeone of campaign, ad_group, adYes
reasonstringYes

Use entityId for one entity or entityIds for up to 40 on the same account. The approval lists the entire selection. Bulk changes keep a result for each entity; review remaining changes again if a write fails.

campaigns_set_status

Pauses or resumes one campaign, ad group or ad on Meta or Google Ads. Adrails reads the platform again before applying, refuses a concurrent change, and measures the result after 24 hours, 3 days and 7 days.

Access: proposal for approval, adrails:actions:prepare, role allows Agent chats and actions: create.

InputTypeRequired
accountIdstringYes
entityIdstringNo
entityIdsarray of stringNo
entityTypeone of campaign, ad_group, adYes
reasonstringYes
statusone of ACTIVE, PAUSEDYes

Use entityId for one entity or entityIds for up to 40 on the same account. The approval lists the entire selection. Bulk changes keep a result for each entity; review remaining changes again if a write fails.

campaigns_change_budget

Raises or lowers a campaign or ad group daily budget by an amount or a percentage, or sets it to an amount (unit to), at most 30% in one change unless the person gave that amount: pass their words verbatim as userStatement, and an amount they wrote there with its currency or the words that set a budget (set TOF to $900 a day) applies as given, within the workspace's caps. On Meta the budget is changed where it lives: a campaign whose ad sets hold their own budgets is changed on its one ad set, or the answer names its ad sets to choose from; an ad set under a campaign budget has none of its own. A lifetime budget is not changed, and the answer says so before any proposal. An increase shows on its card whether measured spend and results back it. Google Ads keeps budgets on campaigns and refuses a budget shared between campaigns.

Access: proposal for approval, adrails:actions:prepare, role allows Agent chats and actions: create.

InputTypeRequired
accountIdstringYes
directionone of increase, decreaseNo
entityIdstringNo
entityIdsarray of stringNo
entityTypeone of campaign, ad_groupYes
reasonstringYes
unitone of amount, percent, toYes
valuenumberYes

Use entityId for one entity or entityIds for up to 40 on the same account. The approval lists the entire selection. Bulk changes keep a result for each entity; review remaining changes again if a write fails.

campaigns_create_draft

A new Meta campaign with one website ad set and one image ad, for a standard Sales, Leads or Traffic objective, using an image already uploaded to the account (imageHash). Approval starts the build, and everything is created paused.

Access: proposal for approval, adrails:actions:prepare, role allows Drafts and launches: create.

InputTypeRequired
accountIdstringYes
namestringYes
objectiveone of Sales, Traffic, LeadsYes
currencystringYes
dailyBudgetnumberYes
countriesarray of stringYes
ageMinintegerYes
ageMaxintegerYes
startAtstringYes
endAtstringYes
placementsone of feeds, automaticYes
specialAdCategoryNoneYes
facebookPageIdstringYes
pixelIdstringNo
conversionEventone of Purchase, Lead, Complete_registration, Add_to_cartNo
beneficiarystringYes
destinationUrlURLYes
callToActionone of Learn more, Shop now, Sign up, Contact us, Get offer, Book nowYes
imageHashstringYes
headlinestringYes
primaryTextstringYes
descriptionstringNo
reasonstringYes

campaigns_launch

Launches the ads of a complete launch_brief: where the ads go, settings, copy and every creative. After approval Adrails sends the Drive files or images to the ad account, then builds the campaign, ad sets and ads, all paused. For a campaign alone or a brief without creatives, the approval saves a draft in Campaigns instead and nothing is sent to Meta. A brief with source posts is one approval that reads the posts and the ad set again, then creates the ads paused on the posts, kept with their likes and comments; its undo deletes what it created while it is still paused. A launch saved as a draft uploads its files to the ad account's media library and creates no campaign, ad set or ad until the draft is published. With publishAs upload, the approval sends the files to the ad account's media library alone and keeps them for the next launch: no campaign, ad set, ad or draft is created. placements takes the placements the person named, such as Instagram Reels or Stories; without them the launch uses Advantage+ placements. A setting the launch cannot apply is named on the proposal as not applied.

Access: proposal for approval, adrails:actions:prepare, role allows Drafts and launches: create.

InputTypeRequired
adPerFilebooleanNo
adNameTemplatestringNo
adSetNamestringNo
bidStrategyone of Cost cap, Bid cap, Minimum ROASNo
bidEvidencestringNo
bidAmountnumberNo
interestsarray of stringNo
customAudiencesarray of stringNo
excludedAudiencesarray of stringNo
placementsarray of stringNo
callToActionstringNo
publishAsone of draft, paused, live, uploadNo
ageMinintegerNo
ageMaxintegerNo
genderone of Men, WomenNo
campaignBudgetbooleanNo
startAtstringNo
accountIdstringNo
budgetCurrencystringNo
headlinestringNo
primaryTextstringNo
descriptionstringNo
copiesarray of objectNo
beneficiarystringNo
campaignNamestringNo
campaignOnlybooleanNo
conversionEventstringNo
copyModeone of shared, per_adNo
copyone of generate, reuse, providedNo
countriesarray of stringNo
dailyBudgetnumberNo
destinationUrlstringNo
urlParametersstringNo
folderIdstringNo
driveFileIdsarray of stringNo
creativeCountintegerNo
creativeKindone of image, videoNo
creativeOrderone of latestNo
creativeNamesarray of stringNo
settingsFromAdSetstringNo
excludeFoldersarray of stringNo
onlyFoldersarray of stringNo
includeFoldersarray of stringNo
formatsone of send_missing, as_isNo
languagesarray of stringNo
layoutone of one_ad_set, ad_set_per_ad, campaign_per_adNo
objectiveone of Sales, Traffic, Leads, Engagement, Awareness, App promotionNo
pageIdstringNo
pixelIdstringNo
purposestringNo
schedulestringNo
imageUrlsarray of URLNo
startDatedateNo
endDatedateNo
sourceone of drive_folder, images, reuse, none, postsNo
targetstringNo

campaigns_launch_activate

Switches on what a launch created: its ads, and the ad sets and campaign above them when they are paused, also when the launch partly failed or its drafts were published from Campaigns. The proposal lists every budget that starts spending, and the workspace's spend caps hold. If Meta stops partway, the answer names what is already on.

Access: proposal for approval, adrails:actions:prepare, role allows Agent chats and actions: create.

InputTypeRequired
accountIdstringYes
launchIdstringYes

campaigns_duplicate_to_draft

Copies a Meta or Google Ads campaign into a draft in Adrails, with its targeting, bidding, budget, extensions, keywords and ads as the latest sync reads them. On Meta each copied ad uses its source ad's existing post, as Ads Manager's Use existing post, so the copy keeps the same posts with their likes and comments, and the card lists each post id. targetAccountId copies the campaign into another Meta ad account of the workspace, in that account's currency: images are copied and videos sent again there, custom audiences stay behind and the proposal says which, and keepPosts keeps each ad on its source's post when that account can use the same Page. excludeAds leaves ads out by number, name or id; startDate, startTime and timeZone schedule the start. On Meta, variants replaces one source ad with 3 to 5 copy variants. targetDailyBudget sets the copy's daily budget when the person gave one. changes makes one copy per entry, each with its own daily budget, name, countries, ages, gender, Advantage+ audience, custom audiences by name and bid, planned as meta_edit plans an edit and checked as the Campaigns editor checks a row; the proposal lists every change against the source. An ad set's or an ad's id is refused: those are copied with meta_duplicate. It needs fresh source data. Approval saves the draft only: nothing reaches the platform until the draft is published from Campaigns, paused.

Access: proposal for approval, adrails:actions:prepare, role allows Drafts and launches: create.

InputTypeRequired
accountIdstringYes
entityIdstringNo
excludeAdsarray of stringNo
namestringNo
reasonstringNo
sourceAdIdstringNo
startDatestringNo
startTimestringNo
targetAccountIdstringNo
changesarray of objectNo
targetDailyBudgetnumberNo
keepPostsbooleanNo
timeZonestringNo
variantsarray of objectNo

meta_archive

Archives Meta campaigns, ad sets or ads of one level, up to 40 in one proposal. The proposal lists everything it stops, the ad sets and ads underneath included, by name with the counts. Archiving stops delivery and keeps every result in Meta's reports; Adrails saves the full configuration first. Each entity is read again before it is archived, and one changed since is left as it is.

Access: proposal for approval, adrails:actions:prepare, role allows Agent chats and actions: create.

InputTypeRequired
accountIdstringYes
entityIdstringNo
entityIdsarray of stringNo
entityTypeone of campaign, ad_group, adYes
reasonstringYes

meta_delete

Deletes Meta campaigns, ad sets or ads of one level for good, up to 40 in one proposal. The proposal says it is irreversible on Meta, lists everything deleted with them, and Adrails saves a final snapshot of each first. With entityType custom_audience it deletes custom audiences of the ad account by id instead, each named on the proposal with its kind and size; ad sets that use one stop reaching it, and a customer list Adrails fills stops being sent. Meta keeps no archive of an audience, so meta_archive does not take them. Prefer meta_archive unless deleting was asked for explicitly. On a Google Ads account, it and meta_archive remove the campaigns, ad groups or ads instead: Google Ads has no archive, and a removed one never serves again.

Access: proposal for approval, adrails:actions:prepare, role allows Agent chats and actions: create.

InputTypeRequired
accountIdstringYes
entityIdstringNo
entityIdsarray of stringNo
entityTypeone of campaign, ad_group, ad, custom_audienceYes
reasonstringYes

meta_edit

Changes what a Meta account already runs, shown before and after, and never a budget or a spending limit (use campaigns_change_budget): an ad's copy, button, link, URL parameters, name, Page or Instagram account (a copy change makes a new creative, as Meta requires); an ad set's countries (replaced, or added to the current ones with addCountries), ages, gender, interests, placements, dates, conversion event, bid and name; a campaign's name, end date and, when it holds the budget, its bid. A bid (highest volume, cost cap, bid cap or minimum ROAS, with its target) is set at the level that holds the budget. Several entities of one level take the same change in one proposal, an ad set's audience, placements, dates and bid included, each planned from what Meta holds; changes.rename replaces a text in each name, and an entity whose name lacks it is left out and listed. Meta checks the exact change when it is prepared, and each change is sent once when it is applied. Targeting, placement changes and any new creative on an ad that has run always wait for approval. The proposal says what it resets: an ad set's learning, naming it when it is out of learning, an ad's likes and comments, and Meta's review.

Access: proposal for approval, adrails:actions:prepare, role allows Agent chats and actions: create.

InputTypeRequired
accountIdstringYes
changesobjectYes
entityIdstringNo
entityIdsarray of stringNo
entityTypeone of campaign, ad_group, adYes
reasonstringYes

meta_audience_create

Creates Meta custom audiences on the ad account after approval, as Ads Manager's Create audience does:

  • Website: all visitors, visitors of pages whose address contains a fragment, or people who sent a pixel event (Purchase, AddToCart, InitiateCheckout, ViewContent and the other standard events), up to 180 days.
  • Video viewers: people who watched 3 seconds, a ThruPlay, or 25, 50, 75 or 95 percent of chosen videos, or of the videos of a campaign's ads (campaignId), up to 365 days.
  • Instagram account and Facebook Page engagers: everyone who engaged, visited, engaged with a post or ad, sent a message or saved; on a Page also clicked a call-to-action button, up to 730 days.
  • Lead form: people who opened, opened but did not submit, or submitted chosen forms of a Page, up to 90 days.
  • Instant Experience: people who opened one or clicked a link in it, up to 730 days.
  • Messages: people who messaged the Page, or the Instagram account; Meta takes one of the two per audience.
  • Customer list from the connected Shopify store: the customers who accept marketing, or every customer. Adrails reads them from Shopify, normalizes and hashes each email, phone, name and address with SHA-256 by Meta's rules, and sends only the hashes, in batches of 10,000; it keeps counts, never the customers. valueBased sends each customer's total spent, for a value-based lookalike, and sync adds the store's new and changed customers every day and takes out those who stopped accepting marketing. The proposal says about how many customers are sent, never who. A list from a file is uploaded in the Campaigns editor only.
  • Lookalike of any custom audience but a lookalike, in one or several countries, at 1 to 10 percent, as one audience or split in up to six bands (percents [1,2,3] makes 0-1%, 1-2% and 2-3%).

Its audience takes the format editor_settings_reference returns with tool meta_audience_create. A customer list needs Meta's Custom Audience Terms accepted on the ad account: when they are not, the result says so with Meta's link and nothing is prepared. An audience spends nothing; once created, its id is used in a launch or an edit like any custom audience. A Meta refusal is returned in Meta's words with its link.

Access: proposal for approval, adrails:actions:prepare, role allows Agent chats and actions: create and Ad sets / ad groups: create.

InputTypeRequired
accountIdstringYes
audienceobjectYes

meta_duplicate

Copies a Meta ad set with its ads, or ads, into a draft in Adrails under the same parent or a named one. posts is asked first: same keeps each ad on its source's post, with its likes and comments; new builds each ad as a new post, which Meta reviews. Each copied ad keeps its source's creative, targeting, exclusions, placements and budget come from the source, and no results are copied. changes makes one copy per entry, each with its own daily budget, name, countries, ages, gender, Advantage+ audience, custom audiences by name and bid, planned as meta_edit plans an edit and checked as the Campaigns editor checks a row; the proposal lists every change against the source. targetAccountId copies into a campaign or an ad set of another Meta ad account of the workspace, named with destinationId, as a campaign copy goes there: in that account's currency, with a daily budget given there when it bills in another one, images copied and videos sent again on approval, custom audiences left behind and said, and each ad on its source's post only when that account can use the same Page. Approval saves the draft only: it is published from Campaigns, paused.

Access: proposal for approval, adrails:actions:prepare, role allows Drafts and launches: create.

InputTypeRequired
accountIdstringYes
destinationIdstringNo
changesarray of objectNo
copiesintegerNo
endDatestringNo
entityIdstringNo
entityIdsarray of stringNo
entityTypeone of ad_group, adYes
excludeAdsarray of stringNo
namestringNo
postsone of same, newNo
reasonstringNo
startDatestringNo
startTimestringNo
targetAccountIdstringNo
timeZonestringNo

meta_swap_creative

Replaces the image or video of one Meta ad that already runs with a file attached in the conversation or picked in Google Drive, keeping its copy, button, link and identity. After approval the file is sent to the ad account, a video is processed by Meta, and the ad is pointed at a new creative; a file Meta refuses leaves the ad as it was.

Access: proposal for approval, adrails:actions:prepare, role allows Agent chats and actions: create.

InputTypeRequired
accountIdstringYes
adIdstringYes
filestringNo
allPlacementsbooleanNo
reasonstringYes

campaigns_split_test

A split test from an ad set or ad that already runs, which stays variant A, with one to three new variants that each change only the tested variable. Approval creates the test with its new variants paused; launching it is a separate approval on the test's page in Adrails.

Access: proposal for approval, adrails:actions:prepare, role allows Split tests: create.

InputTypeRequired
accountIdstringYes
durationDaysintegerNo
entityIdstringYes
metricone of cpa, conversion_rateNo
namestringYes
reasonstringYes
sharesarray of integerNo
variableone of audience, placements, bidding, ad_text, search_ad_text, creative, google_creativeYes
variantsarray of objectYes

Creates Google Ads: a new Search, Display, Demand Gen, Performance Max or Shopping campaign with its ad groups, keywords and ads or its asset groups; new ad groups under an existing campaign; or new ads in an existing ad group. Google validates the request on approval, and everything is created paused.

Access: proposal for approval, adrails:actions:prepare, role allows Drafts and launches: create.

InputTypeRequired
accountIdstringYes
adGroupsarray of objectNo
assetGroupsarray of objectNo
campaignobjectYes
reasonstringYes

Changes what a Google Ads account already has: ad texts, paths and final URLs, keywords (added, paused, switched on or removed), names, campaign dates, target CPA or ROAS, asset group texts, extensions, places, languages, search themes and audience signals, and a campaign's ad schedule and device bid adjustments. Google validates every change when it is prepared and again when it is applied, all or nothing. A target is set only on the strategy that has one; a change of strategy is its own proposal. Taking out a campaign's last place or language is refused, and a new end date on a campaign that ended says it runs again, with the budget it spends. Removing a campaign, ad group or ad goes through meta_delete, which removes on Google Ads. An ad schedule is given whole, one line per slot in the account's time zone (mon-fri 09:00-18:00 +20, [] for all hours), and device bids as mobile -100, tablet +20; it is built from what Google holds when it is prepared, read again before it is applied, read back after, and actions_undo puts the previous schedule back while Google still holds what was written. Hours go in 15-minute steps, at most 6 slots a day; a bid adjustment Smart Bidding ignores is refused in words, a -100% device exclusion is not.

Access: proposal for approval, adrails:actions:prepare, role allows Agent chats and actions: create.

InputTypeRequired
accountIdstringYes
changesarray of objectYes
reasonstringYes

findings_apply

Applies the fixes that findings of one account propose for UTM tags, enhancements, placements or tracking. On Meta they go to new paused copies of the campaigns; on Google Ads they edit the live campaigns.

Access: proposal for approval, adrails:actions:prepare, role allows Drafts and launches: update.

InputTypeRequired
findingIdsarray of stringYes
reasonstringYes

campaigns_publish_draft

Publishes a campaign draft saved in Adrails, by its draftId from campaign_drafts, once approved: every campaign, ad set and ad it holds is created on Meta paused, so nothing spends until switched on. The draft must be validated. Launches approved in a conversation publish on their own.

Access: proposal for approval, adrails:actions:prepare, role allows Agent chats and actions: create.

InputTypeRequired
draftIdstringYes

campaigns_delete_draft

Deletes one campaign draft saved in Adrails, by its draftId from campaign_drafts, once approved in Adrails. Nothing changes on Meta and nothing spends. actions_undo puts the draft back.

Access: proposal for approval, adrails:actions:prepare, role allows Drafts and launches: delete and Agent chats and actions: create.

InputTypeRequired
draftIdstringYes

actions_undo

Undoes an applied, reversible action, only while the platform still matches the state Adrails wrote. A later direct change is never overwritten.

Access: proposal for approval, adrails:actions:prepare, role allows Agent chats and actions: create.

InputTypeRequired
actionIdstringYes

Campaign drafts, templates and media

The campaign editor's drafts, templates and media. Listing reads; everything else changes the workspace without an approval step, and launches nothing.

campaign_drafts

Lists, saves, validates or deletes the workspace's campaign drafts. save takes the Adrails campaign source in source. Publishing goes through campaigns_publish_draft and its approval.

Access: list: read, adrails:read, role allows reading it; save: change, adrails:campaigns:write, role allows Drafts and launches: create; validate: change, adrails:campaigns:write, role allows reading it; delete: change, adrails:campaigns:write, role allows Drafts and launches: delete.

OperationInputTypeRequired
listadAccountIdstringNo
listcampaignClientIdstringNo
savedraftIdstringNo
saveadAccountIdstringYes
savesourceobjectYes
validatedraftIdstringYes
deletecampaignClientIdsarray of stringYes

campaign_templates

Lists, creates, updates or deletes reusable campaign templates, with the template content in payload.

Access: list: read, adrails:read, role allows reading it; create: change, adrails:campaigns:write, role allows Drafts and launches: create; update: change, adrails:campaigns:write, role allows Drafts and launches: update; delete: change, adrails:campaigns:write, role allows Drafts and launches: delete.

OperationInputTypeRequired
listchannelone of Meta Ads, Google Ads, TikTok AdsNo
listviewone of campaigns, adsets, adsNo
createnamestringYes
createchannelone of Meta Ads, Google Ads, TikTok AdsYes
createpayloadobjectYes
createviewone of campaigns, adsets, adsYes
updatenamestringYes
updatechannelone of Meta Ads, Google Ads, TikTok AdsYes
updatepayloadobjectYes
updatetemplateIdstringYes
deletetemplateIdstringYes

campaign_media

Lists an account's Meta or Google Ads images and videos. upload sends nothing to the ad account: an AI client never sends a file there. It returns the Adrails link where you upload the file yourself, in Campaigns, with Upload media in the campaign editor, as every other change from an AI client is approved in the browser.

Access: list: read, adrails:read, role allows reading it; upload: change, adrails:campaigns:write, role allows Creatives and media: create.

OperationInputTypeRequired
listplatformone of meta, google_adsYes
listaccountIdstringYes
listkindone of image, videoNo
uploadplatformone of meta, google_adsYes
uploadaccountIdstringYes
uploadfileNamestringYes
uploadmimeTypeone of image/png, image/jpeg, image/gifYes
uploadbase64stringYes

Accounts and integrations

Connected ad accounts and data sources. Credentials are never asked for or returned: connecting and reconnecting go through a setup link you open in Adrails.

accounts_list

Connected ad accounts with platform, currency, time zone, last snapshot and whether they are enabled. 100 per page: pass nextCursor as after.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
afterstringNo

accounts_update

Enables or disables an ad account in the workspace. Disabling stops its polling and hides its data; it does not pause any ad.

Access: change, adrails:integrations:manage, role allows Ad accounts: update.

InputTypeRequired
accountIdstringYes
enabledbooleanYes

integrations_status

What the workspace has connected, what each source can do, and how fresh each of its data streams is.

Access: read, adrails:read, role allows reading it.

No inputs.

integrations_catalog

The providers Adrails can connect: Meta and every registered integration, with how each authenticates, what it provides and the fields its connection asks for.

Access: read, adrails:read, role allows reading it.

No inputs.

integrations_detail

One connection's imported data coverage, sync streams and trend. For a Meta connection: its profile name, token expiry, scopes, last error and up to 100 ad accounts.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
connectionIdstringYes

integrations_connect

Creates a setup link to connect a provider named as integrations_catalog names it. The link is valid for 10 minutes and usable once, by you, signed in to Adrails as an owner or admin of the connection's workspace. You authorize the provider or enter its credentials there.

Access: change, adrails:integrations:manage, role allows Integrations: create.

InputTypeRequired
providerstringYes

integrations_update

Creates a setup link, on the same terms, to reconnect an existing connection and refresh its credentials or access.

Access: change, adrails:integrations:manage, role allows Integrations: update.

InputTypeRequired
connectionIdstringYes

integrations_sync

Queues a synchronization of one connection. For Meta, it refreshes the connection's enabled accounts, up to 10; beyond that, use accounts_sync per account. A queued sync is not fresh data yet.

Access: change, adrails:integrations:manage, role allows Integrations: manage.

InputTypeRequired
providerstringYes
connectionIdstringYes

integrations_disconnect

Disconnects one connection: Adrails revokes it and stops importing its data. Connecting again needs the provider's authorization.

Access: change, adrails:integrations:manage, role allows Integrations: delete.

InputTypeRequired
providerstringYes
connectionIdstringYes

accounts_sync

Queues a refresh of one Meta or Google Ads account. The refresh runs after the call returns and changes no campaign or spend. A queued refresh does not replace an analysis: answer from usable period data already read and cite its timestamp. If no usable data exists for the requested period, explain the gap. The tool does not schedule a follow-up analysis.

Access: change, adrails:integrations:manage, role allows Ad accounts: manage.

InputTypeRequired
accountIdstringYes

Leads

The leads of Meta instant forms: how many came and from where, the leads themselves as a file, a new instant form, and the Google Sheets they are sent to. What a lead wrote (a name, an email, a phone, an answer) is never in a result: the leads leave as the Leads tab's CSV, behind a link signed for the connected person. Reading leads needs the leads_retrieval and pages_manage_ads permissions on the Meta connection; without them, or without the Page in a business connection, a result says what grants them, as the Leads tab does.

leads_read

Counts the leads of a Meta campaign, ad set, ad or instant form from since to until, in the ad account's days: the total, by day, by form, by ad set and by ad, with the address of the Leads tab. Meta is asked for each lead's id, time and ad alone. The leads themselves (when each came, every answer, the form and the ad) are the CSV at file, signed for the connected person, valid for one hour and opened once signed in to Adrails, read from Meta at the click; a role that cannot read reports gets the counts alone.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
accountIdstringYes
scopeone of campaign, adset, ad, formYes
idstringYes
sincedateYes
untildateYes

lead_form_create

Prepares an instant form on a Facebook Page from form, the spec of the Campaigns editor's form builder: its name, prefilled questions (full name, email, phone and the others Meta offers), short answers, multiple choice questions to qualify, appointments, an intro, the privacy policy, consent checkboxes, the completion screen, higher intent and who may open it. editor_settings_reference lists the format with tool lead_form_create. Meta's API takes no conditional or disqualifying answer and no ending per answer. After approval the form is created on the Page and selected for the launch brief this connection prepares on that Page. Meta keeps every form: it can be archived in Meta, not deleted. It spends nothing.

Access: proposal for approval, adrails:actions:prepare, role allows Agent chats and actions: create and Campaigns: create.

InputTypeRequired
accountIdstringYes
pageIdstringYes
formobjectYes

lead_sheet_sync_start

Prepares sending the leads of a Meta campaign, ad set or ad to a new Google Sheet in the connected person's own Drive, every 2 minutes, as the Leads tab's sync does. from adds the leads since that day (Meta keeps 90 days); google picks one of the person's Google sign-ins. Without a Google sign-in that can create the sheet, the result is the Adrails sign-in link and nothing is prepared. After approval Adrails creates the sheet with its header; it keeps lead ids and times, not what a lead says.

Access: proposal for approval, adrails:actions:prepare, role allows Agent chats and actions: create and Integrations: update.

InputTypeRequired
accountIdstringYes
scopeone of campaign, adset, adYes
idstringYes
fromdateNo
googlestringNo

lead_sheet_sync_status

The Google Sheets leads are sent to in the workspace's accounts, each with its syncId, the campaign, ad set or ad it follows, the sheet's link, the leads sent and the last error, and the connected person's Google sign-ins, with the sign-in link when none can create a sheet. A sheet opens for whoever its owner shared it with in Google.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
accountIdstringNo

lead_sheet_sync_stop

Prepares stopping one Google Sheet sync, by the syncId lead_sheet_sync_status lists. After approval no new lead is added; the sheet and its rows stay.

Access: proposal for approval, adrails:actions:prepare, role allows Agent chats and actions: create and Integrations: update.

InputTypeRequired
syncIdstringYes

Automations

The workspace's automations and the channels they post to.

An automation stopped after five consecutive scheduled failures records why in its run history and queues an immediate email to the workspace owner. Configuration and access stops are recorded and notified too. A pending Drive launch proposal for existing creative keys is refreshed for another 24 hours instead of generating and billing its copy again. New creative keys continue through the workflow.

workflows_list

The workspace's automations with their purpose (why each exists, in the words of the person who asked for it), definition, state and next run, and the templates available. 100 per page: pass nextCursor as after.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
afterstringNo

automation_propose

Sets up an automation the person asked for, saved off, with its purpose in their words: an alert or report on a schedule, or a check when a figure crosses a line, with an optional pause, resume or budget change, one of the Shopify store templates, the account health alert (account-health: a spending limit at 90%, a failed payment, a restricted account), or the New lead alert (notify-new-leads, with the Meta id of a campaign, ad set, ad or instant form in ids: every 5 minutes, how many new leads came, with a link to them in Adrails, never what a lead says). The fields are the in-app card's. It returns what the automation does and a link to review it. Nothing runs until a person switches it on in Adrails, and from an AI client every change it proposes waits for approval.

Access: change, adrails:workflows:manage, role allows Automations: create.

InputTypeRequired
namestringYes
purposestringNo
templateone of pause-sold-out-ads, store-roas-guard, new-product-campaign, account-health, notify-new-leadsNo
platformone of meta, google_ads, tiktok_adsNo
accountIdsarray of stringNo
idsarray of stringNo
triggerone of daily, every_2_days, every_3_days, weekly, monthly, thresholdNo
hourintegerNo
weekdayintegerNo
monthDayintegerNo
levelone of account, campaign, adset, adNo
periodone of today, yesterday, last_3_days, last_7_days, last_14_days, last_30_days, last_month, lifetimeNo
oncebooleanNo
conditionsarray of objectNo
rankobjectNo
changeone of pause, resume, multiply, increase_percent, decrease_percent, increase_amount, decrease_amount, set_amountNo
amountnumberNo
maxBudgetnumberNo
minBudgetnumberNo
automaticbooleanNo
notifybooleanYes
emailbooleanNo
reportone of changes, movedNo
bystringNo
timeZonestringNo

workflows_preview

Previews an automation (workflow) or one integration source of it (source) without sending messages or applying anything.

Access: workflow, source: read, adrails:read, role allows reading it.

OperationInputTypeRequired
workflowautomationIdstringYes
workflowdefinitionobjectYes
sourcenodeobjectYes
sourcetimeZonestringYes

channels_manage

Lists, creates, updates, tests or deletes the Slack, Discord or email channels automations post to. From an AI client, a channel can only be created or pointed at the email addresses of verified members of the workspace; Slack, Discord, Telegram and any other recipient are added by a person in Adrails, under Automations, and the refusal says so with the link. Renaming, testing and deleting work for every channel. Testing a webhook channel sends it a connection message; an email channel saves its recipients without sending a test. A listing never returns a channel's target.

Access: list: read, adrails:read, role allows reading it; create, update, test, delete: change, adrails:workflows:manage, role allows Automations: manage.

OperationInputTypeRequired
listafterstringNo
createnamestringYes
createkindone of slack, discord, emailYes
createtargetstringNo
createwebhookUrlURLNo
updatenamestringYes
updatechannelIdstringYes
updatetargetstringNo
updatewebhookUrlURLNo
testchannelIdstringYes
deletechannelIdstringYes

Knowledge, history and jobs

knowledge_skills

Finds and reads the workspace's Knowledge methods and documents: by command key to read a method in full, or by query, then skillId or documentId. A listing returns names and excerpts only, paginated with offset, which also continues a long method or document.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
skillIdstringNo
documentIdstringNo
commandstringNo
querystringNo
offsetintegerNo

knowledge_manage

Creates, updates, favorites or deletes a Knowledge entry. fields takes skillId, command, kind (skill or shortcut), name, description, prompt, metaScope, integrationScope, metaAccountIds, integrationConnectionIds and favorite. Any member can manage shortcuts; a skill, which the agent follows on its own, needs an owner or admin.

Access: change, adrails:knowledge:write, role allows Knowledge and skills: update.

InputTypeRequired
operationone of create, update, favorite, deleteYes
fieldsobjectYes

knowledge_propose

Checks a durable instruction or a reusable request (a shortcut) against what Knowledge already holds, and saves nothing. A shortcut comes back ready for knowledge_manage once the person agrees; an instruction comes back with the link where the person adds it in Knowledge.

Access: read, adrails:read, role allows Knowledge and skills: create.

InputTypeRequired
kindone of instruction, result, shortcutYes
textstringYes
commandstringNo
namestringNo

brand_read_site

Reads one of the workspace's stores: a connected Shopify store through Shopify (the store details and its best-selling products) and its public pages (about, FAQ, shipping, returns, contact), or the url given on the public web. With several connected stores, store names the one to read, by its name or domain; without it the call lists them. Returns each source's address and text, and the store's logo, colors and fonts from its theme, for the client to write a brand profile from (overview, story, products, audience, positioning, voice and tone, promises, objections, claims to avoid), each line resting on a source. Runs no model and saves nothing: the returned link opens the brand profile in Knowledge.

Access: read, adrails:read, role allows Knowledge and skills: create.

InputTypeRequired
storestringNo
urlstringNo

jobs_status

The stored state of background jobs, campaign publications, actions, automation runs, or this connection's own calls (operation, by tool and key): the 25 most recent, or one by id. Pending, applied and failed stay distinct.

Access: read, adrails:read, role allows reading it.

InputTypeRequired
kindone of background, publication, action, workflow, operationNo
idstringNo
toolstringNo
keystringNo

On this page

Calling a toolWhat a call doesApproving a proposalRetries and idempotencyOne call at a timeLaunch questions and contextWho can call whatResultsReport filesRate limitsErrorsRefused requestsErrors inside a toolAnalysis and reportingreporting_overviewperformance_periodads_exportperformance_diagnosemetrics_dailymetric_compareportfolio_reviewbudget_recommendbusiness_reviewplanning_calculatechanges_reviewfindings_reviewCommerce and subscriptionsstore_revenuestore_ordersstore_customersstore_productssaas_performanceCreativescreative_insightscreative_market_evidencecreative_reviewdrive_folderCampaign setup and researchsite_brieflaunch_briefcampaigns_setupcampaigns_structuregoogle_ads_librarygoogle_keyword_plannereditor_settings_referencetargeting_optionsaudience_estimateAdvertising changesactions_recentcampaigns_pausecampaigns_set_statuscampaigns_change_budgetcampaigns_create_draftcampaigns_launchcampaigns_launch_activatecampaigns_duplicate_to_draftmeta_archivemeta_deletemeta_editmeta_audience_createmeta_duplicatemeta_swap_creativecampaigns_split_testgoogle_ads_buildgoogle_ads_editfindings_applycampaigns_publish_draftcampaigns_delete_draftactions_undoCampaign drafts, templates and mediacampaign_draftscampaign_templatescampaign_mediaAccounts and integrationsaccounts_listaccounts_updateintegrations_statusintegrations_catalogintegrations_detailintegrations_connectintegrations_updateintegrations_syncintegrations_disconnectaccounts_syncLeadsleads_readlead_form_createlead_sheet_sync_startlead_sheet_sync_statuslead_sheet_sync_stopAutomationsworkflows_listautomation_proposeworkflows_previewchannels_manageKnowledge, history and jobsknowledge_skillsknowledge_manageknowledge_proposebrand_read_sitejobs_status