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

# Sheets tools

> Discover worksheets, inspect formulas and results, find cells, and delete spreadsheet documents

The Sheets tools access the same documents as the Finta editor. A **sheet** is the whole document; its **worksheets** are individual tabs. Tools return the document's editor link so you can open the result in Finta.

| Tool | Purpose | Required permission |
| - | - | - |
| `list_sheets` | Find documents by name, with pagination | Forecast: View |
| `get_sheet` | Inspect worksheet metadata or selected values/formulas | Forecast: View |
| `search_sheet_cells` | Find authored cell contents or formula text | Forecast: View |
| `delete_sheet` | Permanently delete a document and all its tabs | Forecast: Manage |

Company access and existing entitlements still apply. The tools use your connected Finta identity; you do not supply a company ID. See [MCP setup](/docs/mcp/introduction) to connect.

## Find the right worksheet

For a request such as “What hiring assumptions are in our cash forecast?”, first find the document:

```json theme={null}
{"query":"cash forecast","limit":20}
```

Pass this to `list_sheets`. Each result contains `id`, `name`, `url`, and document-wide `revision`. Pass the result ID to `get_sheet`:

```json theme={null}
{"id":"sht_example"}
```

Without `ranges`, this returns metadata, including worksheet IDs, names, used ranges and grid dimensions. It does not download every cell or run financial calculations. Worksheet IDs are stable IDs, not zero-based tab positions.

Use `search_sheet_cells` to locate a label before reading nearby assumptions:

```json theme={null}
{"id":"sht_example","query":"hiring","match":"contains"}
```

`contains` is the default; `exact` requires the whole authored text to match. Both are case-insensitive. Results identify the worksheet ID/name, A1 cell and saved input string. This searches authored inputs and formula text, **not evaluated results**. To search only one tab, supply its `worksheet_id`.

Both list and search accept `limit` from 1 to 500 (default 100) and opaque `starting_after`. Pass `next_cursor` back unchanged with the same filters. Search cursors are tied to the document revision; if it changes, restart the search without the old cursor.

## Read formulas alongside results

Call `get_sheet` with qualified A1 ranges:

```json theme={null}
{
  "id": "sht_example",
  "ranges": ["'Plan'!A1:B2"],
  "view": "both",
  "include": ["formats", "charts"]
}
```

The `'Plan'` part is the tab name. For a name containing an apostrophe, double it: `'Bob''s Plan'!A1`. Alternatively supply `worksheet_id` and an unqualified range like `A1:B2`. If both forms identify a worksheet, they must agree. A bare range without an ID works only when the document has one worksheet.

| `view` | Returned content |
| - | - |
| `values` | Calculated values; the default |
| `formulas` | Saved formula strings, with null for other cells; skips calculation |
| `both` | Formulas and calculated values |

Values and formulas use rectangular row-major arrays. Up to 100 ranges and 10,000 selected cells are accepted per call. Read ranges must fit the existing grid; metadata gives `row_count` and `column_count`.

`include` is an array in MCP, unlike the HTTP comma-separated query parameter. `formats` returns explicit formatting for selected cells. `charts` returns embedded chart definitions, not images. Omit both to keep the response smaller.

## Interpret the result

Sheet cells preserve worksheet units. An amount of \$20,000 is `20000`; do not divide it by 100 because other financial API fields use cents. Saved FINTA formulas calculate using the existing formula engine and financial authorization. Saved numbers remain snapshots. Authored whitespace-only strings remain text in calculated values rather than becoming numeric zero.

Inspect `calculation.status` whenever values were requested:

* `complete`: evaluation finished without formula errors; warnings can remain.
* `error`: one or more formulas failed; inspect the errors and affected null cells.
* `unavailable`: value matrices are omitted. Readable formulas remain available with `both`; retry the selected read when appropriate.

Formula-only reads do not include calculation status. Calculation creates no background job to poll. Warnings such as `uncategorized_transactions` qualify the result rather than changing the saved formula. See [calculation details](/docs/api-reference/sheets#cell-units-and-live-calculation).

## Delete a document

Use `delete_sheet` only when the user intends to remove the whole document and every worksheet:

```json theme={null}
{"id":"sht_example","base_revision":3}
```

Use the current revision from a read. Success returns:

```json theme={null}
{"id":"sht_example","deleted":true}
```

A `revision_conflict` means the document changed. Reread it and reconsider the deletion before retrying; do not blindly substitute `current_revision`. Missing documents return `resource_missing`. Deleting a sheet is not a way to clear cells or remove one tab.

## Prompts to try

* “Find our cash forecast and show the hiring assumptions alongside their formulas.”
* “Which cells in the income statement contain FINTA formulas?”
* “Show the saved growth-rate assumption and the calculated ending cash from the Plan tab.”

For HTTP examples, limits and error recovery, see [Sheets](/docs/api-reference/sheets).


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