Get cost structure
well_get_cost_structureGet the workspace's cost structure: outflow for the latest closed month, broken down by category — the exact same computation and numbers the Well app's canvas cost-structure donut chart shows. Use this instead of summing/grouping transactions yourself.
Returns entries (an array of { category, amount, pct }, sorted by amount descending) and currency (the workspace base currency). amount is a magnitude (outflow), not signed.
period_start and period_end are the inclusive YYYY-MM-DD bounds these amounts cover — always a single month. Read the period from those fields and state it whenever you present the numbers. Never derive it from today's date. Never present the figures as a quarter or a multi-month span. If both fields are absent, say the period is unknown rather than naming one.
rung names which grouping actually produced these categories — "ledger_account" (the workspace's own chart of accounts), "category_normalized" (Well's auto-categorization), "transaction_type" (a technical fallback bucket), or "uncategorised" (no rung qualified — either nothing covered the month, or a rung had the coverage but too few labelled rows). State it when you present the breakdown so the user knows whether they're looking at their own ledger's categories or Well's.
label_provenance says whether a human owns those labels, which rung cannot — "curated" (a person set or confirmed every one), "machine" (none were confirmed by a person), "mixed" (some of each), or "unlabelled" (the breakdown is not grouped on a category, so the question does not apply). When it is "machine" or "mixed", say the categories were assigned automatically and may be wrong on any individual line, rather than presenting them as the user's own categorization.
If hints are present (e.g. a coverage caveat about uncategorized spend), disclose them rather than presenting the breakdown as unconditionally complete.
Pass year + month to break down a specific past month instead of the latest closed one. Read the month you actually got from period_start/period_end either way — a requested month with no data still comes back with whatever the endpoint could cover.
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 |
|---|---|---|---|
| year | No | Calendar year of the reporting period, e.g. 2026. Must be given together with `month`. | |
| month | No | Calendar month of the reporting period, 1 = January … 12 = December. Must be given together with `year`. Omit both to read the live/current figure. | |
| 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. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rung | No | Which ladder rung produced these categories: the workspace's own ledger accounts, Well's auto-categorization, a technical fallback bucket, or none qualified. | |
| error | No | ||
| hints | No | ||
| entries | Yes | ||
| success | Yes | ||
| currency | No | ||
| period_end | No | Inclusive YYYY-MM-DD end of that window. | |
| records_url | No | Login-gated deep link to the web-app transactions table, so the user can categorize the underlying spend. Null when no workspace is in context. | |
| period_start | No | Inclusive YYYY-MM-DD start of the window the amounts cover (the latest closed month). | |
| label_provenance | No | Whether a human owns the labels: every one set or confirmed by a person (curated), none confirmed (machine), some of each (mixed), or not grouped on a category at all (unlabelled). | |
| resolved_workspace | No | The workspace that answered, when the caller named none and the token authorizes several. |