Get cash flow bridge
well_get_cash_flow_bridgeGet the workspace's cash-flow bridge — how the opening cash position became the closing one — the exact same steps the Well app's cash-flow waterfall chart shows. Use this instead of deriving flows from raw transaction reads.
Returns steps in render order, each { label, value, kind }. kind says how to read value:
"start" and "total" carry an ABSOLUTE cash position (the opening and closing anchors).
"increase" and "decrease" carry a gross flow MAGNITUDE, always positive. The direction lives in
kind, not in the sign — never report a "decrease" as a negative number or add the magnitudes as though they were signed."unexplained" carries a SIGNED adjustment and is the one kind whose sign you must keep. It appears only when the four measured bars do not reconcile: it is the gap between them and the measured closing position, NOT cash that moved. Report it as an unexplained difference and say the bridge does not fully reconcile. Never fold it into the inflow or outflow figure, and never present it as spending, income, or a transfer.
Walk the steps to reach the total: opening, plus every "increase", minus every "decrease", plus any "unexplained". When an "unexplained" step is present that sum equals the "total" exactly. When none is present the bridge reconciled to within a small tolerance — say it reconciles, not that it is exact to the cent. A bridge can also omit the step because an anchor could not be measured at all; the hints say so when that happens, so read them before claiming either.
This is a SELF-CONTAINED reconciliation: the "start" and "total" steps ARE the opening and closing balances for the period, so do not also call well_get_cash_position to fetch them. That tool answers a different question — the balance right now — and pairing it with this one reports today's figure beside last period's bridge as though they were the same reading.
An EMPTY steps array means neither anchor could be measured (nothing connected, or the reads timed out). That is missing data, NOT a month with no movement — say the bridge is unavailable rather than reporting flat cash.
period_start and period_end are the inclusive YYYY-MM-DD bounds these bars cover — a trailing multi-month window, not a single month. Read the period from those fields and state it whenever you present the numbers. Never derive it from today's date, and never assume one month. If both fields are absent, say the period is unknown rather than naming one.
Pass year + month to bridge a past period instead of the live window. Read the window you actually got from period_start/period_end either way.
This is not a decomposition of well_get_cost_structure: this reconciles opening to closing cash across inflow and outflow, while cost structure splits a single month's outflow by category. They will not tie out, and presenting one as the breakdown of the other is wrong.
If hints are present (excluded accounts, an FX gap, or an unexplained residual between the anchors and the flows), disclose them rather than presenting the bridge as balanced.
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. | |
| 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 |
|---|---|---|---|
| error | No | ||
| hints | No | ||
| steps | Yes | ||
| success | Yes | ||
| currency | No | ||
| period_end | No | Inclusive YYYY-MM-DD end of that window. | |
| unavailable | No | ||
| period_start | No | Inclusive YYYY-MM-DD start of the window the flow bars cover (a trailing multi-month span). | |
| connectors_url | No | ||
| resolved_workspace | No | The workspace that answered, when the caller named none and the token authorizes several. |