Keep the chart of accounts up to date

# Chart of accounts maintenance

## ⚠️ Write tools in Beta

`create_accounts`, `update_accounts` and `delete_accounts` need the "Manage chart of accounts" permission, off by default: an Admin or Account Owner enables it on the connection, then the user reconnects and ticks it.

These tools **fail outright** when the chart of accounts is managed by the company's accounting integration (pull or bidirectional mode): the change is then made in the accounting software. Do not retry.

Before each action, tell the user what is about to change (account name, code, type) and wait for their go-ahead.

## Step 1 — Always read before writing

```json
{ "tool": "get_chart_of_accounts", "params": { "searchTerm": "<code or label>", "includeArchived": true } }
```

`includeArchived: true` is essential here: without it, archived accounts are invisible, and you risk recreating an account that already exists in the archive. Verified live: searching "MCP TEST" returned nothing by default, and three archived accounts with `includeArchived`, two of them already holding the codes being considered.

Useful filters: `accounts` (types: `expense`, `supplier`, `employee`, `tax`, `bank`, `reverseCharge`), `purpose`, `isAvailable`.

## Step 2 — Create

```json
{
  "tool": "create_accounts",
  "params": {
    "type": "expense",
    "accounts": [ { "name": "Seminars and events", "code": "623800", "description": "…" } ]
  }
}
```

- One `type` per call, 100 accounts at most. Each account needs `name` and at least `code` or `externalId`.
- The batch is applied **in one transaction**: it all succeeds or all fails.
- The response can hold **fewer** accounts than you sent (two items resolving to the same account merge). Report the number of accounts returned, not the number sent.

⚠️ **`create_accounts` is also an upsert, and that is its trap.** An account sent without an `id` but with a `code` matching an active account of the same type **updates that account** instead of creating one. And any update through this tool **rewrites the whole account**: every omitted field (description, auxiliary code, external ID, tax rate…) is set back to empty, and an omitted `externalId` erases the ERP link. To change an existing account, use `update_accounts`.

## Step 3 — Edit

```json
{
  "tool": "update_accounts",
  "params": { "accounts": [ { "id": "<account id>", "name": "New label" } ] }
}
```

- Partial update: only the fields sent change. Verified live: the rename left the code and description untouched.
- Validation is all-or-nothing (one unknown `id` cancels everything), but then each account is handled separately: read `failed` and resend only the failures.
- `purpose` and `isAvailable` cannot be changed with any tool.

## Step 4 — Archive

```json
{ "tool": "delete_accounts", "params": { "accountId": "<account id>" } }
```

Despite its name, this tool **archives**: the account is not deleted. Observed response: `{ "id": "…", "isArchived": true }`. One account at a time.

- Reversible with `update_accounts` and `isArchived: false`.
- **What is not reversible**: archiving releases the suppliers and employees assigned to the account, and unarchiving does not restore those assignments.
- Unarchiving an account gives it back its `purpose`, which is then removed from the active account that held it. Check who holds it first.

## Step 5 — Read back

Read again with `get_chart_of_accounts` to confirm. Reads are cached for 24 hours, but a successful write through these tools clears the company's cache. A change made outside the MCP (Spendesk app, accounting sync) can take up to 24 hours to appear.

## What was tested

Tested live on the demo account on 5 October 2026: creating a test expense account (code 699997), renaming it, archiving it, then reading back — absent from the default list, present with `includeArchived`. Not tested: the upsert by code, the `purpose` change and unarchiving, described from the tools' documentation.

## Example user prompts

- "Add an expense account 623800 Seminars and events"
- "Rename account 625100 to Business travel"
- "Does account 601000 already exist, including in the archive?"
- "Archive the test account 699997"