What to expect

The rules that each AdCrunch tool follows — which organization your client acts for, how fresh the data is, how money is stated, and what happens when you ask for a change.

Each AdCrunch tool follows the same six rules. Read them once, and you know what the agent can tell you and what it cannot.

Your client acts for one organization

The consent screen has no organization picker. Your client acts for the organization that is active in your most recent AdCrunch session.

Your client reads that organization again each time it gets a new token, which is about once an hour. So when you switch to another organization in the console, your client follows within the hour.

To connect a client to one organization, switch to that organization in the console before you connect the client. Auth & scopes gives the details.

Most answers come from the store

A tool gets its data in one of two ways:

A stored read answers from the data that AdCrunch copied from your ad accounts. It is fast, and it does not use the rate limits of the provider. list_advertisers, list_entities, get_entity and query_insights are stored reads.
A live read asks the provider at the time of the call. meta_list_pages and meta_list_pixels are live reads, because a create needs the Page and the Pixel that exist now.

AdCrunch copies your campaigns, ad sets, ads and their performance once a day. The copy starts at 00:00 UTC. When you connect a provider, AdCrunch also copies the last 90 days. So a stored answer can be up to one day old:

A change that a person makes in Ads Manager shows after the next copy.
A campaign, ad set, creative or ad that AdCrunch creates for you usually shows within seconds, because AdCrunch copies that one object again after the create. This is not guaranteed. The id that the create returns is always correct.
The figures of the last days can still change. A provider counts a conversion some days after the click, so AdCrunch copies the last 3 days again on Meta and TikTok, and the last 14 days on Google Ads.

When you need the value of now, check it in the interface of the provider. A budget change is different: it reads the provider before it applies, so it never acts on an old budget level.

Money is in whole units of the account currency

Each amount that a tool sends or receives is in whole units of its currency, as a decimal number. 50 is 50.00, and 40.5 is 40.50. It is never in cents.

A budget and a spend are in the currency of their ad account.
query_insights can convert its figures to one display currency. It uses the reference rate of the European Central Bank for the date of each row. Ask for one currency when your organization has ad accounts in more than one currency, so that no total mixes two currencies.
AdCrunch refuses an amount with more decimals than its currency has. It never rounds an amount.

get_entity returns the full record of the provider, with one change for money. AdCrunch converts the budgets and the bids of a Meta record to whole units of the account currency. When AdCrunch does not know that currency yet, those fields are empty (null). A Google Ads field whose name ends in Micros states its unit, so it stays in micros: 1,000,000 micros is one unit.

A change is queued, then confirmed

A change on Meta does not happen during the tool call. The tool puts the change in a queue, and it returns a workflowId at once. The agent then calls get_mutation_status with that id, until the change is complete or errored.

complete gives the result, for example the id of a new campaign.
A change that AdCrunch or the provider refuses is also complete. Its result holds the code of the refusal, for example budget_cap_exceeded. The call to get_mutation_status succeeded, because it read the status.
errored means that the change stopped before it had a result. Check in the interface of the provider before you ask for the change again.
The six Meta tools that change something work this way: meta_create_campaign, meta_create_adset, meta_create_creative, meta_create_ad, meta_set_status and meta_update_budget.

So when you ask for a change, the agent first tells you that it started the change, and then tells you how it ended. The job guide shows a full example.

A create arrives paused

Each campaign, ad set and ad that an agent creates arrives paused. The create tools have no status input, so no agent can create something that spends at once. Nothing spends until you, or a separate call to meta_set_status, turns it on.

AdCrunch also refuses a budget above the safety cap, and it never deletes an object on an ad account. Auth & scopes lists each limit.

An edit can collide with another edit

Two people, or a person and an agent, can edit the same brand, persona, playbook or Campaign Plan at the same time. AdCrunch does not let the second edit erase the first.

Each of these objects has a revision number. The agent reads the object, and it sends the revision that it read with its edit. When the object changed in the meantime, the edit fails with the code revision_mismatch, and the failure gives the current revision in currentRevision. Nothing changes.

The agent then reads the object again, checks that its edit still applies to the new version, and sends the edit again with the new revision. When the two edits disagree, a good agent asks you which one to keep.

What’s next

Errors: the shape of each failed tool call.
Auth & scopes: what an agent can change, and what it cannot.
The six job guides, which apply these rules to one job each.