Render a caller-computed cash forecast
well_render_cash_forecastPut a cash forecast YOU computed onto the forecast card.
The default mode measures nothing. It takes the settled month-end series, the anchor, the burn and the projection you computed, and returns them for rendering. Call it only after you have computed both halves yourself: the month-end totals under your cash scope, and the burn under your stated policy. Never call it to "get" a forecast.
Without recurring_inflow the projection is WORST CASE: no revenue arrives, and cash declines by the burn each month until it reaches zero, where it stops. Take the anchor and the burn each to the cent, then each point is max(0, anchor − k × burn) for the k-th month after the anchor.
With recurring_inflow, the projection counts the recurring inflow well_measure_recurring_inflows measured, and nothing else: each point is max(0, anchor − k × (burn − inflow)), each figure to the cent. An inflow larger than the burn makes the series grow. Pass the forecast_inflows entry of the cash's currency as it is; never add a one-off payment, an unpaid invoice or a deal to it. The tool re-derives the series from the amount you state and cannot check where that amount came from. The amount is a floor that holds month by month: only monthly payers that may not have stopped and paid in every month are in it, and quarterly, yearly, month-skipping, ended and no-cadence payers are not.
The tool re-derives every point from the figures you state here, in cents.
Set include_deals: true when the person explicitly asks to include or add deals, or answers 1 to an offer already sent. An explicit request is approval: compute the floor from the supplied reads and render the deal-adjusted series once. When no inclusion was requested, omit include_deals; this returns the supplied baseline without a deal read. An ordinary forecast may use a separate well_list_projects offer metadata read before any monetary deal read. This mode reads at most 100 live deals from the workspace. It counts each won deal at its full amount in its closed_at month, and each open deal (active or paused) at its chance, its own or else its live stage's, in its end_date month, when that month is inside the projection window, converting with Well's stored FX rate as of this call. Draft, lost, archived, undated, past-due, out-of-window, incomplete and unconvertible deals return named exclusions; an excluded deal with a malformed source amount includes its original display string. An open deal with no chance returns the exclusion no stage weight. More than 100 live deals refuses the whole deal variant. The returned entries draw the deal-adjusted series; floor_entries preserve the series you passed.
The card draws the series, the anchor clause and the caveat: the worst-case one, or the recurring-inflow one when recurring_inflow is sent. The cash scope, the burn policy and partial are REQUIRED and reach no pixel. All of it comes back in this tool's text result, which is what you write the prose from.
REQUIRED:
currency, andas_of: the full ISO time of the balances read the series came fromactuals: one{ month, amount }per month, oldest first, ending on the last month that has ended atas_of(UTC). A month no account covered isnull, never 0, and it stays in the list.anchor:{ month, amount, basis }.closed_month_endis the latest settled month-end inactuals.current_positionis today's cash when no month has a settled total. It sits on the grid at the last actual month.burn: the POSITIVE monthly magnitude, its currency,trailing_months, and thewindowit averaged (frominclusive andtoexclusive, eachYYYY-MM-01). The window ends with the last actual month.months_forward(at most 12), andprojection: one{ month, amount }per projected month. When the anchor sits before the last actual month, the months between are projected too, somonths_forwardmust reach past them.cash_scope: the counted account types, whether unknown ownership was counted,anchor_missing_accounts(counted accounts with no reading at a closed-month anchor; 0 undercurrent_position), and the four exclusion groupsburn_policy: the elected convention andconvention_counts: { negative: <the sum's count_negative>, positive: <the sum's count_positive> }, the exclusions (internal_transfersis the sum'sexcluded_multi_leg,unreadable_rowsits malformed rows), andunplaceable_count(the sum'sexcluded_no_owned_leg)partial: the forecast's own floor, which is WIDER than a cash total'sis_floor. It is checked againstcash_scopeand must betrueexactly when an account was left out with no readable balance, no rate, OR no reading at the anchor month — that last one is the forecast's alone, and a caller that forwards its cash total'sis_floorunchanged is refused on it. It never means a cut-short read: a cut-short balances read or sum stops the run before this call.
OPTIONAL:
recurring_inflow:{ amount, currency, measured_through }, theforecast_inflowsentry ofwell_measure_recurring_inflowsin the cash's currency, as it is. Leave it out when that measure returned no entry in the cash's currency.
REFUSED rather than rendered, each because your own figures disagree:
a projection point that is not
max(0, anchor − k × burn)within a cent, ormax(0, anchor − k × (burn − inflow))whenrecurring_inflowis senta
recurring_inflowin another currency than the cash, or measured through a month other than the last actual montha
recurring_inflowabove the burn on an anchor at or below zero: the balance is recovering, which a series clamped at zero cannot draw. Report the overdraft and the inflow insteada projection that does not start the month after the anchor, skips a month, continues after a zero, or has the wrong length
a projection ending on a month that has already ended. The refusal names which of the three causes fired: the cash ran out (report that), the horizon was too narrow for the gap (widen it), or the gap exceeds every legal horizon (the feed is too far behind to project across)
a cash currency that differs from the burn's
a negative burn, a burn elected "magnitude",
signedelected from no negative rows, or one ofunplaceable_countandinternal_transfersnull without the othera
closed_month_endanchor that is not the latest settled actual, or whose amount differs from ita
current_positionanchor beside a settled actual, off the last actual month, or with an account missing at itactual months out of order, repeated, skipped, or ending on any month but the last one that has ended at
as_ofa burn window that disagrees with
trailing_months, or ends on a different month than the actualsa
partialthat disagrees with the floor your owncash_scopeimpliesan
as_ofin the future
The result carries settled_change: the first settled reading, the anchor and the direction between them (up, down or flat), computed from the exact cents. Say how the settled cash moved from its direction alone. It is null when there is no movement to state.
This tool renders its own chart card. Do not re-plot the series with a charting tool.
OPTIONAL, and send it whenever you computed a cash-flow bridge over the same cash:
cash_bridge—{ unexplained, closing }, the two terms you sentwell_render_cash_flow_bridge, in this card's currency. The server applies the bridge's own tolerance and returnscash_check."provisional": the bridge does not reconcile, the gap is inunexplained_gap, and the card marks the figure Provisional; say so in prose too: the figure stands on cash with an unexplained gap of that amount."reconciled": say nothing about it. Leavecash_bridgeoff when you computed no bridge: the result iscash_check: "not_checked"and the card marks the figure Not checked.
When the token authorizes one workspace, call this directly — no workspace 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 |
|---|---|---|---|
| burn | Yes | ||
| as_of | Yes | ||
| anchor | Yes | ||
| actuals | Yes | ||
| partial | Yes | ||
| currency | Yes | ||
| cash_scope | Yes | ||
| projection | Yes | ||
| burn_policy | Yes | ||
| cash_bridge | No | The cash-flow bridge over the same cash, when you computed one. The server decides whether it reconciles and returns the figure's `cash_check`. Leave it off when you computed no bridge: the figure is then `not_checked`. | |
| 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. | |
| include_deals | No | ||
| months_forward | Yes | ||
| conversation_id | No | The conversation id returned by the previous Well result, in its meta under well/conversation_id, in its structuredContent, or in its JSON text block. Pass it back on every call in the same conversation, including a call a card makes, so the chosen workspace and the earlier answers still apply. It decides the conversation on its own: nothing the host states about the session replaces it. Omit it only on the first call of a conversation. | |
| workspace_scope | No | Restrict this call to the family: the token's primary workspace plus the company workspaces under it that you are a member of. Unrelated authorized workspaces drop out of the read; row reads merge across the family, while a per-workspace figure still reports exactly one workspace. | |
| recurring_inflow | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| burn | Yes | ||
| as_of | Yes | ||
| anchor | Yes | ||
| entries | Yes | ||
| partial | Yes | ||
| success | Yes | ||
| currency | Yes | ||
| cash_check | No | ||
| cash_scope | Yes | ||
| burn_policy | Yes | ||
| computed_by | Yes | ||
| deal_summary | No | ||
| floor_entries | No | ||
| months_forward | Yes | ||
| settled_change | No | ||
| conversation_id | No | The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation. | |
| newly_connected | No | Tools that connected to this workspace since the last result and that no session was told about yet, oldest first. Present only when at least one tool is new. The connected-line rule says when to tell an entry; when it does, one line per entry, in the person's language: "<name> is connected.". Never fold several entries into one sentence. Each entry comes back once, on one result only: never repeat its line later. | |
| unexplained_gap | No | ||
| recurring_inflow | No | ||
| resolved_workspace | No | The workspace that answered, when the caller named none and the token authorizes several. | |
| conversation_id_note | No | Present only when the server opened a fresh lane, stating that no choice recorded earlier was read. | |
| conversation_id_source | No | Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened. |