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

# Edit Notes & Folders

> Update note titles and rename, restyle, move, or reorder folders

## Overview

These four write tools let an assistant edit your notes and folder organization on your behalf:

* **`update_note`** — Update a note's title. Scope `mcp:notes:write`.
* **`update_folder`** — Update a folder's title, description, or color. Scope `mcp:folders:write`.
* **`move_folder`** — Move a folder under a different parent, or to the workspace root. Scope `mcp:folders:write`.
* **`reorder_folders`** — Reorder sibling folders within their parent. Scope `mcp:folders:write`.

**When to use:**

* Rename a note after its meeting so the title reflects what actually happened.
* Rename a folder, tidy up its description, or recolor it for at-a-glance grouping.
* Reorganize the folder tree: nest a folder under another, promote it to the workspace root, or change the order siblings appear in.

<Note>
  **User key vs. workspace-system key (folder tools).** For `update_folder`, `move_folder`, and `reorder_folders`: a **user** API key can edit any folder it has edit access to (private or team). A **workspace-system** API key can edit **TEAM (workspace-shared) folders only** — attempts to edit a private folder are rejected. `update_note` works with user, workspace, or organization API keys.
</Note>

## update\_note

Update a note's title.

### Parameters

| Parameter  | Type   | Required | Description                                  |
| ---------- | ------ | -------- | -------------------------------------------- |
| `noteGuid` | string | Required | GUID of the note to update.                  |
| `title`    | string | Required | New note title. 1–100 characters, non-blank. |

### Example

**Request:**

```json theme={"system"}
{
  "noteGuid": "note_9f8c2a1b",
  "title": "Q1 Planning — Kickoff"
}
```

**Response:**

```json theme={"system"}
{
  "noteGuid": "note_9f8c2a1b",
  "title": "Q1 Planning — Kickoff",
  "updatedAt": "2026-07-14T09:30:00Z"
}
```

## update\_folder

Update a folder's title, description, and/or color. This is an AIP-134 field-mask update: **only the fields you pass are changed**, and everything you omit is left untouched. At least one field is required.

### Parameters

| Parameter     | Type   | Required | Description                                               |
| ------------- | ------ | -------- | --------------------------------------------------------- |
| `folderId`    | string | Required | ID of the folder to update.                               |
| `title`       | string | Optional | New folder title. 1–50 characters, non-blank.             |
| `description` | string | Optional | New description. Pass an empty string (`""`) to clear it. |
| `color`       | string | Optional | Folder color as a `#RRGGBB` hex string.                   |

<Note>
  At least one of `title`, `description`, or `color` must be provided. Fields you omit are not modified — this lets you change the color without resending the title, for example.
</Note>

### Example

**Request:**

```json theme={"system"}
{
  "folderId": "12345",
  "title": "Engineering",
  "color": "#4C6EF5"
}
```

**Response:**

```json theme={"system"}
{
  "folderId": "12345",
  "title": "Engineering",
  "description": "Engineering team notes",
  "color": "#4C6EF5"
}
```

## move\_folder

Move a folder under a different parent, or to the workspace root.

### Parameters

| Parameter     | Type   | Required | Description                                                                                |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------ |
| `folderId`    | string | Required | ID of the folder to move.                                                                  |
| `newParentId` | string | Optional | ID of the new parent folder. Pass `null` or omit to move the folder to the workspace root. |

### Example

**Request:**

```json theme={"system"}
{
  "folderId": "12346",
  "newParentId": "12345"
}
```

Moves folder `12346` under folder `12345`.

**Response:**

```json theme={"system"}
{
  "folderId": "12346",
  "title": "Q1 Planning",
  "parentId": "12345"
}
```

To move a folder to the workspace root, omit `newParentId` (or pass `null`):

**Request:**

```json theme={"system"}
{
  "folderId": "12346"
}
```

## reorder\_folders

Reorder sibling folders. Pass the **complete** desired order of a single set of siblings; the workspace is inferred from the first folder ID.

### Parameters

| Parameter          | Type      | Required | Description                                                                                                                             |
| ------------------ | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `orderedFolderIds` | string\[] | Required | The complete desired sibling order (minimum 1 ID). Every sibling must appear exactly once. The workspace is inferred from the first ID. |

### Example

**Request:**

```json theme={"system"}
{
  "orderedFolderIds": ["12347", "12345", "12346"]
}
```

Reorders the three sibling folders so they appear in the given order.

**Response:**

```json theme={"system"}
{
  "orderedFolderIds": ["12347", "12345", "12346"]
}
```

## Scope Requirements

`update_note` requires the `mcp:notes:write` scope; `update_folder`, `move_folder`, and `reorder_folders` require the `mcp:folders:write` scope.

<Note>
  API keys carry all scopes, so any valid API key can call these tools. The `mcp:notes:write` / `mcp:folders:write` scopes matter for **OAuth-based clients**, where the granted scopes gate which tools are callable.
</Note>

Configure your API key at [Tiro Platform API Keys](https://platform.tiro.ooo/dashboard/api-keys).

## Related Tools

* **[`get_note`](./get-note)** — Read a note's current metadata before updating its title.
* **[Folder search](./folder-search)** — Find a folder's `folderId` by name before editing, moving, or reordering it.
* **[`get_note_folders`](./get-note-folders)** — List the folders a note belongs to.