# list_changes

## What it answers

List the account's change log, newest first: who changed what and when on the Project, People (payroll) and Expense grids, scenarios and settings. Each event names the actor (person, agent, import or system), for agents the MCP client and the person whose credentials connected it, the area, row id and label, field, old and new value and the batch id. Filter by area, rowId, field, actorType, actor (person id, connection or key id, import run id or system job), since (inclusive) and until (exclusive) as ISO instants. Page with limit (default 50, maximum 200) and cursor from nextCursor. Requires People grid view because history can carry compensation. Grids backed by Google Sheets are not served: a caveat points to Google Sheets version history. Changes agents make through this server are recorded and visible to the account's people. Read parakeeto://methodology for shared response conventions and INVALID_ARGUMENT guidance.

Read-only.

## Arguments

| Argument | Type | Required | Default | Allowed values |
| --- | --- | --- | --- | --- |
| `account` | string (uuid) | no | — | — |
| `area` | string | no | — | `"projects"`, `"people"`, `"expenses"`, `"scenario"`, `"settings"` |
| `rowId` | string | no | — | `minLength: 1`; `maxLength: 200` |
| `field` | string | no | — | `minLength: 1`; `maxLength: 200` |
| `actorType` | string | no | — | `"person"`, `"agent"`, `"import"`, `"system"` |
| `actor` | string | no | — | `minLength: 1`; `maxLength: 200` |
| `since` | string (date-time) | no | — | — |
| `until` | string (date-time) | no | — | — |
| `limit` | integer | no | `50` | `minimum: 1`; `maximum: 200` |
| `cursor` | string | no | — | `minLength: 1`; `maxLength: 500` |
| `includeDefinitions` | boolean | no | `true` | — |

## Returned fields

The result is an envelope: `ok: true` with `data`, or `ok: false` with `error`. Error codes: `MODEL_CALCULATOR_ACCESS_REQUIRED`, `PAYROLL_GRID_MISSING`, `PAYROLL_GRID_REQUIRED`, `PROJECT_GRID_REQUIRED`, `EXPENSE_GRID_REQUIRED`, `PAYROLL_ENTRY_REFERENCE_STALE`, `ACCOUNT_NOT_FOUND`, `ACCOUNT_CONFIGURATION_MISSING`, `NO_IMPORTED_TIME`, `NOTHING_IMPORTED`, `ACCOUNT_REQUIRED`, `NO_REACHABLE_ACCOUNTS`, `FEATURE_NOT_ENTITLED`, `PERMISSION_DENIED`, `CALCULATION_FAILED`, `INTERNAL_ERROR`, `INVALID_ARGUMENT`.

- `data`: object
  - `data.account`: string (uuid)
  - `data.events`: array of object
    - `data.events[].id`: string (uuid)
    - `data.events[].occurredAt`: string (date-time)
    - `data.events[].actorType`: string (`"person"`, `"agent"`, `"import"`, `"system"`)
    - `data.events[].actorName`: string
    - `data.events[].connectingPerson`: string or null
    - `data.events[].session`: null
    - `data.events[].connectionRef`: string or null
    - `data.events[].area`: string (`"projects"`, `"people"`, `"expenses"`, `"scenario"`, `"settings"`, `"targets"`)
    - `data.events[].rowId`: string
    - `data.events[].rowLabel`: string or null
    - `data.events[].operation`: string (`"create"`, `"update"`, `"delete"`, `"restore"`)
    - `data.events[].field`: string or null
    - `data.events[].oldValue`: any, optional
    - `data.events[].newValue`: any, optional
    - `data.events[].batchId`: string (uuid)
  - `data.truncated`: boolean
  - `data.nextCursor`: string or null
  - `data.latestChangeAt`: string (date-time) or null
  - `data.gridFreshness`: array of object
    - `data.gridFreshness[].kind`: string (`"payroll"`, `"expense"`, `"project"`)
    - `data.gridFreshness[].gridId`: string (uuid)
    - `data.gridFreshness[].name`: string
    - `data.gridFreshness[].storage`: string (`"sheet"`, `"database"`)
    - `data.gridFreshness[].sheetRefreshedAt`: string (date-time) or null
  - `data.caveats`: array of object
    - `data.caveats[].code`: string (`"history-in-google-sheets"`)
    - `data.caveats[].message`: string
  - `data.definitions`: map of string to string, optional
    - `data.definitions.*`: string

On failure:

- `error`: object
  - `error.code`: string (`"MODEL_CALCULATOR_ACCESS_REQUIRED"`, `"PAYROLL_GRID_MISSING"`, `"PAYROLL_GRID_REQUIRED"`, `"PROJECT_GRID_REQUIRED"`, `"EXPENSE_GRID_REQUIRED"`, `"PAYROLL_ENTRY_REFERENCE_STALE"`, `"ACCOUNT_NOT_FOUND"`, `"ACCOUNT_CONFIGURATION_MISSING"`, `"NO_IMPORTED_TIME"`, `"NOTHING_IMPORTED"`, `"ACCOUNT_REQUIRED"`, `"NO_REACHABLE_ACCOUNTS"`, `"FEATURE_NOT_ENTITLED"`, `"PERMISSION_DENIED"`, `"CALCULATION_FAILED"`, `"INTERNAL_ERROR"`, `"INVALID_ARGUMENT"`)
  - `error.argument`: string, optional (`minLength: 1`)
  - `error.message`: string
  - `error.accounts`: array of object, optional
    - `error.accounts[].id`: string (uuid)
    - `error.accounts[].name`: string
  - `error.payrollGrids`: array of object, optional
    - `error.payrollGrids[]`: same shape as `error.accounts[]`
  - `error.projectGrids`: array of object, optional
    - `error.projectGrids[]`: same shape as `error.accounts[]`
  - `error.expenseGrids`: array of object, optional
    - `error.expenseGrids[]`: same shape as `error.accounts[]`
  - `error.context`: object, optional
    - `error.context.account`: object
      - Further fields: see the response.
    - `error.context.imports`: array of object
      - Further fields: see the response.
    - `error.context.hasTimeEntries`: boolean
    - `error.context.reports`: array of object
      - Further fields: see the response.

## Definitions

Returned in `definitions` when `includeDefinitions` is true (the default). It is a map of string to string: each key names a field and each value is its definition text.

## Caveats

- `history-in-google-sheets`.

Read every caveat before interpreting a figure. See [methodology](</methodology.md>) on how to communicate caveats and data-quality conditions.

## Example call

```json
{
  "name": "list_changes",
  "arguments": {}
}
```

Add `account` with an identifier from `list_accounts`; omit it only when the connection reaches exactly one account.