---
title: MCP tools
description: Every tool the Archetype MCP server publishes, with its arguments, the domains get_brand reads, and an example call for each.
---

> Source: https://www.heyarchetype.com/docs/agents/tools

A connected agent gets six tools: three that read the brand, two that make something new (images and video, or a whole campaign), and one that changes the brand. This page lists every argument exactly as the server declares it. The same reference, generated from the same source, is served to agents at `/llms-full.txt`.

| Tool | What it's for | Marked as |
| --- | --- | --- |
| `get_brand` | Read the brand, one domain at a time: an index, then one item's detail. | Read-only |
| `search_brand` | Find anything in the brand by keyword. | Read-only |
| `check_against_brand` | Grade code, copy or a live page against the brand. | Read-only |
| `generate_media` | Make a new photo or video clip and keep it in the brand's library. | Write (creates) |
| `create_campaign` | Plan a whole campaign from one brief, then make its designs, images and videos. | Write (creates) |
| `update_brand` | Change one item in the brand, or apply, discard or undo a change. | Write (destructive) |

The server works index first, then detail. Call a domain bare to see what it holds, then call it again with the `handle` the index gave you. Fetch only the item you need, because every response lands in the agent's context.

## get_brand

Reads the brand. With no arguments it returns the brief, which is where an agent should start: BRAND.md, then every token and the logo rules inline, then an inventory of everything else with the handle that fetches each item.

| Argument | Type | Required | What it does |
| --- | --- | --- | --- |
| `domain` | string, one of the domains below | No | Which part of the brand to read. Defaults to `brief`. |
| `handle` | string | No | The item within the domain, as its index gave it. Leave it out for the index. Ignored by `brief` and `info`. |
| `task` | string | No | One sentence on what you are about to make. Returns a brief of just what that work needs: the template to start from, files to read, photos by tag, parts and gaps. Leave `domain` unset. |
| `example` | string | No | `components` only. An example's name or id, to narrow a component to one example. |
| `mode` | string | No | `tokens`, or `components` and `templates` with a handle. The mode to resolve colors in, such as `dark`. |
| `include_tokens` | boolean | No | `components` with a handle only. `false` leaves out the `:root` block of tokens, which is the same for every component. |
| `variant` | string | No | Deprecated alias for `example`. |
| `intent` | string | No | `icons` only. What the icon needs to mean, to pick one from a custom set, such as `download`. |
| `include_code` | boolean | No | `artifacts` only, with no handle. Includes the full source of every artifact. Large. |
| `type` | string: `social`, `web`, `app` or `files` | No | `templates` only, with no handle. Only templates of this kind. |
| `frame` | string, number, or an array of either | No | `templates` with a handle only. Only these frames, by name or by number from 1. |
| `tag` | string or array of strings | No | `files` only. Assets carrying this tag. Several tags narrow further: an asset must carry all of them. |
| `search` | string | No | `files` only. Substring match over name, description, usage and tags. |
| `pages` | string | No | `files` with a handle only. Which pages of a PDF to read, such as `3` or `5-12`. |

### Domains

| Domain | What `handle` selects | What it returns |
| --- | --- | --- |
| `brief` | (none) | BRAND.md, all tokens and logo rules inline, and an index of components, templates, artifacts, icons, library tags and knowledge files. The default. |
| `info` | (none) | The brand's name and slug, and a count of everything served. The cheapest way to see what exists. |
| `tokens` | token category: `color`, `typography`, `spacing`, `radius` or `shadow` | Design tokens as W3C Design Tokens (DTCG) JSON. Where the brand has modes, each semantic color carries its other values. |
| `assets` | asset name, such as `Logo Dark` | Logos, favicons and other identity assets: inline SVG or a stable file URL, plus usage rules (when-to-use tags, guidance, clearspace, minimum size, misuse). |
| `components` | component key, such as `button` | Bare: every component's key, name and example names. With a key: each example's real HTML and CSS, with values as `var(--token)`. |
| `icons` | icon set slug, such as `lucide` | Bare: the icon sets the brand uses. With a slug: import syntax and license for a referenced set, or every icon as inline SVG for a custom set, plus the set's when-to-use tags and guidance. |
| `artifacts` | artifact handle | Bare: an index of the brand's bespoke code (backgrounds, patterns, generative graphics, motion), with when-to-use tags and guidance. With a handle: its full source, usage snippet and brand defaults. |
| `templates` | template key | Bare: every template with its type and frames. With a key: the finished markup with the brand's real logo, images and colors bound in, plus a `slots` list of what may change. |
| `files` | file name or id | The asset library: photos, illustrations and PDFs, with tags, descriptions and a stable `embedUrl`. A PDF returns its text, page by page. |
| `voice` | document slug, or `all` | The brand's voice and messaging documents. Bare: an index with each document's slug, status and word count. |
| `schema` | (none) | How to write with `update_brand`: every domain's value shape, the component model and every limit. Read it before the first write. |

```json title="Read one component"
{ "domain": "components", "handle": "button", "example": "Primary" }
```

```json title="Brief for one piece of work"
{ "task": "Instagram story announcing our spring sale" }
```

## search_brand

Keyword search across token names and roles, logo usage, component and example names, artifacts and their code, library files (including the text inside PDFs), templates and voice documents. Every hit carries the exact `get_brand` call that fetches it.

| Argument | Type | Required | What it does |
| --- | --- | --- | --- |
| `query` | string | Yes | A case-insensitive keyword or phrase. A phrase that matches nothing is retried term by term. |
| `domains` | array of `tokens`, `assets`, `components`, `icons`, `artifacts`, `templates`, `files`, `voice` | No | Limit the search to these domains. Leave it out for all. |

```json title="Example"
{ "query": "pricing table", "domains": ["components", "templates"] }
```

## check_against_brand

Grades work against the brand and returns a worst-first list of fixes. A finding is either a lookup (a color or typeface the brand never defined, with the token to use instead) or a judgment with a confidence (a control rebuilt from raw elements when the brand already has it). Each finding is marked as drift, a hardcoded value, or a gap the brand has no answer for.

| Argument | Type | Required | What it does |
| --- | --- | --- | --- |
| `subject` | string | One of `subject` or `url` | The code, CSS, markup or copy to grade. One file at a time, up to 80,000 characters. A longer subject is refused, not cut. |
| `kind` | string: `code` or `copy` | No | Defaults to `code`. Pass `copy` for prose people will read, and each sentence is also checked against the brand's voice documents. |
| `url` | string | One of `subject` or `url` | A live page to check as a visitor sees it. It is drawn in a browser, takes up to a minute, spends the brand's AI credits and returns a `reportUrl` for a person. |
| `gaps` | array of strings | No | What you had to invent because the brand didn't define it, one short sentence each. They reach the brand's team. |

```json title="Example"
{ "subject": ".cta { background: #0a84ff; border-radius: 10px; }", "gaps": ["No focus ring color for dark surfaces"] }
```

Nothing about the brand is changed by a check. A `url` check keeps its report on the brand's Check page. See [Check](/docs/create/check).

## generate_media

Makes a new photograph or video clip and keeps it in the brand's library. It costs credits, so an agent should look in the library first. The brand's imagery rules are added to the prompt for it. It needs a role that can add files to the library; it does not need edits allowed on the connection.

| Argument | Type | Required | What it does |
| --- | --- | --- | --- |
| `kind` | string: `image` or `video` | No | Defaults to `image`. |
| `prompt` | string | Yes, unless `check` | A photographer's brief: subject, setting, light, framing, mood. Describe a scene, never a logo or lettering. |
| `aspect` | string | No | Images: `1:1`, `4:5`, `3:2`, `2:3`, `16:9`, `9:16`. Videos: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`. |
| `quality` | string: `high` or `medium` | No | Images only. Defaults to `high`. |
| `size` | string: `1k`, `2k` or `4k` | No | Images only. Defaults to `1k` (about 1 megapixel). `2k` is about 4 and `4k` about 8, at 8 times the credits of `1k`. |
| `seconds` | number: 5, 10 or 15 | No | Videos only. Defaults to 5. |
| `audio` | boolean | No | Videos only. Defaults to `true`. |
| `from` | array of strings | No | Library files to start from, by name or id: up to 4 for an image, 1 for a video. |
| `check` | string | No | The `id` an earlier video call returned, to see whether it is ready. Pass it on its own. |

An image comes back when it's made, in about a minute. A video takes minutes: the call returns an `id`, and the agent calls again with `check` until the status is ready. Either way the result names the library file it became, with an `embedUrl`.

```json title="Example"
{ "kind": "image", "prompt": "Morning light over a rooftop garden, wide shot, calm", "aspect": "16:9", "size": "2k" }
```

## create_campaign

Has Archetype make a whole campaign from one brief: it plans the idea, the line and the look the pieces share, then makes every piece side by side. Pieces are designs from the brand's templates, components, photos and voice, and generated images and videos in the same look. It spends the brand's credits: about one Create design per design or image, and many times that per video.

It needs a role with the **Designs and checks** permission; images and videos also need permission to edit the **Library**. Like `generate_media`, it does not need edits allowed on the connection.

| Argument | Type | Required | What it does |
| --- | --- | --- | --- |
| `brief` | string | Yes, unless `make`, `discard` or `check` | What the campaign is for, who it speaks to, where it runs, and any facts (dates, prices, offers) it must carry, in the person's words. Up to 3 full `https://` links in it are read for their words, logo and pictures, which the pieces use as that party's own. |
| `attach` | array of objects | No | Up to 6 files for this campaign, such as a partner's logo or the brief as a PDF. Each is `{"source": "<public URL>"}` or `{"data": "<base64>"}`, with a `name`. Pictures (PNG, JPEG, WebP, GIF or SVG), PDFs and text. They're held with the campaign and never added to the library. |
| `pieces` | number | No | How many pieces, 2 to 16. Defaults to 6. Counts written in the brief ("four posts and two photos") set it when it is left out. |
| `formats` | array of strings | No | Up to 48 format ids, such as `instagram-post`, `instagram-story`, `linkedin-landscape` or `email-header`, or platform ids such as `instagram`, whose formats the plan chooses from the brief. Left out, the channels the brief names hold the plan to their formats, or with none named the plan picks. An unknown id is refused with the full list. |
| `kinds` | array of `design`, `image`, `video` | No | What the pieces may be made as. Defaults to all three where generation is on and the role may add to the library. The plan picks the mix, with at most 3 videos. |
| `latitude` | string: `brand`, `first` or `free` | No | How far the materials may stretch past what the brand owns, as on Create. Defaults to `brand`. |
| `photos` | boolean | No | Allow up to 2 new photographs, made once and shared by every piece. Defaults to `false`. |
| `make` | string | No | A campaign `id` whose plan the person has said yes to: make every piece as planned. Pass it on its own. |
| `discard` | string | No | A campaign `id` whose plan the person doesn't want: drop it. Pass it on its own. |
| `check` | string | No | The `id` an earlier call returned, to see how the pieces are getting on. Pass it on its own. |

Every campaign stops at its plan. The first call waits for the plan (about a minute) and returns it with `status` `review`: the idea, the line, the look, any notes, each piece's title, kind, format and brief, and a `reviewUrl`. Nothing is made yet. The agent shows the person the plan and, once they say yes, calls again with `make`. The person can also edit the plan at the `reviewUrl` and press **Make all** there.

Pieces take a few minutes, so the agent calls with `check` until `status` is `ready`. Each ready design has a `previewUrl` picture and each image or video a `fileUrl`, both to show the person, plus an `openUrl`. The `reviewUrl` opens the whole campaign in Archetype to edit and download. See [Campaigns](/docs/create/campaigns).

```json title="Example"
{ "brief": "Launch our spring range on Instagram: three posts and a story, sale ends 15 May", "latitude": "first" }
```

```json title="After the person approves the plan"
{ "make": "<campaign id>" }
```

## update_brand

Changes one item in the brand per call, only when the person asked for that change. It needs a connection approved with **Change the brand when you ask it to**, and the person's role must allow edits in that area. By default the change becomes a draft that waits for review. See [Changes from agents](/docs/agents/drafts).

| Argument | Type | Required | What it does |
| --- | --- | --- | --- |
| `domain` | string: `tokens`, `voice`, `info`, `assets`, `files`, `icons`, `components`, `artifacts`, `templates`, `designs` | Yes, unless `undo`, `apply` or `discard` | What kind of thing to change. `designs` saves a document made from a template's pages (create only). |
| `handle` | string | No | Which item: a token path (`color.brand.500`, or `modes`), a voice slug, a logo name, a file name, an icon set slug, a component key, an artifact handle or a template key. Not used for `info`. |
| `example` | string | No | `components` only. The example to edit, add or delete, by name, such as `Primary · Hover`. |
| `icon` | string | No | `icons` only. An icon's key within a custom set. |
| `frame` | string or number | No | `templates` only. The frame to edit or delete, by name or number from 1, or the new frame's name with `create`. |
| `value` | any | No | What the item becomes: a bare value (a hex, a number of px, a family name) or an object of only the fields to change. Artwork goes in as `{source}`, `{svg}` or `{data}`. |
| `find` | string | No | Exact text to change in a voice document, a component example, an artifact's code or a template frame. Must occur exactly once. |
| `replace` | string | No | What `find` becomes. `""` removes it. |
| `create` | boolean | No | Add a new item at `handle`. |
| `delete` | boolean | No | Remove the item at `handle`. It can be put back with `undo`. |
| `import` | object | No | `tokens`, `components` or `icons`: many items in one call, from `{"source": "<https URL>"}` or `{"document": ...}`. `"dryRun": true` previews. |
| `apply` | string | No | A draft id: make that change for real, only after the person said yes. Pass it on its own. |
| `discard` | string | No | A draft id: drop it. Pass it on its own. |
| `replaces` | string | No | A pending draft id this call revises. |
| `undo` | string or object | No | A `changeId`, `"last"`, or `{"since": "<changeId>"}` for that change and every later one you made. Pass it on its own. |

```json title="Example"
{ "domain": "tokens", "handle": "color.brand.500", "value": "#2179ef" }
```

The exact `value` shape for every domain, and the limits, are in `get_brand` with `{"domain": "schema"}`. A few shapes worth knowing:

- **Font files.** `typography.<family>` takes `{"fonts": [...]}` to upload the family's files, each as `{"source": "<https URL>"}` or `{"data": "<base64>", "name": "<file name>"}`. Files are .woff2, .woff, .ttf or .otf, at most 3 MB each and 24 a call (1.5 MB each sent as `data`). Weight and style come from the file name unless given, and an upload replaces only the file at its weight and style. Font files are licensed, so an agent should ask before uploading them.
- **When to use and guidance.** Logos, icon sets and artifacts take `whenToUse` as short tags of at most 40 characters, such as "Dark background", and `guidance` as free text for sentences such as sizes and pairings. A sentence sent as a tag is refused.
- **How a photo fits its slot.** In a template's `bindings` or a design's `slots`, a file binding takes `"fit"`: `"fill"` covers the box (the default for a photo), `"fit"` shows the whole picture inside it, and `"tile"` repeats it. With `"fill"`, `"focus": {"x": 50, "y": 20}` keeps that point in view; with `"tile"`, `"size"` is a tile's width in percent of the box.

```json title="Upload font files"
{ "domain": "tokens", "handle": "typography.gt-walsheim", "value": { "fonts": [{ "source": "https://example.com/GT-Walsheim-Bold.woff2", "weight": 700 }] } }
```

```json title="Fit a photo in a template slot"
{ "domain": "templates", "handle": "launch-post", "frame": 1, "value": { "bindings": { "hero": { "file": "team-offsite.jpg", "fit": "fill", "focus": { "x": 50, "y": 30 } } } } }
```

## Older tool names

Before version 3 the server published one tool per domain, such as `get_brand_tokens` and `get_brand_components`. Those names still answer and map to the matching `get_brand` domain, but they are no longer listed. Use `get_brand`.

## Resources and limits

For clients that prefer MCP resources, the server also lists `archetype://context` (the brief), `archetype://tokens` (DTCG JSON), and one resource per voice document, artifact, component and icon set.

Each person can make up to 240 calls a minute to a brand, and a brand takes up to 20,000 calls a day.

:::cards
- [Connect an agent](/docs/agents/connect): Add the server to your client and approve it.
- [Changes from agents](/docs/agents/drafts): How `update_brand` drafts are reviewed and applied.
- [Campaigns](/docs/create/campaigns): What `create_campaign` makes, and how the plan is reviewed.
:::