Describe a brand

Write down who a brand is, how it sounds and who it talks to. Your agent reads it before it writes copy or judges an ad account.

A brand is what your agent reads before it acts for you. It says who the brand is, how it sounds, which rules it keeps, and who it talks to. With it, the agent writes in your voice, not in a generic voice.

You describe the brand in the conversation, and the agent writes it with the brand_*, persona_* and document_* tools. The console shows the same brands on Brands. A change that the agent makes shows in the console, and a change in the console shows to the agent.

What a brand holds

You write a brand one part at a time. A section that nobody wrote is empty, and the agent gets no text for it.

Find a brand

“Which brands do we have?”

The agent calls brand_list. You see the name and the one-line description of each brand. The list holds no sections, so it stays short.

“What do we know about Acme?”

The agent calls brand_get with the slug of the brand. It gets the four sections, the website address, a summary of each persona, each file with its URL, and the attached ad accounts. It does not get the text of a persona or the content of a file. It reads those with persona_get and document_get when it needs them.

Create a brand

“Set up a brand for Acme. We sell one running shoe, direct to the runner. Our tone is plain and measured. Never compare the shoe to a named competitor.”

The agent calls brand_create, and it writes the sections that your words fill: here, the identity, the voice and the guidelines. AdCrunch makes the slug from the name. You then see the new brand, and the messaging is empty.

• A slug keeps only the letters from a to z and the digits. Each other run of characters becomes a hyphen. So a name with no letter from a to z and no digit, such as “東京”, gives no slug, and the call fails with invalid_slug. Give a slug with such a letter or a digit.
• A slug is unique in your organization. When a brand already has the slug, the call fails with slug_conflict. AdCrunch does not add a suffix. Give a different name or slug.
• No tool reads the website. The brand keeps the address and nothing more. When you create a brand in the console, the console can read the site and propose the four sections. Over MCP, an agent that can fetch a web page can read the site itself and write the sections.

Change a brand

“Add to the Acme guidelines: we never make a medical claim.”

The agent reads the brand with brand_get, and then calls brand_update. It sends the revision that it read and the fields that change. You then see the brand with the new guidelines and a higher revision.

• A field that the agent does not send stays as it is. A section that it sends as null is cleared. So a change to the voice cannot erase the identity.
• A stale revision changes nothing. When somebody changed the brand after the agent read it, the call fails with revision_mismatch. The agent reads the brand again and decides what to keep. Errors describes each failure.
• A new slug is a rename. A skill, a saved prompt or a teammate that uses the old slug must change too.

Describe who the brand talks to

“Add a persona to Acme: runners aged 28 to 45 who already own a pair and buy the same shoe again. They fear that a new model is worse.”

The agent calls persona_create on the brand, with the age range and the sections that your words fill. You then see the persona with its slug, for example loyalists.

• The age range is the only structured field. A lower bound alone means “and older”. Where the audience lives and what it does go into the profile, as prose. The page of persona_create gives the limits of each bound.
• The section language is not a locale. It holds the words that the audience uses for the problem.
• A persona slug is unique in its brand. Two brands can each have a persona loyalists. So each persona tool takes the brand and the persona together.

brand_get lists the personas of a brand, with no text. persona_get reads one in full. persona_update and persona_delete take the revision that the agent read, as brand_update does. persona_update checks the age range after it applies the change. So a new lower bound above the stored upper bound fails with invalid_age_range.

Add files and a logo

“Upload our brand book to Acme.”

An upload has three steps, and the agent does all three.

• AdCrunch accepts some file types only, up to 25 MB. The page of document_create_upload lists the types. Finalize discards a file of a different type or a larger file, and the call fails.
• The runtime of the agent must reach the storage host. The PUT goes to *.r2.cloudflarestorage.com. An agent that cannot send an HTTP request to that host cannot upload a file.
• Keep the upload URL private. Until it expires, each person who has the URL can write the file. When it expires, the agent reserves the file again.
• Each file has a public URL. Each person who has the URL can read the file. Do not upload a file that must stay private.

“Use acme-logo.png as the Acme logo.”

The logo is a nomination, not a separate upload. The agent uploads the image as a document of the brand. Then it calls brand_update with the id of that document. The document must be a finalized file of the same brand, or the call fails with invalid_logo.

document_list lists the files of a brand. document_get gets one file. An image of 1 MB or less comes back as an image that the agent can look at. A PDF comes back as its URL only. document_delete deletes a file and its bytes. When that file is the logo, the brand drops the nomination.

Attach ad accounts

“Attach our Meta ad account to Acme.”

The agent finds the ad account with list_advertisers. Then it calls brand_attach_advertiser. You then see the ad account in the list of the brand.

• Only an ad account of your organization. An ad account that your organization did not connect fails with advertiser_not_owned.
• One ad account can apply to more than one brand. A second brand does not remove the first.
• A second attach of the same pair changes nothing.

brand_detach_advertiser removes the link, and only the link. The brand and its context stay. When the ad account is not attached to the brand, the call fails with not_attached.

Work on an ad account for its brand

“Write three headlines for our Meta ad account.”

The agent finds the ad account with list_advertisers, and then calls brand_resolve with it. It gets each brand that applies, and how each brand applies. Then it reads the brand with brand_get, and a persona with persona_get when one fits. You then see headlines in the voice of the brand, and they keep its guidelines.

• More than one brand can apply. AdCrunch gives each brand with no rank, and it does not pick one. The agent can ask you which brand you mean.
• No brand is a normal answer. When no brand is attached, the call does not fail. The agent gets an empty list and the sentence “No brand is attached…”. It can continue with no brand context, or you can attach a brand.

Delete

“Delete the brand Acme Trail.”

The agent reads the brand with brand_get, and then calls brand_delete with the revision that it read. Your client can ask you to confirm first. The call deletes the brand, its sections, its personas, its files with their bytes, and its links to ad accounts. The slug is then free for a new brand.

“Delete the persona Loyalists from Acme.”

persona_delete deletes one persona, and the brand stays. It also takes the revision that the agent read.

Scopes

A read needs the scope brand:read. A change needs the scope brand:write. Auth & scopes describes each scope.