brand_get

Read one brand in full: its four sections, its personas, its files and its ad accounts. An agent reads it before it acts for the brand.

Ask for work that needs a brand. The agent reads the brand in full before it writes or judges anything.

“Write three ad headlines for Acme.”

The agent calls brand_get for Acme. It reads the voice and the guidelines, and it sees the personas, the files and the attached ad accounts. You then get headlines in the voice of Acme, not generic headlines.

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

Reference

Fetch a single brand by its slug: the full brand context (identity, voice, guidelines, messaging), its websiteUrl if one is set, plus its personas (summaries only — who the brand talks to), its documents (each with a URL) and the ad accounts attached to it. Unwritten sections are null — read the website yourself for anything they do not cover. Load a persona’s own context with persona_get. Echo the revision back as base_revision when updating.

Input

Argument	Type	Required	Description
`brand_name`	string	yes	The brand slug (its stable per-organization handle).

Output

A successful call returns this object in structuredContent.

Field	Type	Always present	Description
`advertisers`	array of object	yes	The ad accounts attached to the brand.
`advertisers[].advertiserId`	string	yes	The ad account (`acc_…`).
`advertisers[].createdAt`	number	yes	Milliseconds since the Unix epoch, in UTC.
`advertisers[].provider`	string	yes	The provider of the ad account, such as `meta`. AdCrunch reads it from the ad account.
`advertisers[].targetId`	string	yes	The id of the brand that the ad account is attached to.
`advertisers[].targetType`	string	yes	The kind of record that the ad account is attached to: `brand`.
`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.
`documents`	array of object	yes	The finalized files of the brand, each with its URL. The content of a file is not in the bundle.
`documents[].createdAt`	number	yes	Milliseconds since the Unix epoch, in UTC.
`documents[].filename`	string	yes	The name of the file at upload.
`documents[].id`	string	yes	The id of the document (`doc_…`).
`documents[].mimeType`	string	yes	The media type of the stored file. AdCrunch reads it from the file at finalize.
`documents[].name`	string	yes	The display name. It is the filename until someone renames it.
`documents[].sizeBytes`	number	yes	The size of the stored file, in bytes. AdCrunch reads it from the file at finalize.
`documents[].targetId`	string	yes	The id of the brand that holds the document (`brd_…`).
`documents[].targetType`	string	yes	The kind of record that holds the document: `brand`.
`documents[].url`	string	yes	The public URL of the file. Each person who has the URL can read the file.
`personas`	array of object	yes	The personas of the brand, newest first, with no prose.
`personas[].ageMax`	integer, 0 to 120 or null	yes	The highest age of the audience. `null` when the range has no upper bound.
`personas[].ageMin`	integer, 0 to 120 or null	yes	The lowest age of the audience. `null` when the range has no lower bound.
`personas[].description`	string	yes	One line about the persona. An agent picks a persona on it.
`personas[].name`	string	yes	The display name.
`personas[].slug`	string	yes	The handle of the persona. It is unique in its brand, not in the organization. The tools take it as `persona_name`.
`personas[].sections`	object	yes	Which of the four sections of the persona hold text. Read the text with `persona_get`.
`personas[].sections.frictions`	boolean	yes	`true` when the section `frictions` holds text.
`personas[].sections.language`	boolean	yes	`true` when the section `language` holds text.
`personas[].sections.motivations`	boolean	yes	`true` when the section `motivations` holds text.
`personas[].sections.profile`	boolean	yes	`true` when the section `profile` holds text.

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
forbidden
invalid_request
internal_error

Scope

The token must hold brand:read. 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.

Read-only. The tool changes nothing.
Closed world. The tool reads and writes the data of AdCrunch only.

Example

The arguments:

{
  "brand_name": "acme"
}

The result, in structuredContent:

{
  "advertisers": [
    {
      "advertiserId": "acc_1203456789012345",
      "createdAt": 1790000000000,
      "provider": "meta",
      "targetId": "brd_6a9c33",
      "targetType": "brand"
    }
  ],
  "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"
  },
  "documents": [
    {
      "createdAt": 1790086400000,
      "filename": "acme-logo.png",
      "id": "doc_7d1f58",
      "mimeType": "image/png",
      "name": "acme-logo.png",
      "sizeBytes": 48213,
      "targetId": "brd_6a9c33",
      "targetType": "brand",
      "url": "https://documents.adcrunch.dev/org_3a7f10/doc_7d1f58"
    },
    {
      "createdAt": 1790000000000,
      "filename": "acme-brand-guidelines.pdf",
      "id": "doc_5e2b41",
      "mimeType": "application/pdf",
      "name": "acme-brand-guidelines.pdf",
      "sizeBytes": 1482064,
      "targetId": "brd_6a9c33",
      "targetType": "brand",
      "url": "https://documents.adcrunch.dev/org_3a7f10/doc_5e2b41"
    }
  ],
  "personas": [
    {
      "ageMax": 45,
      "ageMin": 28,
      "description": "Runners who already own a pair, and who buy the next one without looking at another brand.",
      "name": "Loyalists",
      "sections": {
        "frictions": true,
        "language": true,
        "motivations": true,
        "profile": true
      },
      "slug": "loyalists"
    }
  ]
}