Get average monthly burn
well_get_burnGet the workspace's average monthly burn — the trailing average of actual outflows, the exact same computation and number the Well app's avg-burn KPI tile shows. Use this instead of summing transactions yourself.
Returns amount (a positive magnitude, not a signed figure) and currency, plus the window it was measured over: trailing_months is the window length, months_in_window and months_with_data say how much of it actually carried outflow.
per_month is the outflow of each month in that window, oldest first — the numbers the average is the mean of. A month with no recorded outflow is present with 0, not omitted, so the series and the average always agree; do not drop those months when you describe the trend. Use it to say whether burn is rising or falling. amount is the figure the app shows, so it is the one you lead with and the one you call the burn — never put a figure computed from the series in its place. If a dark month looks like a data gap rather than a real month of no spend, say it may be a gap; amount stays the headline either way.
change is a percentage against baseline, not against anything in per_month. baseline.period names the months it was measured over. That window anchors earlier than amount, so it normally covers a month this payload does not carry, and you usually cannot recompute change from the series. The two windows normally SHARE months, so this is a comparison between two overlapping averages rather than between two independent periods — a small change says less about a real shift than the same figure across separate periods would. When you quote change, say what it compares: baseline.period against the window in per_month. To describe movement WITHIN the displayed window, compute it from per_month and say so.
trend is whether the change is GOOD, not which way the number went. trend_polarity is lower_is_better for burn, so trend: "up" means burn FELL (the app renders it green) and "down" means burn ROSE. Never narrate trend: "up" as burn rising — read the sign of change for direction.
State the window whenever you present the number. The average always divides by months_in_window, so when months_with_data is lower the figure is a real average over a window containing dark months, NOT an average of only the months that had spend — say so rather than presenting it as the typical monthly outflow.
unavailable: true means amount is a placeholder rather than a measurement (e.g. nothing has synced yet) — a burn of zero standing on nothing measured is not a reading, so say that instead of reporting a €0 burn. partial: true means individual transactions were excluded from an otherwise real figure (e.g. a missing FX rate); disclose the exclusion count and any hints.
Pass year + month to measure a past period instead of the live window, and months_back to change the window length (default 3).
For months of cash left, call well_get_runway — it composes this burn with the cash position. For what the spend is made of, call well_get_cost_structure. Neither is a decomposition of the other: cost structure covers a single closed month and will not sum to a trailing average.
When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass workspace_id on the call.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | Calendar year of the reporting period, e.g. 2026. Must be given together with `month`. | |
| month | No | Calendar month of the reporting period, 1 = January … 12 = December. Must be given together with `year`. Omit both to read the live/current figure. | |
| months_back | No | How many closed months to average the burn over. Defaults to 3 — the same trailing window the app's KPI tile uses. Raise it to smooth a lumpy month, lower it to react faster. | |
| workspace_id | No | Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| as_of | No | ||
| error | No | ||
| hints | No | ||
| trend | No | Whether the change is GOOD for this KPI, not the direction the number moved. Burn is lower-is-better, so "up" means burn FELL and "down" means it ROSE. Read the sign of `change` for direction. | |
| amount | Yes | ||
| change | No | Signed percentage change of `amount` against `baseline.value` (e.g. -20.7 for a 20.7% fall). Measured over `baseline.period`, never over the months in `per_month` — the baseline is a different window, so a delta computed from the series is a different number. | |
| partial | No | ||
| success | Yes | ||
| baseline | No | What `change` was measured against. It arrives with `change`, `trend` and `trend_polarity` as one group; when the baseline has no named period all four are withheld rather than sending a percentage with no referent. | |
| currency | No | ||
| excluded | No | ||
| per_month | No | ||
| unavailable | No | ||
| connectors_url | No | ||
| trend_polarity | No | Which direction counts as good. Burn is lower-is-better, which is why a fall reads as `trend: "up"`. | |
| trailing_months | No | ||
| months_in_window | No | ||
| months_with_data | No | ||
| resolved_workspace | No | The workspace that answered, when the caller named none and the token authorizes several. |