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

> MCP tool that files agents under a dashboard folder, moves them between folders, or unfiles them.

Files [agents](/concepts/agents) under one of your folders, moving any that are already filed elsewhere. Passing an empty `folder` unfiles them instead, returning them to the dashboard's Unfiled group.

Equivalent to [`murmur folder assign`](/cli/folder-assign) and [`murmur folder unfile`](/cli/folder-unfile) in the CLI.

The folder must already exist — create it with [`folder`](/mcp-server/folder). Naming one that does not exist is an error listing the folders that do, never a silent create: a folder is one person's own organization of their sidebar.

## Parameters

| Name        | Type      | Required | Description                                                                                                                                                                                                               |
| ----------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `folder`    | string    | yes      | The folder to file these agents under, by name, as listed by [`spawn_profiles`](/mcp-server/spawn-profiles). Pass `""` to unfile them instead. Omitting it is an error, not an unfile.                                    |
| `slugs`     | string\[] | yes      | Agent slugs to file. Each must be a top-level agent you can read; use an absolute path like `/w/{workspace}/{owner_provider}/{account}/{slug}` for an agent outside your own path. They must all belong to one workspace. |
| `workspace` | string    | no       | Workspace name. Overrides the session default.                                                                                                                                                                            |

<Warning>
  `folder` is required and `""` is a real value: it unfiles. Omitting the parameter is rejected rather than treated as `""`, so a call that forgets it cannot silently empty a folder.
</Warning>

<Note>
  Folders hold top-level agents. A child agent renders under its root in the dashboard, so it cannot be filed on its own.
</Note>

## Response

| Field             | Type   | Description                                                                                                                                                                             |
| ----------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `updated_members` | number | How many agents changed folder, counting those filed, moved, and unfiled. An agent already in the named folder is not counted, so `0` means the call was a no-op rather than a failure. |

## Examples

### File two agents

```json theme={null}
{
  "folder": "Release 4.2",
  "slugs": ["fix-auth", "bump-deps"],
  "workspace": "backend"
}
```

Response:

```json theme={null}
{
  "updated_members": 2
}
```

### Unfile an agent

```json theme={null}
{
  "folder": "",
  "slugs": ["bump-deps"]
}
```

## Errors

| Code                  | Meaning                                                                                                                                        | What to do                                                                                                                     |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `INVALID_ARGUMENT`    | No folder of yours has that name, `folder` was omitted, an agent is not top-level, an agent is named twice, or the agents span two workspaces. | The error says which. List folders with [`spawn_profiles`](/mcp-server/spawn-profiles) and agents with [`ls`](/mcp-server/ls). |
| `NOT_FOUND`           | No agent with that slug exists.                                                                                                                | Check the slug with [`ls`](/mcp-server/ls).                                                                                    |
| `PERMISSION_DENIED`   | You cannot read one of the named agents.                                                                                                       | Filing requires `agent.read` on every agent named.                                                                             |
| `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

* [`murmur folder assign`](/cli/folder-assign) — equivalent CLI command
* [`murmur folder unfile`](/cli/folder-unfile) — the CLI's spelling for `folder: ""`
* [`folder`](/mcp-server/folder) — create the folder first
* [`spawn`](/mcp-server/spawn) — file a new agent at spawn time via `folder`