Wealth Desk

Independence

A read on financial independence and retirement readiness: the safe annual draw the portfolio supports, the runway it buys, and how the user's what-if scenarios change it. Load when the user asks if or when they can retire, about safe withdrawal, runway, or to model a drawdown scenario.

Market lookup

Answer a markets question — a stock/ETF/index quote, today's move, or financial news on a holding. Load when the user asks for a current price, market level, "how is <ticker> doing", or news about a company you track.

Money checkup

A holistic read on where the household stands financially: net-worth trend and what moved it, savings rate, allocation and tax shelter, leverage, and progress against goals. Load when the user asks how they're doing, for a financial check-in, or where they stand.

Money plan

Set and track the household's long-term money plan: goals like a retirement number, a debt-free date, a big purchase, a savings rate, or a target allocation, plus the cadence to revisit them. Load when the user wants to set a financial goal, review the plan, or check progress toward a target.

Onboarding

Build a working dashboard scaffold and capture household identity. Load when the user asks to set up, build, or start their wealth dashboard — not just because get_dashboard returned null.

Refresh

Refresh the Tier 1 dashboard — orchestrate the end-to-end update of the household's daily live financial numbers. Load when the user asks to refresh, update the dashboard, or refresh Tier 1.

Get current time

Return the current wall-clock time. Use this when reasoning about elapsed time (e.g. current minute of a live match, time until a deadline) or about what day it is — don't guess the time or the date. By default `now_iso` and `local_date` are in the user's own timezone (near midnight the UTC date is a day ahead of the user's local date). Pass `timezone` (an IANA name like 'Europe/Berlin') only to override that, e.g. to read the time in another location.

Get dashboard

Read the Wealth Desk dashboard — the JSON payload the wealth.q5m.ai SPA renders directly. Returns the current snapshot or null if no dashboard has been written yet. Scope resolves automatically from the session (household when bound, personal otherwise).

Update dashboard

Update the Wealth Desk dashboard with a JSON merge-patch (RFC 7396). Top-level keys merge recursively, arrays and scalars replace wholesale, null deletes a key. **Calling convention:** the merge-patch document goes inside a single `patch` argument — DO NOT spread `meta`, `netWorth`, etc. at the top level of the tool arguments. Correct shape: ```json { "patch": { "meta": { "asOfLabel": "...", "refreshedAtTitle": "..." }, "netWorth": { "value": "...", "delta": "..." }, "balanceSheet": { ... } } } ``` Wrong: `{"meta": {...}, "netWorth": {...}}` — that sends `patch=null` and the call is rejected. Send only the sub-trees you actually changed; siblings you omit (`tech`, `drawdown`, copy) stay intact. Scope resolves from the session automatically.

Init dashboard

Create the starting Wealth Desk dashboard. Use this once during onboarding when `get_dashboard` returns null — the SPA needs a fully-shaped payload to render at all, even before any real numbers are loaded. The tool writes a zero-state scaffold (empty rows, $0 totals, placeholder editorial) with the household identity values from `seed` applied. The first refresh fills in real balances. Refuses to overwrite an existing dashboard. If one already exists, the call returns an error and you should ask the user whether they want to reset (they almost never do).

Get refresh log

Read the refresh history for this household / user. Returns the last entries (newest first) recorded by past Tier 1/2/3 refreshes — each entry includes `as_of`, `tier`, and a free-form `diff_summary`. Empty list if no refreshes have run.

Append refresh log

Record a refresh in the household / user refresh-log. The store keeps only the most recent 30 entries — older ones are trimmed automatically. Use this once per refresh after writing the dashboard, so reviewers can see what changed and when.