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

# Formula authoring for agents

> For agents working on cfo.ai formulas: which tool answers which formula question, why writes go through visible saved tables, and the rules every formula read and write follows.

Formulas belong to saved Variables, and their calculated values appear in saved Table blocks. The Model the user sees is the source of truth for human and agent work alike, so an agent reads and writes formulas through the same tables a person uses. For how cfo.ai chooses a formula for each cell, see [How formulas work](/concepts/formulas.md); for the expression grammar and functions, see [Formula syntax](/reference/formula-syntax.md) and [Formula functions](/reference/functions.md).

Tool messages and field descriptions often call a saved formula a rule. These pages say formula, except when they quote the product.

## Match the tool to the question

Two tools cover formula work. Each takes one action block named for the action.

| The user wants to | Call | Read more |
| - | - | - |
| Know how a Variable or Dimension is calculated | `inspect_table_blocks` with a `variable` or `dimension` block | [Read and explain formulas](/agents/read-formulas.md) |
| See the values a table shows, with row and column references, formula origins, and sources | `inspect_table_blocks` with a `read` block | [Read and explain formulas](/agents/read-formulas.md) |
| Create or change a formula on a visible row, column, or cell | `edit_table_blocks` with an `update` block | [Create and update formulas](/agents/write-formulas.md) |
| Build a new table and its formulas | `edit_table_blocks` with a `create` block | [Create and update formulas](/agents/write-formulas.md) |
| Save a Variable's own formula with no table | `edit_table_blocks` `update` with a `variables` entry and no table `target` | [Create and update formulas](/agents/write-formulas.md#save-a-variables-formula-without-a-table) |
| Check a new table's formulas without saving | `edit_table_blocks` `create` with `dry_run: true` | [Validate and verify formula writes](/agents/validate-and-verify.md) |
| Get an answer from what is already saved | `inspect_table_blocks` reads only | [Analyze saved values without changing the Model](/agents/analyze-without-saving.md) |

A question that existing values can answer stays read-only. A new calculated result needs a visible, saved formula. The user's request is the authorization to create it; a change that is easy to undo from the changelog needs no separate confirmation.

## Start from the visible table

Read the relevant Table block once, reuse the row and column references it returns, and send related edits together. The server derives the Variable, the formula's scope, and its Date grain from that visible target, and the read tells you whether each cell is writable, so you never build those yourself. The range is the one you name: `default_formulas.actuals` or `default_formulas.forecast`.

When the work has no table yet, read the existing Variables and Dimensions first, and reuse their returned references, such as `Revenue#3f2`, when you compose a formula.

Write expressions with readable Variable names. Put backticks around a name that contains spaces, punctuation, or a reserved word, such as `` `Gross Profit` ``. Add a returned reference's short suffix only when two names collide.

## Respect the Scenario

Formulas are Scenario-scoped. Use the Scenario the user is working in, or the one they asked for, and pass it as `scenario` beside the action block. If a write could reasonably go to more than one Scenario, settle which one before you change the Model.

## Keep the condition and the expression apart

A formula has two parts. The condition decides where it applies; the expression decides what it calculates. For a visible table edit, the server derives the condition from the target you choose:

* a row's own formula,
* a `child_defaults` formula that the items beneath a row inherit, or
* one cell.

[Formula scope and formula ranges](/agents/formula-scope.md) covers conditions and Actuals and Forecast ranges.

## Verify the outcome

A formula that parses can still express the wrong business rule. After a material write, read the receipt's warnings and the saved Table block, and compare representative periods and segments with what the user asked for. [Validate and verify formula writes](/agents/validate-and-verify.md) lists what a receipt reports and how to check the numbers.


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