List burn exemptions
well_list_burn_exemptionsList the categories a reader can exempt from burn over one window, each with the spend exempting it would remove. This is what the exemption card offers; it measures nothing the sum did not already measure.
Each entry in groups is one category's OUTFLOW in the window: category_key (the id an exemption is matched on), label (the category as the product writes it), amount (a magnitude, never signed) and count (the rows behind it). Sorted by amount descending, so the biggest decision reads first. A category with no outflow in the window is NOT listed — exempting it would remove nothing, so it is not a choice.
total is the sum of groups[].amount and nothing else. unclassified_amount and unclassified_count are the outflow this list cannot offer as a choice: rows carrying no category, which no exemption ever matches, and rows whose category is outside the shared vocabulary, which this read cannot name for a reader. The two are reported together because both leave the reader's choices unable to touch that money — not because the same thing is true of them downstream. total + unclassified_amount is the window's whole outflow, so a reader can see what the choices do not cover. State the unclassified figure whenever it is not zero rather than presenting total as the whole window.
Pass the convention you elected for the burn figure itself. The list and the figure have to sit on one election, and this read deliberately does not make a second one.
partial: true means the underlying sum measured nothing, so groups is empty and nothing is known about the window's spend. Say so and offer to try again, rather than presenting an empty list as a decision. unreadable_rows counts rows whose amount could not be read at all; they are in no figure here.
from is inclusive and to is EXCLUSIVE, so a window of whole months passes the first instant of the month after the last one you want. window echoes both back exactly as you sent them.
Internal transfers are already out. This read keeps only the rows with exactly one leg on an account the workspace owns — the same rule the burn applies — so a movement between the workspace's own accounts never appears here.
currency is the one currency every row in the window shares. A window holding more than one, or holding a row that carries none, is REFUSED with success: false and an error saying which: adding two currencies gives a number denominated in nothing, and no field on this result could say it happened. currency is the EMPTY STRING only when the window held no row at all, and then groups is empty and both totals are zero.
The direction convention is elected ONCE over the whole window, never per category. A window whose rows are overwhelmingly negative stores an outflow as a negative amount, and these figures are that branch. A window that stores outflows as positive magnitudes keeps the direction in a field this grouping does not read, and a window that pools both kinds of feed has no single outflow at all — both are REFUSED with an error naming the counts behind the decision, rather than reported as spend.
Take the reader's answer from the card, record it with well_switch_workspace as exempt_categories, and read it back with well_wait_for_selection (kind "exemptions"). The record belongs to this conversation. Another conversation does not read it. Then pass the same keys to well_sum_transactions as exempt_categories to compute the burn without them, and name the exemptions beside the figure so it can be read back.
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 |
|---|---|---|---|
| to | Yes | EXCLUSIVE end of the window, ISO-8601 — the first instant after the last month you want. | |
| from | Yes | Inclusive start of the window, ISO-8601 (e.g. 2026-06-01). | |
| convention | Yes | Which sign means money leaving, as YOU elected it for the figure these exemptions apply to — the same election `well_render_burn` takes. This read does not elect its own: a share of positive rows cannot tell a business with revenue apart from two feeds pooled together, and guessing would either refuse ordinary workspaces or total two conventions as one. Pass "signed" when the window's rows are mostly negative for spend, "magnitude" when the feed stores outflows as positive numbers. A "magnitude" window is refused, because direction then lives in a field this read does not group on. | |
| 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. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | ||
| total | Yes | The sum of groups[].amount, and nothing else. | |
| groups | Yes | ||
| window | Yes | ||
| partial | Yes | True when the sum behind this card measured nothing. `groups` is then empty, so there is no list to choose from: say so and offer to try again. | |
| success | Yes | ||
| currency | Yes | The one currency every row shares; empty only when the window held no row. | |
| next_step | No | What to do with the card this result renders. Added by the dispatcher when the card asks for a click. | |
| 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. | |
| unreadable_rows | Yes | Rows in the window whose amount could not be read. They are in no figure here, including the unclassified one. | |
| resolved_workspace | No | The workspace that answered, when the caller named none and the token authorizes several. | |
| unclassified_count | Yes | ||
| unclassified_amount | Yes | Outflow this list cannot offer as a choice: rows with no category, which no exemption ever matches, and rows whose category is outside the shared vocabulary, which cannot be named here. | |
| 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. |