# get_model_scenario

## What it answers

Calculate the stored Model Calculator baseline plus up to four independent, named what-if scenarios over required inclusive calendar range.from/to dates. Requires administrator, Payroll Grid or Model Calculator access. Compensation appears only as department totals. Include/exclude existing opaque row references from list_payroll_entries; stale references require relisting. Choose payrollGridId or expenseGridId when multiple grids exist. Override any of the ten editable inputs with finite decimal strings, including zero; utilization is a fraction. Undefined figures are null with causal caveats; shares divide only by modelled AGI. Stored freshness does not claim the live Sheet is unchanged. Reads stored snapshots only, writes no grids or settings and saves no scenario; use save_scenario to keep one, and list_scenarios and get_scenario to read saved ones. Read parakeeto://methodology for INVALID_ARGUMENT guidance before interpreting modelled AGI, which is capacity × ABR × utilization rather than actual billings less pass-through.

Read-only.

## Arguments

| Argument | Type | Required | Default | Allowed values |
| --- | --- | --- | --- | --- |
| `account` | string (uuid) | no | — | — |
| `includeDefinitions` | boolean | no | `true` | — |
| `payrollGridId` | string (uuid) | no | — | — |
| `expenseGridId` | string (uuid) | no | — | — |
| `range` | object | yes | — | — |
| `range.from` | string | yes | — | pattern `^\d{4}-\d{2}-\d{2}$` |
| `range.to` | string | yes | — | pattern `^\d{4}-\d{2}-\d{2}$` |
| `scenarios` | array of object | no | `[]` | `maxItems: 4` |
| `scenarios[].name` | string | yes | — | `minLength: 1` |
| `scenarios[].include` | array of string | no | — | — |
| `scenarios[].exclude` | array of string | no | — | — |
| `scenarios[].overrides` | object | no | — | — |
| `scenarios[].overrides.grossCapacity` | string | no | — | pattern `^-?\d+(?:\.\d+)?$` |
| `scenarios[].overrides.modelAbr` | string | no | — | pattern `^-?\d+(?:\.\d+)?$` |
| `scenarios[].overrides.modelUtilization` | string | no | — | pattern `^-?\d+(?:\.\d+)?$` |
| `scenarios[].overrides.deliveryPayrollBudget` | string | no | — | pattern `^-?\d+(?:\.\d+)?$` |
| `scenarios[].overrides.deliveryExpenseBudget` | string | no | — | pattern `^-?\d+(?:\.\d+)?$` |
| `scenarios[].overrides.smPayrollBudget` | string | no | — | pattern `^-?\d+(?:\.\d+)?$` |
| `scenarios[].overrides.smExpenseBudget` | string | no | — | pattern `^-?\d+(?:\.\d+)?$` |
| `scenarios[].overrides.adminPayrollBudget` | string | no | — | pattern `^-?\d+(?:\.\d+)?$` |
| `scenarios[].overrides.adminExpenseBudget` | string | no | — | pattern `^-?\d+(?:\.\d+)?$` |
| `scenarios[].overrides.facilitiesExpenseBudget` | string | no | — | pattern `^-?\d+(?:\.\d+)?$` |

## 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.range`: object
    - `data.range.from`: string (pattern `^\d{4}-\d{2}-\d{2}$`)
    - `data.range.to`: string (pattern `^\d{4}-\d{2}-\d{2}$`)
  - `data.payrollGrid`: object
    - `data.payrollGrid.id`: string (uuid)
    - `data.payrollGrid.name`: string
  - `data.expenseGrid`: object or null
    - `data.expenseGrid.id`: string (uuid)
    - `data.expenseGrid.name`: string
  - `data.annualDays`: string (pattern `^-?\d+(?:\.\d+)?$`)
  - `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.baseline`: object
    - `data.baseline.name`: string
    - `data.baseline.inputs`: object
      - `data.baseline.inputs.grossCapacity`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
      - `data.baseline.inputs.modelAbr`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
      - `data.baseline.inputs.modelUtilization`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
      - `data.baseline.inputs.deliveryPayrollBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
      - `data.baseline.inputs.deliveryExpenseBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
      - `data.baseline.inputs.smPayrollBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
      - `data.baseline.inputs.smExpenseBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
      - `data.baseline.inputs.adminPayrollBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
      - `data.baseline.inputs.adminExpenseBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
      - `data.baseline.inputs.facilitiesExpenseBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.baseline.outputs`: object
      - `data.baseline.outputs.agencyGrossIncome`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
      - `data.baseline.outputs.modelDeliveryBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
      - `data.baseline.outputs.modelSmBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
      - `data.baseline.outputs.modelAdminBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
      - `data.baseline.outputs.modelFacilitiesBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
      - `data.baseline.outputs.modelOperatingIncome`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.baseline.shares`: object
      - `data.baseline.shares.modelDeliveryBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
      - `data.baseline.shares.modelSmBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
      - `data.baseline.shares.modelAdminBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
      - `data.baseline.shares.modelFacilitiesBudget`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
      - `data.baseline.shares.modelOperatingIncome`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.baseline.caveats`: array of object
      - `data.baseline.caveats[].code`: string
      - `data.baseline.caveats[].message`: string
      - `data.baseline.caveats[].reference`: string, optional
  - `data.scenarios`: array of object
    - `data.scenarios[]`: same shape as `data.baseline`
  - `data.definitions`: object, optional
    - `data.definitions.annualDays`: string
    - `data.definitions.inputs.grossCapacity`: string
    - `data.definitions.inputs.modelAbr`: string
    - `data.definitions.inputs.modelUtilization`: string
    - `data.definitions.inputs.deliveryPayrollBudget`: string
    - `data.definitions.inputs.deliveryExpenseBudget`: string
    - `data.definitions.inputs.smPayrollBudget`: string
    - `data.definitions.inputs.smExpenseBudget`: string
    - `data.definitions.inputs.adminPayrollBudget`: string
    - `data.definitions.inputs.adminExpenseBudget`: string
    - `data.definitions.inputs.facilitiesExpenseBudget`: string
    - `data.definitions.outputs.agencyGrossIncome`: string
    - `data.definitions.outputs.modelDeliveryBudget`: string
    - `data.definitions.outputs.modelSmBudget`: string
    - `data.definitions.outputs.modelAdminBudget`: string
    - `data.definitions.outputs.modelFacilitiesBudget`: string
    - `data.definitions.outputs.modelOperatingIncome`: string
    - `data.definitions.shares.modelDeliveryBudget`: string
    - `data.definitions.shares.modelSmBudget`: string
    - `data.definitions.shares.modelAdminBudget`: string
    - `data.definitions.shares.modelFacilitiesBudget`: string
    - `data.definitions.shares.modelOperatingIncome`: string
  - `data.caveats`: array of object
    - `data.caveats[]`: same shape as `data.baseline.caveats[]`

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). Each value is the definition text for that field.

- `annualDays`
- `inputs.grossCapacity`
- `inputs.modelAbr`
- `inputs.modelUtilization`
- `inputs.deliveryPayrollBudget`
- `inputs.deliveryExpenseBudget`
- `inputs.smPayrollBudget`
- `inputs.smExpenseBudget`
- `inputs.adminPayrollBudget`
- `inputs.adminExpenseBudget`
- `inputs.facilitiesExpenseBudget`
- `outputs.agencyGrossIncome`
- `outputs.modelDeliveryBudget`
- `outputs.modelSmBudget`
- `outputs.modelAdminBudget`
- `outputs.modelFacilitiesBudget`
- `outputs.modelOperatingIncome`
- `shares.modelDeliveryBudget`
- `shares.modelSmBudget`
- `shares.modelAdminBudget`
- `shares.modelFacilitiesBudget`
- `shares.modelOperatingIncome`

## Caveats

Codes are not enumerated in the schema; read each `code` and `message`.

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

## Example call

```json
{
  "name": "get_model_scenario",
  "arguments": {
    "range": {
      "from": "2026-10-05",
      "to": "2026-10-09"
    }
  }
}
```

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