---
title: brand_create
description: Create a brand in your organization. You can write its sections now or later.
---

Ask for a new brand. The agent creates it, and it writes the sections that your words fill.

> "Set up a brand for Acme. We sell one running shoe, direct to the runner. Our tone is plain and measured."

The agent calls `brand_create`. You then see the new brand Acme with its identity and its voice. Its guidelines and its messaging stay empty until you write them.

The job guide [Describe a brand](/mcp/tools/describe-a-brand) shows each step of the job.

## Reference

Create a brand in the active organization. Every context section is optional — a brand is authored incrementally, so name and description alone is a valid start. The slug (its stable handle) is derived from the name unless one is given. Fails if the slug already exists.

### Input

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | string | yes | One-line summary — what an agent reads to pick this brand from a list. |
| `guidelines` | string | no | Do's and don'ts, guardrails, claims to avoid, compliance notes (markdown). |
| `identity` | string | no | Who the brand is: positioning, mission, what it offers, category (markdown). |
| `messaging` | string | no | Key messages, value propositions, proof points (markdown). |
| `name` | string | yes | Human-readable display name. |
| `slug` | string | no | Optional explicit slug handle; normalized to kebab-case. Defaults to a slug derived from the name. |
| `voice` | string | no | Tone of voice and personality (markdown). |
| `website_url` | string, at most 2048 characters | no | The brand's public site, http or https. A locator like the slug — where the brand lives on the web — not a context section, and setting it reads nothing. |

### 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.

- `invalid_slug`
- `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
{
  "description": "Running shoes sold direct to the runner, made to last a thousand kilometres.",
  "name": "Acme",
  "voice": "Plain and measured. Short sentences. No superlative the shoe cannot earn.",
  "website_url": "https://acme.example"
}
```

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": null,
    "identity": null,
    "messaging": null,
    "voice": "Plain and measured. Short sentences. No superlative the shoe cannot earn.",
    "id": "brd_6a9c33",
    "logoDocumentId": null,
    "name": "Acme",
    "revision": 1,
    "slug": "acme",
    "updatedAt": null,
    "websiteUrl": "https://acme.example"
  }
}
```