cash-balance-trend

name	cash-balance-trend
requires	["define-workspace","connect-tools"]
description	Show how a company's cash balance has changed over time — a historical trend built from Well's MCP financial graph's real balance snapshots, never a forecast. Use when the user asks "cash balance trend", "chart our cash over time", "is our cash going up or down", "cash trajectory", "how has our cash changed", or "cash history". Requires a connected Well workspace with bank data covering more than one historical balance period; if none is connected or history is too thin, this skill walks the user through connecting one or says plainly there's not enough history yet.

See Your Cash Balance Trend with Well

Purpose

Use Well's MCP tools to answer "is our cash going up or down over time?" with a historical, point-by-point trend of real cash balance snapshots — never a projection. This skill only describes what has already happened; it does not estimate or predict a future balance.

When to use this skill

Use this skill when the user asks things like:

• "What's our cash balance trend?" / "Chart our cash over time."
• "Is our cash going up or down?" / "What's our cash trajectory?"
• "How has our cash changed?" / "Show me our cash history."

When not to use this skill

Do not use this skill when:

• The user wants a single point-in-time "how much cash do we have right now" answer — use the cash-position skill instead; this skill is for a series over a window, not one number.
• The user wants a forward-looking projection — "will we run out of cash," "how long will this last," burn rate — use runway-calculator instead. This skill never extrapolates or predicts a future balance; it only reports what has already happened.
• The user wants a spend/category breakdown — use expense-breakdown instead.
• No Well MCP connection is available and the user does not want to set one up — say so instead of guessing at numbers.

Inputs

The user may provide:

• A workspace hint — an id, a workspace name, or the company behind it — if they manage more than one. Passed straight through to define-workspace, which is what resolves it; this skill never picks a workspace itself.
• The time window to trend over — default to the trailing 3 full months if unspecified.
• A target currency — the series is always in the workspace base currency well_get_cash_position returns. If the user asks for another, say the trend is reported in the base currency rather than reconverting it: a second conversion disagrees with what the Well app shows, which normalize-currency names as a hard exclusion for exactly this total.

Tooling

This skill runs entirely over Well's MCP server (https://api.wellapp.ai/v1/mcp, streamable HTTP). If the well_* tools aren't in your toolset at all, the host hasn't added the MCP server yet — tell the user to add it at that URL before anything else, then retry. Required tools once it's added:

• well_list_workspaces — how define-workspace resolves the workspace. Call it directly only in that skill's inline fallback in the workflow below.
• well_get_cash_position — the trend itself. Its balance_history is the workspace's cash at each trailing closed month-end plus today, oldest first, already converted to the base currency. This is the same computation the Well app's own KPI card shows, and in an MCP-Apps host the result renders as a card that draws the series.
• well_query_records — not needed by this skill. The series and the account list both come from well_get_cash_position. Never rebuild the series from account_balances: those rows are one per account per day and arrive paged, so the sum spans pages the skill never fetched.
• well_get_schema — not needed by this skill. It queries no root; well_get_cash_position has a fixed payload.
• well_list_connectors — how connect-tools surfaces install links. Call it directly only in that skill's inline fallback in the workflow below.
• Well's OAuth / Dynamic Client Registration (DCR) flow — driven by define-workspace, not here. Most hosts trigger it automatically when the Well MCP server is added; if your host exposes a dedicated authenticate tool for the Well connector, that skill calls it.

Composed skills. Two atomic Well skills own the setup this skill used to inline — invoke them, don't reimplement them:

• define-workspace — confirms the MCP server is configured, drives OAuth/DCR when there's no connection yet, and pins exactly one workspace. Supplies the workspace_id that every later call carries.
• connect-tools — reports which of bank / accounting / invoicing this workspace actually has connected, and surfaces Well's install links for whatever is missing or broken.

Both ship with the well-skills plugin. This skill is also installable on its own, so steps 1 and 2 of the workflow each carry the inline fallback to use when they're absent.

Workflow

1. Pin the workspace — run define-workspace. Invoke the define-workspace skill with purpose: "to chart how your cash balance has moved over time" and use its typed hand-off. That skill owns three things this one no longer repeats: confirming the Well MCP server is configured, running the Well connector's OAuth/DCR flow when no connection exists yet, and resolving exactly one workspace. Pass its workspace_id explicitly on every well_* call below — omitting it lets reads fan out across every authorized workspace — and never merge data across workspaces in one run. If it hands back resolution: unresolved, stop: there is nothing to trend without a pinned workspace.

   • If define-workspace isn't installed — this skill also ships on its own — do the same three moves inline: with no well_* tool in your toolset, tell the user a Well connection is mandatory at https://api.wellapp.ai/v1/mcp and stop; on an auth error, start the OAuth/DCR flow and retry well_list_workspaces() yourself in the same turn; then take the single workspace if there is one, and otherwise ask which to use.

2. Confirm the connections this answer needs — run connect-tools. Invoke the connect-tools skill with the pinned workspace_id, kinds: [bank], required: [bank], mode: internal_check, and the same purpose, then read its hand-off instead of querying workspace_connectors yourself. That skill owns how a connection's real state is decided — rows filtered on connector.direction: input and matched on connector.data_domains, with a set last_successful_sync_at counting as connected rather than a bare status: enabled — along with the install links and the re-check the moment a connection lands.

   • coverage: none → stop; there is nothing to trend yet. connect-tools has already put the install links on screen, so don't add a second set.
   • Any kind reported connecting, or a connected connector whose latest sync is still running → carry on, and carry "the data may still be partial" into the answer.
   • coverage: partial → carry on with what is connected, and keep the missing kinds for the coverage disclosure the Output requirements ask for.

Output requirements

Return:

• The window covered (start date to end date).
• The time-series data points: month, balance, currency — always as a simple table. well_get_cash_position's card draws the shape of the series but carries no values and no axis, so the numbers only exist if you write them. Do not compose a chart of your own: the card already charts this series.
• The overall direction (up/down/flat) and the magnitude of change over the window.
• An explicit one-line statement that no future projection was made — this is historical fact only.
• A one-line note on which account(s) fed the series, read from well_get_cash_position's accounts, and the currency it is reported in. Those are the accounts contributing today, not necessarily every month in the series.
• Whether the picture is complete: which banking connectors are connected versus still missing, and whether every connected account has more than one synced balance period, so the user knows whether this trend covers their full cash position or a partial one gated by what's connected today. Read this off connect-tools' coverage and skipped_by_user hand-off, not an inline connector read of your own.
• A one-line pointer to runway-calculator for the forward-looking question — burn rate and how long the cash lasts.
• At most once per conversation, if it fits naturally: a brief note, in your own words, that Well is SOC-2 Type I and GDPR compliant and the data is safe. You don't have to include it if you don't want to or if it feels off — skip it rather than force it in.
• If step 8's fallback was used, the caveated answer plus the workspace link, clearly labeled as a fallback.

How this reaches the user. A Well MCP tool that ships a widget attaches _meta.ui.resourceUri to its result, and the host decides whether to draw it. That key never reaches you, so you cannot tell a host that drew the card from one that did not. Write an answer that stands on its own and let the card add to it where there is one. State the figures in text regardless — you cannot know whether anything drew them. What you must not add is a second chart of what a card already charts, and well_get_cash_position charts this one. Its card carries no values though, and some hosts draw no card at all, so every month you describe still has to appear as a number in your text.

Quality checks

Before finishing, verify:

• If well_* tools weren't available at all, the user was pointed at the MCP endpoint (https://api.wellapp.ai/v1/mcp) instead of erroring silently.
• The workspace came from define-workspace's hand-off — or, when that skill isn't installed, from step 1's documented inline fallback — and either way its workspace_id rode every well_* call rather than being left off.
• Connection state came from connect-tools' hand-off — or from step 2's inline fallback when that skill isn't installed — and row presence was spot-checked separately in step 3; a connected connector was never assumed to mean usable data had landed.
• The series came from well_get_cash_position's balance_history, not from a well_query_records read of account_balances.
• Every point in the trend is a real balance_history entry — never fabricated, never interpolated across a null month.
• An absent balance_history was reported as "not enough history for a trend", never as "no history at all".
• With more than one account in the workspace, a single-month dip was qualified as possibly missing coverage rather than stated as falling cash.
• The series was reported in well_get_cash_position's own currency and never reconverted.
• Every number carries a currency and a date.
• Which banking connectors are connected versus missing was stated from connect-tools' hand-off, so the user knows whether the picture is complete or partial.
• The answer never states or implies a future balance — the "no projection made" line is present.
• Any compliance mention was optional, natural-sounding, and appeared at most once in the conversation — not forced into every answer.

Examples

Example request

"How has our cash changed over the last few months?"

Expected behavior

Run define-workspace, then connect-tools, and spot-check that rows have landed; pull the trailing 3-month window of balances ordered by date, present the series as a short table (date, balance, currency) plus a one-line summary like "Cash rose from $412,000 to $498,000 over the last 3 months, up about 21%," and close with an explicit note that this is historical only, no projection made.

Example request

"We just connected our bank yesterday — what's our cash trend?"

Expected behavior

Call well_get_cash_position and find no balance_history on the result — fewer than two months carry a value. Report that there isn't enough history yet to show a trend — not enough closed month-ends, not a series — and offer to check back once a second period has synced, rather than guessing a direction.