Read model snapshot
layerz_readReturns a UID-native snapshot of a model: model (name, timelines, lists, branches), items (flat, parent_uid carries the hierarchy, each with role, formula, check, note; values are the base plan) and revision_id / version_number. Filters: uids, roles, include_children. with_values: true adds the computed series v aligned with the periods p (periods for explicit labels of mixed grains, else granularity), variance adds vv, per_element adds ve for list-mode items, health adds the check report, branch_id computes v and health under one branch's [base, branch] checkout, else they are the base plan. The check report is judged on a branch checkout: without branch_id, a multi-branch model reports the branch it opens on (health.branch_id) and every branch under health.by_branch. When the response leads with computable: false, errors[] names the broken dependencies (e.g. CIRCULAR_DEPENDENCY) and every series is a zero-filled placeholder. A read without uids or roles also carries conventions (workspace conventions + model FINANCE.md, as in layerz_get_conventions) when either is set, and guidance (the rebuild method of the modeling guide § 12) on a model of 1000 items or more.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "layerz_read"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uids | No | Filter by items: UIDs or names | |
| roles | No | Filter by role | |
| health | No | Also returns the `health` block: non-blocking check violations (lines flagged `check`), evaluated at the finest active grain under a branch checkout: the `branch_id` requested, else on a multi-branch model the branch the model opens on (`health.branch_id`) with every branch's verdict under `health.by_branch`. `with_values: true` already includes `health` when the model has checks; this flag returns `health` without the full value series. | |
| periods | No | Period labels to scope values to | |
| model_id | No | Target model UUID. Required for user-scoped API keys; validated against the bound model for model-scoped keys. | |
| variance | No | Also return the variance series `vv` (the `branch_id` checkout − the base plan), aligned with `v`. Requires with_values and branch_id. | |
| branch_id | No | Branch whose `[base, branch]` checkout the values `v` and the check report `health` are computed under. Absent: the base plan. An unknown id is rejected. Requires with_values or health. | |
| granularity | No | Grain for `v`/`p` when no explicit `periods` are given, among the active timelines (another one: `GRANULARITY_UNAVAILABLE`). 'native' = finest active dated grain (monthly>quarterly>yearly). Default: 'yearly' when the model has it, else 'native'. Ignored when `periods` are provided (each label resolves its own grain). | |
| per_element | No | Also return `ve`: per-element series for list-mode items, keyed `ve[itemUid][elementLabel]` and aligned with `p` (e.g. payroll split by Business Unit). Without it, `v` only carries the aggregate. Requires with_values. | |
| with_values | No | Compute and return values for matched items | |
| include_lists | No | Which named lists to embed in `model.lists`: 'referenced' (default — only lists used by the returned items via liste_ref), 'all', or 'none'. | |
| include_children | No | Include descendants of filtered containers |