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

Your client acts for one organization: the organization that is active in your most recent AdCrunch session. The consent screen has no organization picker. Auth & scopes tells how to choose the organization, and when your client follows a switch.

Most answers come from the store

Most tools answer from the copy of your ad accounts that AdCrunch stores. list_advertisers, list_entities, get_entity and query_insights read this copy. A read from the copy is fast, and it does not use the rate limits of the provider.

meta_list_pages and meta_list_pixels are different. They ask Meta when you call them, 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 the interface of the provider usually shows after the next copy. A change to a budget only can stay old: Meta does not mark a campaign changed when only its budget changes, and AdCrunch does not follow a budget change on Google Ads yet. Read your accounts gives the details.
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. AdCrunch does not guarantee this. The id that the create gives 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 Meta before it applies, so it never acts on an old budget level.

Money is in whole units of its 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. An amount is never in cents.

A budget and a spend on an ad account are in the currency of that ad account.
A budget in a Campaign Plan is in the currency of that Campaign Plan.
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 gives 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 currency of the ad account. When AdCrunch does not know that currency yet, those fields are empty. 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 gives an id for the change at once. The agent then calls get_mutation_status with that id, until the change is complete or it stopped.

A complete change gives the result, for example the id of a new campaign.
A change that AdCrunch or Meta refuses is complete too. Its result holds the code of the refusal, for example a budget above the safety cap. The call to get_mutation_status succeeded, because it read the status.
A change that stopped has no result. Check in the interface of Meta 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. Change what runs on Meta shows a full example.

A create arrives paused

Each campaign, ad set and ad that an agent creates arrives paused. A creative has no status. 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, Skill, Campaign Plan or Line Item 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, AdCrunch refuses the edit with the code revision_mismatch, and the failure gives the current revision. 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. It does not read the object and start again from zero, because that erases what the author wrote. 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.