---
title: document_list
description: List the files attached to a brand, each with a URL you can fetch.
---

Lists the **documents** attached to a brand — logo, guidelines, decks — each with a URL you can fetch directly.

Uploads that were reserved but never completed are **not** listed: there is no file behind them, so every URL returned here resolves.

## Input

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `brand_name` | `string` | yes | The brand slug whose files to list. |
| `limit` | `number` | no | The greatest number of rows in the answer, from 1 to 500. The default is 100. |
| `cursor` | `string` | no | The `nextCursor` of the previous answer. Omit it to get the first page. |

## Output

`{ documents: [...], nextCursor? }`, newest first. Each document is `{ id, name, filename, mimeType, sizeBytes, url }`. When `nextCursor` is present, more documents exist: call `document_list` again with the same `brand_name` and `cursor` set to that value.

## Example

> _"What brand materials do we have for Acme?"_

```ts
document_list({ brand_name: 'acme-running' });
// → { documents: [{ name: 'brand-guidelines.pdf', mimeType: 'application/pdf',
//      url: 'https://documents.adcrunch.dev/org_…/doc_…' }] }
```

The same list is included in [`brand_get`](/mcp/tools/brand-get), so if you're already loading the brand's context you don't need a second call.

## Errors

- `invalid_cursor` — the `cursor` is not a `nextCursor` of this tool, with the same arguments. Send it with no change, or omit it.

Requires the `brand:read` scope.

## Reference

List the files attached to a brand — logos, guidelines, decks — newest first, each with a URL you can fetch. Uploads that never completed are not listed, so every URL here resolves. The answer holds at most `limit` rows (default 100, maximum 500). When it carries `nextCursor`, more rows exist: call this tool again with the same arguments and `cursor` set to that value. When it carries no `nextCursor`, you have every row.

### Input

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `brand_name` | string | yes | The brand slug whose files to list. |
| `cursor` | string, at least 1 character | no | The `nextCursor` of the previous page. Omit it to get the first page. Send it with no change, and with the same filters as the request that answered it: a cursor from a different query gets a 400 `invalid_cursor`. Do not build or change a cursor. |
| `limit` | integer, 1 to 500 | no | The greatest number of rows on the page, from 1 to 500. The default is 100. A greater value gets a 400, with `error` of `invalid_request`. Default: `100`. |

### 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_cursor`
- `forbidden`
- `invalid_request`
- `internal_error`

### Scope

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

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