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

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 on how to communicate caveats and data-quality conditions.

Example call

{
  "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.