well_list_recurring_contexts

io.github.WellApp-ai/well-mcp · Verify this server

List the billing contexts a reader can count as recurring revenue over one window, each with what counting it would add. This is what the recurring-contexts card offers; it measures nothing `well_sum_invoices` did not already measure. Each entry in `groups` is one billing context's revenue in the window: `context_key` (the id a selection is matched on), `label` (the context as the product writes it), `amounts` (one entry per currency, each already net of credit notes and never converted) and `count` (the invoices behind it). The named contexts are sorted biggest first in the currency that carries the most invoices, so the biggest decision reads first. A context whose window nets to nothing in every currency is NOT listed — counting it would add nothing, so it is not a choice. A context that nets NEGATIVE stays on the list: its credit notes outweighed its invoices, which is a real state, and hiding it would move the figure by an amount nobody saw. **The last entry may be `context_key: "unclassified"`, labelled "No billing context".** It is the invoices whose `billing_context` is `null`: extraction fills the field rather than a billing system, so on most workspaces it holds most of the revenue. It is a choice like the others. A business that bills only subscriptions can count it as recurring; a business with one-off work usually cannot. When the reader counts it, apply it to the `well_sum_invoices` rows whose `billing_context` is `null` — no row carries the key itself. **State its amount whenever it is listed**, counted or not, because it is the part of the figure extraction could not describe. `totals` is the sum of the groups' amounts per currency: the window's whole readable issued revenue. **This read converts nothing and never adds one currency to another.** The reader decides per context, so the choice needs no single total; convert once, in the arithmetic, at a rate you state. This read takes no view on which contexts ARE recurring, and offers no default, the "No billing context" entry included. What counts as recurring revenue is a fact about the reader's business, not about the vocabulary: a retainer is recurring for one company and a one-off engagement for another. Take the reader's answer from the card: its Continue records it with `well_switch_workspace` as `recurring_contexts`, and you read it back with `well_wait_for_selection` (kind "recurring_contexts"). Keep only the `well_sum_invoices` rows whose `billing_context` is in that answer, reading `unclassified` as the rows whose `billing_context` is `null`, and pass the same keys to `well_render_mrr` as `recurring_contexts` so the figure names what it counted. The window is whole months: `from` and `to` are both the first day of a month, YYYY-MM-01, `from` inclusive and `to` EXCLUSIVE. `window` echoes both back exactly as you sent them. When a comparison will be measured, read the list over BOTH windows, from the start of the earlier one to the end of this one, so a context that stopped billing between them is still offered. `partial: true` means the aggregate was cut short: every amount here is a FLOOR, a context's real share can only be larger, and a choice made because a share looked small may not survive the full read. Say so before presenting the list as a basis for the decision. `unreadable_rows` counts invoices whose net amount or currency could not be read at all; they are in no figure here. It is `null` when that count could not be read, which is not zero: say it is unmeasured. Read `success` before `groups`: a failed read returns no contexts, which looks exactly like a window with nothing to choose. 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.