> ## Documentation Index
> Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# folder

> MCP tool that creates, renames, or deletes one of your personal dashboard folders, selected by an action argument.

Creates, renames, or deletes a folder in your personal dashboard folder list. The `action` argument selects which.

Equivalent to [`murmur folder create`](/cli/folder-create), [`murmur folder rename`](/cli/folder-rename), and [`murmur folder rm`](/cli/folder-rm) in the CLI.

Folders are personal: they change only your own dashboard view, never another user's. To file [agents](/concepts/agents) into a folder, use [`folder_assign`](/mcp-server/folder-assign); to read your folder names and what each holds, use [`spawn_profiles`](/mcp-server/spawn-profiles).

## Parameters

| Name       | Type   | Required      | Description                                                                                                                                                                                                                                                                                                 |
| ---------- | ------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action`   | string | yes           | One of `create`, `rename`, `delete`.                                                                                                                                                                                                                                                                        |
| `name`     | string | yes           | The folder this acts on, by display label. For `create` it is the new folder's label — 1–76 UTF-8 bytes, no leading or trailing whitespace, no control characters — and a label you already use is rejected. For `rename` and `delete` it must be one of your existing folder names, matched ignoring case. |
| `new_name` | string | with `rename` | The new display label. Required with `action: rename` and rejected with any other action.                                                                                                                                                                                                                   |

<Note>
  A folder name carries no hierarchy — `/` is an ordinary character in a label, not a separator.
</Note>

## Actions

### `create`

Creates a folder holding no agents. Returns the folder, with `agent_count: 0`.

```json theme={null}
{
  "action": "create",
  "name": "Release 4.2"
}
```

```json theme={null}
{
  "folder_id": "fld-3b17c9e04ad2",
  "name": "Release 4.2",
  "agent_count": 0
}
```

### `rename`

Changes a folder's display label. Everything filed under it stays filed: membership follows the folder itself, not its name. Returns the folder as it now reads, with no `agent_count` — a rename neither changes nor reports it. Read the count from [`spawn_profiles`](/mcp-server/spawn-profiles).

```json theme={null}
{
  "action": "rename",
  "name": "Scratch",
  "new_name": "Scratch pad"
}
```

```json theme={null}
{
  "folder_id": "fld-c07be31d5a94",
  "name": "Scratch pad"
}
```

### `delete`

Deletes the folder. The agents filed under it become unfiled and are otherwise untouched — no agent is stopped, deleted, or altered, and no other person's view is affected. Returns how many agents were unfiled.

```json theme={null}
{
  "action": "delete",
  "name": "Release 4.2"
}
```

```json theme={null}
{
  "unfiled_agents": 1
}
```

<Note>
  There is no confirmation step. Read the folder's `agent_count` from [`spawn_profiles`](/mcp-server/spawn-profiles) first if it matters — that is exactly what the delete will unfile. To undo, create the folder again and re-file the agents with [`folder_assign`](/mcp-server/folder-assign).
</Note>

## Response fields

| Field            | Type   | Description                                                                                                                                                           |
| ---------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `folder_id`      | string | The folder's stable id, assigned by the server and unchanged by a rename. No tool takes it as input — folders are named by `name`. Returned by `create` and `rename`. |
| `name`           | string | The display label. Returned by `create` and `rename`.                                                                                                                 |
| `agent_count`    | number | How many agents are filed in the folder. Returned by `create` (always `0`); absent from a `rename`, which does not report a count.                                    |
| `unfiled_agents` | number | How many agents the delete unfiled. Returned by `delete`.                                                                                                             |

## Errors

| Code                  | Meaning                                                                                                                                                              | What to do                                                                                                                                         |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `INVALID_ARGUMENT`    | Unknown `action`; missing `name`; `new_name` on an action other than `rename`, or missing on a `rename`; no folder of yours has that name; or the name is malformed. | The error says which. For an unknown name it lists the folders you do have.                                                                        |
| `ALREADY_EXISTS`      | The name is already used by one of your folders.                                                                                                                     | Names are unique within your own list, ignoring case. List them with [`spawn_profiles`](/mcp-server/spawn-profiles) and reuse the existing folder. |
| `RESOURCE_EXHAUSTED`  | You already hold the maximum of 200 folders.                                                                                                                         | Delete one you no longer use.                                                                                                                      |
| `FAILED_PRECONDITION` | The caller has no personal identity to hold folders.                                                                                                                 | Folders belong to a person; an agent running on a VM has no personal identity and cannot hold them.                                                |

## Related

* [`folder_assign`](/mcp-server/folder-assign) — file agents under a folder, move them, or unfile them
* [`spawn_profiles`](/mcp-server/spawn-profiles) — list your folders and their agent counts
* [`spawn`](/mcp-server/spawn) — file a new agent at spawn time via `folder`
* [`murmur folder ls`](/cli/folder-ls) — the CLI's folder commands