# get_financial_overview

## What it answers

Read Executive Dashboard values from manually keyed imported Data Inputs, read-only Target Inputs, definitions, trailing averages and dashboard import freshness. Optional inclusive YYYY-MM range; defaults to the latest twelve available months. No person-level data. This is the Executive Dashboard imported snapshot, including frozen capacity/hours and read-only Target Inputs J/K monthly targets, and follows the template ratio of three-month averages; follow its inline report definitions. Read parakeeto://methodology for shared response conventions and INVALID_ARGUMENT guidance.

Read-only.

## Arguments

| Argument | Type | Required | Default | Allowed values |
| --- | --- | --- | --- | --- |
| `account` | string (uuid) | no | — | — |
| `includeDefinitions` | boolean | no | `true` | — |
| `range` | object | no | — | — |
| `range.from` | string | yes | — | pattern `^\d{4}-(?:0[1-9]\|1[0-2])$` |
| `range.to` | string | yes | — | pattern `^\d{4}-(?:0[1-9]\|1[0-2])$` |

## 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.availableMonths`: array of string
  - `data.availableRange`: object
    - `data.availableRange.first`: string (pattern `^\d{4}-(?:0[1-9]|1[0-2])$`)
    - `data.availableRange.last`: string (pattern `^\d{4}-(?:0[1-9]|1[0-2])$`)
  - `data.selectedRange`: object or null
    - `data.selectedRange.first`: string (pattern `^\d{4}-(?:0[1-9]|1[0-2])$`)
    - `data.selectedRange.last`: string (pattern `^\d{4}-(?:0[1-9]|1[0-2])$`)
  - `data.months`: array of object
    - `data.months[].month`: string (pattern `^\d{4}-(?:0[1-9]|1[0-2])$`)
    - `data.months[].leadershipDashboard`: object
      - `data.months[].leadershipDashboard.financial`: object or null
        - `data.months[].leadershipDashboard.financial.income`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
        - `data.months[].leadershipDashboard.financial.agi`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
        - `data.months[].leadershipDashboard.financial.deliveryExpenses`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
        - `data.months[].leadershipDashboard.financial.salesMarketingExpenses`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
        - `data.months[].leadershipDashboard.financial.adminExpenses`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
        - `data.months[].leadershipDashboard.financial.facilitiesExpenses`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
        - `data.months[].leadershipDashboard.financial.month`: string (pattern `^\d{4}-(?:0[1-9]|1[0-2])$`)
      - `data.months[].leadershipDashboard.utilization`: object or null
        - `data.months[].leadershipDashboard.utilization.grossCapacity`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
        - `data.months[].leadershipDashboard.utilization.deliveryCapacity`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
        - `data.months[].leadershipDashboard.utilization.deliveryHours`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
        - `data.months[].leadershipDashboard.utilization.month`: string (pattern `^\d{4}-(?:0[1-9]|1[0-2])$`)
      - `data.months[].leadershipDashboard.calculations`: object or null
        - `data.months[].leadershipDashboard.calculations.incomeShare`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
        - `data.months[].leadershipDashboard.calculations.deliveryExpenseShare`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
        - `data.months[].leadershipDashboard.calculations.salesMarketingExpenseShare`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
        - `data.months[].leadershipDashboard.calculations.adminExpenseShare`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
        - `data.months[].leadershipDashboard.calculations.facilitiesExpenseShare`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
        - `data.months[].leadershipDashboard.calculations.deliveryIncome`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
        - `data.months[].leadershipDashboard.calculations.deliveryMargin`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
        - `data.months[].leadershipDashboard.calculations.operatingIncome`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
        - `data.months[].leadershipDashboard.calculations.operatingMargin`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
        - `data.months[].leadershipDashboard.calculations.abr`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
        - `data.months[].leadershipDashboard.calculations.utilization`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
      - `data.months[].leadershipDashboard.comparisons`: object
        - `data.months[].leadershipDashboard.comparisons.income`: object
          - `data.months[].leadershipDashboard.comparisons.income.actual`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
          - `data.months[].leadershipDashboard.comparisons.income.target`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
          - `data.months[].leadershipDashboard.comparisons.income.delta`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
        - `data.months[].leadershipDashboard.comparisons.agi`: same shape as `data.months[].leadershipDashboard.comparisons.income`
        - `data.months[].leadershipDashboard.comparisons.abr`: same shape as `data.months[].leadershipDashboard.comparisons.income`
        - `data.months[].leadershipDashboard.comparisons.utilization`: same shape as `data.months[].leadershipDashboard.comparisons.income`
        - `data.months[].leadershipDashboard.comparisons.deliveryMargin`: same shape as `data.months[].leadershipDashboard.comparisons.income`
        - `data.months[].leadershipDashboard.comparisons.operatingMargin`: same shape as `data.months[].leadershipDashboard.comparisons.income`
    - `data.months[].missing`: array of object
      - `data.months[].missing[].code`: string (`"MISSING_INPUT"`, `"UNDEFINED_RATIO"`, `"MISSING_TARGET"`)
      - `data.months[].missing[].message`: string
      - `data.months[].missing[].fields`: array of string
  - `data.trailing`: object
    - `data.trailing.leadershipDashboard`: object
      - `data.trailing.leadershipDashboard.definition`: string
      - `data.trailing.leadershipDashboard.trailingAverages`: object
        - `data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare`: object
          - `data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare.months`: array of string
          - `data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare.value`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
        - `data.trailing.leadershipDashboard.trailingAverages.salesMarketingExpenseShare`: same shape as `data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare`
        - `data.trailing.leadershipDashboard.trailingAverages.adminExpenseShare`: same shape as `data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare`
        - `data.trailing.leadershipDashboard.trailingAverages.facilitiesExpenseShare`: same shape as `data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare`
        - `data.trailing.leadershipDashboard.trailingAverages.operatingMargin`: same shape as `data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare`
        - `data.trailing.leadershipDashboard.trailingAverages.deliveryMargin`: same shape as `data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare`
        - `data.trailing.leadershipDashboard.trailingAverages.abr`: same shape as `data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare`
        - `data.trailing.leadershipDashboard.trailingAverages.utilization`: same shape as `data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare`
        - `data.trailing.leadershipDashboard.trailingAverages.agi`: same shape as `data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare`
      - `data.trailing.leadershipDashboard.targetAverages`: object
        - `data.trailing.leadershipDashboard.targetAverages.income`: same shape as `data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare`
        - `data.trailing.leadershipDashboard.targetAverages.agi`: same shape as `data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare`
        - `data.trailing.leadershipDashboard.targetAverages.abr`: same shape as `data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare`
        - `data.trailing.leadershipDashboard.targetAverages.utilization`: same shape as `data.trailing.leadershipDashboard.trailingAverages.deliveryExpenseShare`
  - `data.monthlyTargets`: array of object
    - `data.monthlyTargets[].income`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.monthlyTargets[].agi`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.monthlyTargets[].abr`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.monthlyTargets[].utilization`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.monthlyTargets[].deliveryMargin`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.monthlyTargets[].operatingMargin`: string or null (pattern `^-?\d+(?:\.\d+)?$`)
    - `data.monthlyTargets[].month`: string (pattern `^\d{4}-(?:0[1-9]|1[0-2])$`)
  - `data.freshness`: array of object
    - `data.freshness[].source`: string (`"time-entries"`, `"role-task-mappings"`, `"annual-days"`, `"dashboard-inputs"`)
    - `data.freshness[].everCompleted`: boolean
    - `data.freshness[].completedAt`: string (date-time) or null
  - `data.definitions`: map of string to string, optional
    - `data.definitions.*`: string
  - `data.caveats`: array of object
    - `data.caveats[].code`: string
    - `data.caveats[].message`: 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

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_financial_overview",
  "arguments": {}
}
```

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