cash-balance-trend

name

cash-balance-trend

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:

• Which workspace to use, if they manage more than one.
• The time window to trend over — default to the trailing 3 full months if unspecified.
• A target currency — default to reporting per-account currency, converting only if the user asks or if a single total is required.

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 — resolve which workspace to query.
• well_query_records — read workspace_connectors, accounts, account_balances, exchange_rates.
• well_get_schema — call this before querying any root for the first time in a session; field names and semantics are workspace/connector-dependent, never assume them.
• well_list_connectors — surface install links when the workspace lacks data.
• Well's OAuth / Dynamic Client Registration (DCR) flow — if no Well MCP connection exists yet, most hosts trigger this automatically when the Well MCP server is added (it exposes standard OAuth discovery + DCR, no manual client secret needed). If your host exposes a dedicated authenticate tool for the Well connector, call that instead.

Workflow

1. Confirm the MCP server is configured. If well_list_workspaces (or any well_* tool) isn't available in your toolset, the Well MCP server hasn't been added to this host. Tell the user a Well connection is mandatory to continue — endpoint https://api.wellapp.ai/v1/mcp — because Well is where their financial data is aggregated securely to compute a real cash trend; without it there's nothing to trend. Stop until it's there; don't estimate from assumptions.

2. Confirm the account. Attempt well_list_workspaces().

   • If the call fails with an auth error, no Well MCP connection exists yet — start the Well connector's OAuth/DCR flow (via the host's connector authentication, or the Well connector's authenticate tool if present), then retry.
   • If it returns one workspace, use it. If more than one, ask the user which to use.

3. Verify the workspace has enough history. Query workspace_connectors (fields: status, connector.name, connector.slug) for any status: enabled entries, then spot-check with a well_query_records call on accounts and on account_balances for the workspace's own accounts.

   • If no banking connector is enabled, or the spot-check returns zero rows, call well_list_connectors() and present the top 2-3 install_url links (bank connectors first), and stop here — there is nothing to trend yet.
   • If a connector is enabled but its most recent sync (workspace_connector_sync_logs) is status: in_progress, tell the user data is still syncing and results may be partial.
   • If an account has only one account_balances row, there is only one snapshot, not a trend — say so plainly for that account rather than fabricating a direction from a single data point.

4. Resolve the requested time window. Default to the trailing 3 full months if the user didn't specify one; state whatever window is used.

5. Pull the accounts and their balance history. Call well_get_schema({ root: "accounts" }) and well_get_schema({ root: "account_balances" }). Query accounts for the workspace's own accounts (ownership indicating workspace-owned, not counterparty), then query account_balances for each account across the requested window, ordered by balance_at_from ascending. Pull balance_at_from, balance_at_to, accounting_balance (closing_booked, closing_value, currency), and account.account_name.

6. Build the trend series. Assemble a time-ordered series of { date, balance, currency } points per account, using balance_at_to as the point date and closing_booked (or closing_value if that's what the connector populates) as the balance. If summing across multiple accounts into one line, sum only same-currency accounts per period; report other currencies as separate series, or convert via exchange_rates and state the rate/date used — never blend currencies silently. If accounts report on different cadences or period boundaries, flag the misalignment in the answer rather than silently interpolating between mismatched dates.

7. Describe the trend, using only real rows. State the direction (up, down, or flat) and the magnitude of change from the first to the last real data point in the window. Never interpolate between snapshots and never extrapolate past the last real account_balances row — this skill reports history only.

8. If any required step errors or returns unusable data, do not guess. The fallback is: (a) state the fallback question plainly in your reply (e.g. "Is our cash going up or down?"), (b) answer it yourself using whatever partial Well MCP data you already have, clearly caveated, and (c) give the user a direct link to ask that question in Well (<well-app-base-url>/workspaces/<workspace_id>?q=is%20our%20cash%20going%20up%20or%20down) so they can get a second opinion from their own AI assistant there.

Output requirements

Return:

• The window covered (start date to end date).
• The time-series data points: date, balance, currency — described narratively and/or as a simple table, clear enough that the user or their AI host could plot it. This skill does not render an actual chart.
• 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 and any currency handling applied.
• 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.

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.
• A Well workspace was resolved unambiguously (not guessed when multiple existed).
• Data presence was checked, not just connector "enabled" status.
• well_get_schema was called before querying accounts or account_balances for the first time.
• Every point in the trend comes from a real account_balances row — never fabricated or interpolated.
• An account with only one account_balances row was flagged as "not enough history for a trend" rather than faked into a direction.
• Multi-currency results were converted (with rate/date noted) or clearly kept separate, never blended.
• Every number carries a currency and a date.
• 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

Resolve the workspace, confirm a banking connector has synced data with more than one account_balances period, 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

Query account_balances for the newly connected account and find only one row (the initial sync snapshot). Report that there isn't enough history yet to show a trend — one balance point, not a series — and offer to check back once a second period has synced, rather than guessing a direction.