well_sum_transactions

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

Sum a workspace's transactions over a date window, grouped how you ask. Arithmetic only — this tool holds no definition of burn, spend, or runway, and returns no figure the app renders. Use it when you are computing a figure whose RULES you are stating yourself: a burn over a window you chose, a total that excludes categories the user named, a per-month series behind a trend you are about to describe. The server derives no burn of its own, so a burn figure starts here: state the rules, sum exactly those rows, then put the result on a card with `well_render_burn`. `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. Both are required: a window you cannot state is a decision you have not made, and this tool will not pick one for you. `axes` groups the result — any of `month`, `currency`, `category`, comma-separated — and names what to group in ADDITION to currency. Every axis appears on every row: the ones you did not group by come back `null`, so the row shape never depends on what you asked for. **Currency is always grouped, named or not, so a row never mixes two.** Adding EUR to USD gives a number denominated in nothing, and no field on the result would tell you it happened. Omitting `axes` therefore returns one row PER CURRENCY over the window, not one row. Convert the per-currency subtotals yourself, at a rate you can state, before you add them — and if there is more than one row and you report a single total without converting, the total is wrong. **Each row carries BOTH sign branches, and choosing between them is your job.** `sum_negative` is the magnitude of the rows whose amount is negative; `sum_positive` is the magnitude of the rows whose amount is positive; `count_negative` and `count_positive` say how many rows are behind each. Which one is money leaving depends on the FEED, not on the query: most connectors store outflows as negatives, some store them as positive magnitudes. Read the counts to decide, and decide ONCE over the whole window rather than per row or per group: a single category or month can be all-positive on a signed feed, so electing per group flips the convention mid-answer and totals two different things together. A window whose rows are overwhelmingly negative is a signed feed, and outflow is `sum_negative`. Almost no negatives means the feed stores magnitudes and keeps direction in a field this tool does not group on — so it cannot separate outflow from inflow, and `sum_negative + sum_positive` is gross movement, not spend. Say so rather than reporting it as an outflow. **A substantial share of BOTH is a third answer, not a close call between the first two.** A workspace connected to a signed feed and a magnitude feed at once pools them here, and no combination of the two subtotals is its outflow: `sum_negative` misses the magnitude feed's spend entirely, and adding `sum_positive` pulls in the signed feed's income. There is no grouping that separates them, because the axes carry no connector. Report that the window mixes conventions and that a single outflow cannot be derived from it, rather than electing whichever branch is nearer. State which convention you elected and what the counts were, so the reader can check it. `exclude_internal_transfers: true` keeps only the rows with EXACTLY ONE leg on an account the workspace owns. Two legs is a movement between your own accounts and drops, which is the rule's purpose. **Zero legs also drops**, and that is the part worth knowing: a card purchase sits against a liability account, so on a card-heavy workspace this removes card spend along with the transfers. `excluded_zero_leg` and `excluded_multi_leg` count the two populations separately, so read them before describing what the figure covers. Read `excluded_zero_leg` as "this many rows carried no asset movement" and nothing narrower: a card charge lands there, and so does a row whose payer and payee resolved to no account at all, and the count cannot tell them apart. A large one is a reason to look, never a spend total to quote. Either count comes back as `null` when it could not be measured, which is NOT `0`: zero says the rule removed nothing, null says nobody counted. On a null, say the exclusion is unmeasured rather than reporting none — the sums themselves are unaffected, and `partial` is what speaks for those. For reproducing the burn tile that is exactly right — it is the conservation law the cash-flow bridge rests on. For "total spend excluding transfers between our own accounts" it is not what the words promise, so say what fell out or leave the flag off. The rule is structural: it counts legs, so no label, category, or type on the row affects it, and a user recategorizing something does not change it. `exempt_categories` takes category keys that should not count. A transaction with no category at all is never matched by an exemption and always stays in the sum; if you want those excluded too, that is a different question and you must say so. `excluded_malformed` counts rows in the window whose amount could not be read as a number. They are in none of the sums, so state the count beside any total rather than presenting a figure that silently skipped them. `partial: true` means the aggregate was cut short and every figure is a floor rather than a measurement. 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.