Render a caller-computed burn
well_render_burnPut a burn figure YOU computed onto the burn card.
This tool measures nothing. It takes the figure and its method as input and returns them for rendering. Call it only after you have computed the burn yourself and can state every field below from your own work — never to "get" a burn.
The server derives no burn of its own. The figure on the card is the one you state here, which is why every field below is required: the policy behind a number is the only thing that makes it checkable.
At its smallest size the card draws the figure alone. It carries the figure, the window it averages and the trend chip. At its wider sizes it also draws the months as bars, from per_month for the window and history_per_month for the months before it, against one line at amount (see history_per_month below). The fields below other than amount, currency and window are not drawn. Every field you send comes back to you in this tool's text result, which is what you write the prose from. The card is the measure; the explanation is yours.
REQUIRED, because a figure whose method is not stated cannot be checked:
amount— the outflow per month, as a POSITIVE magnitude incurrencywindow— the months the average divides by, not the months that carried spendconvention— "signed", and the counts you elected it frommonths_in_windowandmonths_with_data— a window with dark months reports LOWER than its typical month. When the two differ you MUST say so in prose: how many months recorded an outflow, and that the average still divides by the whole windowexcluded— what fell out, in named groups.internal_transfersis the sum'sexcluded_multi_leg; sendnullwhen the sum could not count ittransaction_countandunplaceable_count— how much of the window could be placed inside or outside the transfer rule at all.unplaceable_countis the sum'sexcluded_no_owned_leg. Sendnullwhen the sum could not count it. Never send 0 for that, because zero says every row was placed
REFUSED rather than rendered:
a negative
amount— a burn is a magnitude; a negative one means a signed subtotal was used without taking its magnitudeconvention: "magnitude"— that feed keeps direction in a field no grouping here reaches, so no outflow was measuredmonths_with_dataabovemonths_in_window, or a measuredunplaceable_countabovetransaction_countone of
unplaceable_countandexcluded.internal_transfersnullwithout the other: one cancelled count nulls botha
months_in_windowthat disagrees with the monthswindowspans — the two state one fact, and a reader cannot tell which is the liesignedelected from ZERO negative rows: whatever the convention was called, that window measured no outflowconvention_countssumming pasttransaction_count, ormonths_with_datadisagreeing with the monthsper_monthshows carrying an outflow — your own prose states both, so a contradiction between them is a sentence that refutes itselfa
windowwhose bounds are not each the first of a month, or that fits inside one month: a month average divides by whole monthsa
per_monthseries that is not the window's own months, in order, averaging toamount— a dark month belongs in it as a zero, and a series that disagrees with the figure is not the working behind ita
currencyoutside ISO-4217 — the code is checked against the catalog, not its shape
OPTIONAL, and only as a pair:
baselineandchange— the earlier window you compared against, its own average, and the signed percentage between them. Send both or neither: a percentage whose baseline the reader cannot name is exactly the unchecked number this tool refuses everywhere else. The card draws the CHIP alone and never the baseline, so sending the pair obliges you to NAME that comparison in prose: the baseline window and its own average. Compute the baseline the same way you computed the figure, over a window of the same length; the two may overlap, and when they do say so too.changeis checked againstamountandbaseline.valueand refused when it does not follow from them, so send the percentage you actually divided. Do not send a direction: down is GOOD for a burn, and the card's green is decided server-side fromchangerather than read off its sign.
OPTIONAL, for the card's wider sizes:
history_per_month— the months immediately BEFOREwindow, up to 9, oldest first, each{ month, amount, has_data }. Measure them with the same sum, the same convention, the same exemptions and the same conversion asper_month. A month with no outflow ishas_data: falsewith amount 0. The server derivesforms.m(the window and the months just before it, up to 4 months in all) andforms.l(the window and every month sent, up to 12): the months each size draws. Every size draws its bars against one line atamount, the window's figure, so the card states no second average and neither does your prose: do not average the drawn months yourself. Withouthistory_per_month, both sizes draw the window alone.REFUSED: more than 9 months, a month inside or after
window, a month named twice, months out of order, a gap between two months, or a last month that is not the month just beforewindow.from.
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 |
|---|---|---|---|
| amount | Yes | Average monthly outflow as a POSITIVE magnitude. A negative value is refused. | |
| change | No | Signed percentage against `baseline.value`, drawn as the card's trend chip. Send it only alongside `baseline`, whose window and average your prose must name, and never derive the card's up/down sense from its sign — for a burn, down is good. | |
| window | Yes | Inclusive start and EXCLUSIVE end of the averaged window, YYYY-MM-DD. | |
| baseline | No | The earlier window this figure is compared against, and its own average. Required for `change` to render, and never rendered itself: name it in prose, because a percentage whose baseline the reader cannot find anywhere is a number they cannot check. | |
| currency | Yes | ISO-4217 code the amount is denominated in. Checked against the catalog, not its shape. | |
| excluded | Yes | The three exclusion groups kept apart: structural, reader-chosen, and defective. | |
| per_month | No | The series behind the average. A month with no outflow belongs in it as a zero. | |
| convention | Yes | Which sign the feed uses for an outflow. "magnitude" is refused: it measures no outflow. | |
| 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. | |
| 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. | |
| months_in_window | Yes | The divisor — every month in the window. | |
| months_with_data | Yes | How many of those months carried any outflow. | |
| convention_counts | Yes | The row counts the convention was elected from, so a reader can check the election. | |
| history_per_month | No | The months immediately before `window`, oldest first, measured the same way as `per_month`. Feeds only the card's wider sizes, which draw these months against `amount`. `amount` stays the window's figure. | |
| transaction_count | Yes | Rows in the window. | |
| unplaceable_count | Yes | Rows with no leg on an owned account, neither inside nor outside the transfer rule: the sum's `excluded_no_owned_leg`. `null` when the sum could not count them, never 0. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| forms | Yes | ||
| trend | No | ||
| amount | Yes | ||
| change | No | ||
| window | Yes | ||
| success | Yes | ||
| baseline | No | ||
| currency | Yes | ||
| excluded | Yes | ||
| per_month | No | ||
| cash_check | No | ||
| convention | Yes | ||
| computed_by | Yes | ||
| 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 | ||
| months_in_window | Yes | ||
| months_with_data | Yes | ||
| convention_counts | Yes | ||
| history_per_month | No | ||
| transaction_count | Yes | ||
| unplaceable_count | Yes | ||
| 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. |