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 .
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 to copy versions, fill months from actuals, and lock the agreed plan.
• Comment on financial statements to discuss variances against the plan on the statement cells.
• Review budget variances with comments through an AI client that reads these explanations.