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

# Explain budget values and attach source files

> Record why a budget cell has its value, see who explained it and whether it still applies, and keep the documents behind the plan with the budget.

Use explanations to record why a budget cell has its value: the driver, the source, and the assumptions. Use attachments to keep the documents behind the plan, such as a board deck, hiring plan, or price list, with the budget. Reviewers see both in Control, and an AI client can read them before it changes a number or explains a variance.

## Who can do what

| Action | Who can do it |
| - | - |
| Read explanations, read and download attachments | Anyone who can open the budget, including viewers |
| Add, edit, confirm, or remove explanations; manage attachments | Users who can edit the budget, while it is unlocked |
| Write budget values or explanations through an AI client | Users whose AI client connection has write access; every value written must be explained |

## How explanations work

* An explanation belongs to one cell in one month: an account total, or an entity, local account, dimension item, or counterparty row beneath it. A total keeps its own explanation. **Unallocated** rows have none.
* An explained cell shows a green marker in its top-right corner. The marker turns grey when the value has changed since the explanation was written.
* Typing a new value in Control does not require an explanation and keeps the existing one, which then shows as outdated until someone confirms or changes it.
* An explanation stays while its cell holds an amount. Clearing the value removes the explanation; the change history keeps its text.
* **Fill months from actuals** removes the explanations of the cells it replaces with the ledger. The snapshot taken before the fill keeps them.
* **Copy as new version** keeps the explanations, and restoring a snapshot brings back the explanations it held.

## Read an explanation

1. Open the budget in (Budgets).
2. Point at a cell with a green marker. The note opens after a moment and closes when you move away.
3. To keep the note open, select the cell.

The note shows:

* the row path and month, for example **Subscription revenue › Example Oy · Jan 27**;
* the explanation;
* who last wrote or confirmed it, followed by **via MCP** when it came from an AI client (or **via API** or **by the system**; nothing is added for an explanation written in Control);
* when it was written, with the exact time on hover, and **(edited)** when it changed later;
* for an outdated explanation, **Written when the value was** with the old and current values.

## Add or change an explanation

1. Right-click a cell that holds an amount and choose **Add explanation…**. For an explained cell, choose **Explanation…** and select **Edit**.
2. Write why the cell has this value, for example the driver, the source, and the assumptions. An explanation can be up to 1,000 characters.
3. Select **Save**, or press ⌘Enter or Ctrl+Enter.

To delete an explanation, open the note and select **Remove**.

The explanation is saved against the value the cell had when the note opened. If someone else changes the budget in the meantime, the note closes instead of saving; reopen it and check the new value.

## Confirm an outdated explanation

When a value changes after its explanation was written, the marker turns grey and the note shows the old and current values.

1. Open the note on the cell.
2. If the explanation still applies to the current value, select **Confirm**. Otherwise, select **Edit**, update the text, and select **Save**.

After you confirm, the marker turns green again and the note names you as the person who stands behind the explanation.

## Explanations from an AI client

Every budget value an AI client writes through Control's Model Context Protocol (MCP) server must carry an explanation. The client can give one per value, one shared explanation for the whole change, or a description column in an import file. Control rejects a write without one and saves none of its values. **Unallocated** remainders need no explanation.

| Tool | Use it to |
| - | - |
| `get_budget_plan_values` | Read the values with each explanation, the value it was written for, who wrote or confirmed it, the channel, and when. |
| `set_budget_group_account_monthly_values` | Change a few values, each with its explanation. |
| `describe_budget_cells` | Explain values that are already in the budget, or correct an explanation, without changing any amount. |
| `get_budget_change_history` | Read past changes with their explanations, before and after values, author, and time. |

Explanations from an AI client are saved under the name of the person who connected it and show **via MCP** in the note. Ask the client to explain only what you or a source states; an explanation should not be invented to pass the check.

## See explanations in the change history

1. On the budget page, open **Actions** and select **History**.
2. On the **History & recovery** tab, find **Cell changes**. Each entry shows the number of cell changes and explanations, when they were made, and by whom.
3. Expand an entry to see each change.

| Entry | Meaning |
| - | - |
| **Explained** | A cell got its first explanation. |
| **Explanation changed** | The text changed. The previous text is shown struck through. |
| **Explanation confirmed for a new amount** | Someone confirmed the same text for a changed value. |
| **Explanation removed** | The explanation was removed, or its cell no longer holds an amount. |

A value change shows its before and after amounts with the explanation given with it, or **No explanation recorded.** when it was typed without one. Under **Snapshots**, **Changes** also lists the explanations that changed since the previous snapshot.

## Attach source files

1. On the budget page, open **Actions** and select **Attachments**. The count in brackets shows how many files the budget has.
2. Drop files on the panel, or select **Choose files**.
3. To describe a file, select its pencil icon and add a **Title** and a **Note** saying what the file is and how it relates to the budget, then select **Save**.

| Detail | Limit |
| - | - |
| File types | PDF, Excel (.xlsx), CSV, text, JSON, YAML, XML, and PNG, JPEG, WebP, or GIF images. Convert .xls files to .xlsx or CSV. |
| Size | Up to 25 MB per file in Control; up to 10 MB per file through an AI client |
| Number | Up to 10 files at a time and 50 per budget |
| Locked budget | Files can be read and downloaded, not added, edited, or removed |

Each file shows its title or file name, size, and when it was added. Select the download icon to save a copy. Removing a file takes it off the budget's list; a snapshot taken while it was attached can bring it back. Copies of the budget keep its attachments.

### How an AI client reads attachments

The budget **Assistant** and AI clients connected through MCP can read the text of attached files: tables from CSV and .xlsx, the text layer of a PDF, and text, JSON, YAML, or XML files.

| Tool | Use it to |
| - | - |
| `list_budget_attachments` | List a budget's files with their title, note, kind, size, and the user who added them. |
| `read_budget_attachment` | Read a file's extracted text, one page at a time. |
| `upload_budget_attachment` | Attach a file with a title and a note. This needs write access, and the budget must be unlocked. |

Images, scanned PDFs without a text layer, and password-protected PDFs cannot be read as text. Control marks images **not readable by the assistant**, and `read_budget_attachment` says why a file has no text. An AI client treats attachment text as reference material, not as Control data.

## Troubleshooting

| Problem | Resolution |
| - | - |
| **Add explanation…** is missing or unavailable | Right-click a cell that holds an amount. **Unallocated** rows have no explanation of their own. Unlock the budget, or finish or retry a pending save. |
| The note says the budget is locked | Unlock the budget to change explanations or attachments, or copy it as a new version and explain values there. |
| An AI client's budget write was rejected | Give every changed value an explanation, or one shared explanation for the change, and submit again. Nothing from the rejected write was saved. |
| Explanations disappeared after filling months from actuals | The fill removed the explanations of the cells it replaced. Open **History** and use the snapshot taken before the fill to review them. |
| An attachment says it is not readable | Attach a text-based version, such as a PDF with a text layer, a CSV, or an .xlsx export. |

## Next steps

* [Plan and review a budget](https://control-dev.mintlify.site/product-docs/budgets/plan-and-review.md) to copy versions, fill months from actuals, and lock the agreed plan.
* [Comment on financial statements](https://control-dev.mintlify.site/product-docs/reporting/statement-comments.md) to discuss variances against the plan on the statement cells.
* [Review budget variances with comments](https://control-dev.mintlify.site/product-docs/ai/use-cases/bva-review-with-comments.md) through an AI client that reads these explanations.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.