---
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 body. The new body keeps the text that the agent read and adds the new guideline. You then see the new guideline, and the rest of the body as it was.

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 `body` to replace the whole body of the brand (read it with brand_get, change it, send it back) and null to clear it. Suggested headings for the body: "## Identity", "## Voice", "## Guidelines", "## Messaging". 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. |
| `body` | string, 1 to 50000 characters or null | no | The new body of the brand, as one Markdown text. It replaces the whole body. Omit it to leave the body alone. Pass null to clear it. |
| `brand_name` | string | yes | The current brand slug identifying which brand to update. |
| `description` | string, 1 to 500 characters | no | New one-line summary. |
| `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. |
| `name` | string, 1 to 120 characters | no | New display name. |
| `slug` | string, at most 120 characters | no | Optional new slug handle (a deliberate rename); normalized to kebab-case. Callers of the old handle must be updated. |
| `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.body` | string or null | yes | The context of the brand, as one Markdown text. `null` when no body is written. Headings such as Identity, Voice, Guidelines and Messaging are the advice of the tools, and the body does not need them. |
| `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.id` | string | yes | The id of the brand (`brd_…`). |
| `brand.logoDocumentId` | string or null | yes | The document that the brand nominates as its logo (`doc_…`). `null` when no document is the logo. |
| `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.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`
- `organization_unentitled`
- `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,
  "body": "## Identity\n\nAcme 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.\n\n## Voice\n\nPlain and measured. Short sentences. No superlative the shoe cannot earn.\n\n## Guidelines\n\n- 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.\n\n## Messaging\n\n- 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.",
  "brand_name": "acme",
  "logo_document_id": "doc_7d1f58"
}
```

The result, in `structuredContent`:

```json
{
  "brand": {
    "body": "## Identity\n\nAcme 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.\n\n## Voice\n\nPlain and measured. Short sentences. No superlative the shoe cannot earn.\n\n## Guidelines\n\n- 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.\n\n## Messaging\n\n- 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.",
    "createdAt": 1790000000000,
    "createdBy": "usr_4d8b12",
    "description": "Running shoes sold direct to the runner, made to last a thousand kilometres.",
    "id": "brd_6a9c33",
    "logoDocumentId": "doc_7d1f58",
    "name": "Acme",
    "revision": 4,
    "slug": "acme",
    "updatedAt": 1790086400000,
    "websiteUrl": "https://acme.example"
  }
}
```