well_measure_category_trend

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

Measure ONE spending category for one month against its usual month: the month total, the usual amount, and the difference. It draws no card. Call it when the person asks how much they spent on one category in a month, or how a month compares to usual ("how much did I spend on groceries this month compared to usual?"). For several categories at once, or for a total by category, use `well_sum_transactions` instead. **"Usual" is the mean of the 3 full months before the month.** A month with no row of the category counts 0. Read `baseline_complete` before you call the figure usual: when it is false, some of those months had no transaction in scope at all, so say which months had data (`baseline_activity`) and do not call the mean usual. The month defaults to the running month in UTC. The running month is partial: `month_complete` is false, so say the month is not over. A month after the running month is refused. Figures are per currency, with no conversion: one entry in `currencies` per currency, at most 10. Never add two currencies together. An empty `currencies` means the category has no row in the whole window. A month amount is the net of the category's money in and money out, as a magnitude: spend minus refunds on a feed that keeps one sign convention. When a large share of the category's rows over the window is negative and a large share is positive, the workspace pools a feed that signs its outflows with one that stores magnitudes, and no single spend figure exists: the call refuses with `refusal_reason: "mixed_sign_conventions"` and the two row counts, and measures nothing. `uncategorized_in_month.count` is the rows of the month with no category at all; a row filed under a category the person typed is not counted. Some of them can belong to this category, so the month total is a floor when the count is not 0: say so. `excluded_malformed` counts the rows with an amount that could not be read. **The category list depends on the workspace.** A personal space files household categories, a company workspace business categories, and both file the shared ones. A category outside the workspace's list returns `refusal_reason` and `allowed_categories`, and nothing is measured. A personal space shows some shared keys under its own name: TRAVEL_TRANSPORT ("Transport & travel"), MEALS_ENTERTAINMENT ("Restaurants & bars"), BANK_FX_PAYMENT_PROCESSING_FEES ("Bank fees"), TREASURY_PLACEMENT_OUT ("Savings & investments (out)"), TREASURY_REDEMPTION_IN ("Savings & investments (in)"), INVESTMENT_INTEREST_INCOME ("Interest"), LOAN_DRAWDOWNS_REPAYMENTS ("Loans & credit"), INTER_ACCOUNT_TRANSFER_SAME_ENTITY ("Transfers between my accounts"), FX_CONVERSION_PRINCIPAL ("Currency exchange"), UNCATEGORISED_SUSPENSE ("Uncategorised"). Name a category with `category.label` or `category.names` from the result, never with the key. `scope` defaults to `own`: the workspace's own transactions. `own_and_adopted` adds the rows a parent workspace shared with it. 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.