---
title: brand_update
description: 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`](/mcp/tools/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](/mcp/tools/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](/mcp/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](/mcp/auth) 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:

```json
{
  "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`:

```json
{
  "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"
  }
}
```