brand_update

Change a brand. The revision that the agent read stops it from overwriting a change that it did not see.

Ask for a change to a brand. The agent changes only the parts that you name.

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

The agent reads the brand with brand_get, and then calls brand_update with the new guidelines. You then see the new guidelines, and the voice and the identity as they were.

The job guide Describe a brand shows each step of the job.

Reference

Update a brand. Pass base_revision (from brand_get) — the update is rejected if the brand changed since you read it. Only the fields you pass are changed; pass null for a context section to clear it. Optionally rename the slug handle.

Input

Argument	Type	Required	Description
`base_revision`	integer	yes	The revision you last read via brand_get. Guards against overwriting a concurrent edit.
`brand_name`	string	yes	The current brand slug identifying which brand to update.
`description`	string	no	New one-line summary.
`guidelines`	string or null	no	New do’s and don’ts. Pass null to clear the section.
`identity`	string or null	no	New positioning and mission. Pass null to clear the section.
`logo_document_id`	string or null	no	Nominate one of the brand’s documents as its logo, or null to clear the nomination. Upload the file first with document_create_upload.
`messaging`	string or null	no	New key messages. Pass null to clear the section.
`name`	string	no	New display name.
`slug`	string	no	Optional new slug handle (a deliberate rename); normalized to kebab-case. Callers of the old handle must be updated.
`voice`	string or null	no	New tone of voice. Pass null to clear the section.
`website_url`	string, at most 2048 characters or null	no	The brand’s public site, http or https; null to clear it. Changing it reads nothing — it is a locator, like the slug.

Output

A successful call returns this object in structuredContent.

Field	Type	Always present	Description
`brand`	object	yes	The brand in full.
`brand.createdAt`	number	yes	Milliseconds since the Unix epoch, in UTC.
`brand.createdBy`	string	yes	The user who created the record (`usr_…`).
`brand.description`	string	yes	One line about the brand. An agent picks a brand on it.
`brand.guidelines`	string or null	yes	The rules: claims to avoid, guardrails and compliance notes. Markdown. `null` when the section is not written.
`brand.id`	string	yes	The id of the brand (`brd_…`).
`brand.identity`	string or null	yes	Who the brand is: positioning, mission, offer, category. Markdown. `null` when the section is not written.
`brand.logoDocumentId`	string or null	yes	The document that the brand nominates as its logo (`doc_…`). `null` when no document is the logo.
`brand.messaging`	string or null	yes	Key messages, value propositions and proof points. Markdown. `null` when the section is not written.
`brand.name`	string	yes	The display name.
`brand.revision`	number	yes	The version of the record. Each change adds 1. Send it as `base_revision` to update or delete the record.
`brand.slug`	string	yes	The handle of the brand in the organization. The tools take it as `brand_name`.
`brand.updatedAt`	number or null	yes	Milliseconds since the Unix epoch, in UTC. `null` until the first change.
`brand.voice`	string or null	yes	The tone of voice and the personality. Markdown. `null` when the section is not written.
`brand.websiteUrl`	string or null	yes	The public site of the brand. `null` when it is not set. AdCrunch keeps the address and does not read the site.

Failure codes

A failed call has isError set, and structuredContent.error holds one of these codes. Errors describes the shape of a failed call.

not_found
invalid_slug
invalid_logo
revision_mismatch
slug_conflict
forbidden
invalid_request
internal_error

Scope

The token must hold brand:write. Auth & scopes lists each scope.

Annotations

A client reads these hints. A hint that the tool does not declare has the default value of the MCP specification.

Writes. The tool can change data.
Destructive. The tool can make a change that you cannot undo. A client can ask you to confirm before it calls the tool.
Not idempotent. A second call with the same arguments can change more.
Closed world. The tool reads and writes the data of AdCrunch only.

Example

The arguments:

{
  "base_revision": 3,
  "brand_name": "acme",
  "guidelines": "- Name the distance, never the \"journey\".\n- Claim the kilometres the shoe is tested to, and no more.\n- Do not compare the shoe to a named competitor.",
  "logo_document_id": "doc_7d1f58"
}

The result, in structuredContent:

{
  "brand": {
    "createdAt": 1790000000000,
    "createdBy": "usr_4d8b12",
    "description": "Running shoes sold direct to the runner, made to last a thousand kilometres.",
    "guidelines": "- Name the distance, never the \"journey\".\n- Claim the kilometres the shoe is tested to, and no more.\n- Do not compare the shoe to a named competitor.",
    "identity": "Acme makes one running shoe and sells it direct. The promise is a thousand kilometres on the same pair, and a resole rather than a replacement.",
    "messaging": "- One shoe, a thousand kilometres.\n- Resole it twice, and keep running on it.\n- Sold direct, so the price is the cost of the shoe.",
    "voice": "Plain and measured. Short sentences. No superlative the shoe cannot earn.",
    "id": "brd_6a9c33",
    "logoDocumentId": "doc_7d1f58",
    "name": "Acme",
    "revision": 4,
    "slug": "acme",
    "updatedAt": 1790086400000,
    "websiteUrl": "https://acme.example"
  }
}