Current holdings derived from the user's transaction log: ticker, shares, avg cost, current price, market value, P&L (absolute and %), plus an optional risk summary (Sharpe, volatility, drawdown) from snapshot history and FX return decomposition when a non-USD display currency is requested. All monetary values are returned in display_currency (default USD). Each holding carries asset_type (stock for listed equities; crypto/commodity/real_estate/other for manually-valued assets) and syncedAt — the price as-of date. For non-stock holdings syncedAt reflects the last add_price entry; a null syncedAt (or currentPrice) means the asset has never been priced. This is a drill-down tool: for any check-in or portfolio question, call get_market_brief first — it already includes this data plus weights, news, earnings, and macro context. Use show_portfolio only when the holdings table itself is the sole thing asked for, or to inspect FX decomposition.

Full transaction log (buys, sells, deposits, dividends, taxes) ordered by date ascending. Pass ticker to filter to one symbol — useful for "show me all my AAPL trades" or computing a per-position story. Works for non-stock asset names too (e.g. "Bitcoin"); the match is case-insensitive. Each row has the original currency it was entered in; price is returned in display_currency (default USD).

Stored balance sheet entries (assets + liabilities) by period. Each entry has type (asset|liability), sub_type (cash|investment|other|short_term|long_term), category, amount in display_currency (default USD), and the entry date. Without period, returns ALL periods — use this for trends; with period (YYYY-MM), returns one month's snapshot.

Stored monthly cash flow entries (income + expenses) by period. Each entry has type (income|expense), sub_type, category, amount in display_currency (default USD), date. Without period returns all periods; with period (YYYY-MM) returns one month. For trend analysis use report with target "flow" which aggregates and adds savings rate.

Portfolio concentration measured by Herfindahl-Hirschman Index (HHI) across ticker, currency, sector, and country dimensions. HHI ranges 0–10000; >2500 is high, >5000 very high. Returns top contributors per dimension, plus the pairwise 90-day correlation matrix and an effective-N (correlation-adjusted holdings count): two holdings at 0.9 correlation count as roughly one for diversification. effective_n / correlation_matrix_90d are null/empty until firma sync populates the correlation cache.

Diagnostic: ALL-IN-ONE composite read of current portfolio state. Call this FIRST for any portfolio, market, regime, or check-in question - it returns a comprehensive snapshot in a single response, so you almost never need multiple tool calls just to answer 'how am I doing today'. Returns deterministic, rule-derived facts only — no forward-looking probability distributions, no caller-supplied assumptions. For probabilistic projections (FIRE timelines, short-horizon outlooks under explicit assumptions), use project_net_worth. All monetary values come back in display_currency (default USD). Bundles: meta (single gate capsule with base_date, fx state, fx_caveat, is_nyse_open, display_currency, presentational_constraints), portfolio + holdings (with per-stock fundamentals), concentration (HHI + effective_n + 90d correlations), diversification_insight + diversification_gaps, movers, news (with rule-derived attribution), earnings_upcoming + ipo_calendar + dividend_calendar + economic_calendar, macro + signals (regime, stress, next_week_scenarios), global_macro + disasters, commodities, snapshot_comparison + week_performance, risk_summary, goal_tracking (measured CAGR vs needed CAGR — no projected_net_worth), stance, recommendations (with size_hint.phases / event_window / proceeds / funded_by_rec_ids / is_ceiling_breached), rebalance_chain, watchlist. show_* tools are drill-downs, not peers - call them only when the user asks for a single dimension in more detail than the brief carries. Cached per day on disk.

Aggregated wealth reports. target selects the view: balance — monthly net worth trend; flow — monthly income, expenses, net flow, savings rate; settle — single-period balance + cash flow summary with computed totals (defaults to current month, use period to pick another); combined (default) — both balance and flow trends in one call. Primary entry point for wealth-trajectory questions ("are my assets growing?", "is my net worth trending up?", "am I getting wealthier?") — portfolio value alone is insufficient because it ignores cash savings, debt paydown, and savings rate. Pair with show_snapshot when the user wants the market-driven slice of the trajectory.

Insert one or more transactions in a single call. transactions is an array — pass one entry for a single trade, many for a CSV / brokerage export / paste import. Rows are sorted by date ascending before insertion (average cost depends on insertion order). For bulk imports: first show the user your detected column mapping and total row count, wait for their confirmation, then call this once with all rows. Types: buy/sell move shares; deposit adds shares (set price=0 for grants/transfers, or actual cost basis); dividend/tax record cash events (price = total amount, shares = 1).

Reason capture (critical for thesis tracking): For NEW buy/sell trades — not historical bulk imports — the reason field is the single highest-leverage input you can capture for the user's long-term self-feedback loop (powers show_thesis_track later). When the user logs a NEW single buy/sell without supplying a reason, ALWAYS ask before calling: "What's your reason for this trade? Even one short sentence — 'earnings beat thesis', 'rebalancing toward defensive', 'avg-down on dip' — is enough." Then include their answer in reason. Skip the ask only when (a) the user is explicitly migrating historical data, or (b) the trade type is deposit/dividend/tax (no investment decision).

Each row carries its own asset_type (default 'stock'), which splits two flows:

• stock: price is in the market's native currency (US→USD, KRX/KOSDAQ→KRW, JP→JPY, HK→HKD, LSE→GBP, XETRA→EUR, NSE→INR, TW→TWD) — market determines it, the currency param is ignored. Non-US holdings must set market to the listing exchange; ticker stays the bare local code (e.g. market: "KRX", ticker: "005930").

• crypto / commodity / real_estate / other: there is no market or price provider — these are priced manually (not auto-synced). market is ignored and stored null, ticker is a free-form name (e.g. "Bitcoin", "Seoul apartment"), and price is in the currency param (default USD).

In both cases price is converted to USD at the transaction date before storing — every stored price is USD.

A single-entry call returns the inserted transaction; a multi-entry call returns a per-ticker / per-type summary.

Update fields of an existing transaction by id. Only provided fields are changed.

When price is supplied it is converted to USD at the transaction date before storing. The native currency it is interpreted in depends on the (effective) asset type: for a stock it is the market's native currency (the new market if passed, else the existing one); for a non-stock asset it is the currency param (default USD).

Changing asset_type mirrors add_txn's fork: switching TO a non-stock type (crypto/commodity/real_estate/other) clears market to null (any market arg is ignored); switching TO 'stock' uses the supplied market (or keeps the existing one, defaulting to US).

Delete a single transaction by its id. The user must confirm — never call this without explicit instruction (e.g. "delete transaction #42"). Removing a transaction recalculates all subsequent positions/avg cost since holdings are derived from the log.

Upsert one or more balance sheet entries (also edits — same composite key overwrites). entries is an array: pass one entry to record a single balance item, many to import a net-worth spreadsheet (rows = months, columns = categories) in one call. Prefer add_monthly for full month-end settlement. sub_type: cash|investment|other (assets) or short_term|long_term (liabilities). VALID BALANCE CATEGORIES — assets: cash, savings, housing_sub, usd_cash, cash_other, domestic_stock, overseas_stock, real_estate, pension, vehicle, deposit, asset_other. Liabilities: credit_card, short_term_other, loan, long_term_other. Use ONLY these category strings — do NOT invent your own. For non-USD users: pass currency as the native currency (e.g. "KRW") and amount in that currency — converted to USD via historical FX at date. Use category="usd_cash" (currency="USD") for USD-denominated assets held alongside home-currency ones.

A single-entry call returns the upserted entry; a multi-entry call returns counts grouped by period.

Upsert one or more cash flow entries (also edits — same composite key overwrites). entries is an array: pass one entry to record a single flow item, many to import an income/expense spreadsheet (rows = months, columns = categories) in one call. Prefer add_monthly for full month-end settlement. VALID FLOW CATEGORIES — income (sub_type=employment): salary, business. Income (sub_type=investment): dividends, interest. Income (sub_type=other): income_other. Expense (sub_type=consumption): personal. Expense (sub_type=fixed): insurance, phone, utilities. Expense (sub_type=housing): rent, maintenance. Expense (sub_type=debt): loan_repayment. Expense (sub_type=other): expense_other. Use ONLY these category strings — do NOT invent your own.

A single-entry call returns the upserted entry; a multi-entry call returns counts grouped by period.

Batch upsert balance and flow entries for a single period in one call. Primary tool for month-end settlement / 월말 결산. When the user says "결산", "월말 결산", "month-end closing", or "record this month" — do NOT just display data. Instead: (1) ask for each balance category and each cash flow category; (2) confirm the numbers; (3) call this tool once with the full arrays. VALID BALANCE CATEGORIES — assets: cash, savings, housing_sub, usd_cash, cash_other, domestic_stock, overseas_stock, real_estate, pension, vehicle, deposit, asset_other. Liabilities: credit_card, short_term_other, loan, long_term_other. VALID FLOW CATEGORIES — income: salary (employment), business (employment), dividends (investment), interest (investment), income_other (other). Expense: personal (consumption), insurance (fixed), phone (fixed), utilities (fixed), rent (housing), maintenance (housing), loan_repayment (debt), expense_other (other). Use ONLY these category strings and their matching sub_type — do NOT invent your own. After recording, call report with target "settle" to show the confirmed summary.

Set the current price of ONE non-stock asset (crypto / commodity / real_estate / other). These assets have no market data provider, so their market value is entered manually — unlike stocks, which are auto-priced by sync (scope='prices'). Resolve name against the user's non-stock holdings (case-insensitive). value is in currency (default USD) and is converted to USD at today's date before storing. Calling it for a stock returns an error (stocks are auto-priced — use sync with scope='prices'); an unknown name returns a clear not-found error.

Delete balance entries for a period. If category is provided, only that single entry is removed; otherwise all entries for the period are deleted.

Delete flow entries for a period. If category is provided, only that single entry is removed; otherwise all entries for the period are deleted.

Sync latest prices from Finnhub then record a portfolio snapshot for today. Required before snapshot data is useful.

Update shares, avg_price, or current_price for a holding in a snapshot. Identified by date + the asset (asset_type + market + ticker). Works for non-stock assets too — pass their asset_type; market is ignored for non-stock.

Delete all portfolio snapshot rows for a given date (YYYY-MM-DD). Use only when the user explicitly asks to remove a bad snapshot — destructive.

Query portfolio snapshot history. Without ticker, returns daily total market value in display_currency (default USD). With ticker, returns per-holding time series with prices in display_currency. IMPORTANT: For any projection, goal-timeline, or "when will I reach X" question, this tool alone is insufficient — it only provides historical trajectory. You must also call get_market_brief (for current macro regime, stress score, and signals) and use risk_summary.annualized_vol + signals.regime to build bear/base/bull scenarios rather than extrapolating linearly from past returns. Linear extrapolation from snapshot history is a category error for forward-looking questions.

Compare portfolio return against benchmark indices (default: SPY and QQQ). Uses daily snapshot history when available for accurate time-series comparison; falls back to cost-basis vs current value when no snapshots exist.

Portfolio risk metrics derived from snapshot history: annualized volatility, max drawdown, Sharpe ratio, Sortino ratio, win rate, and beta vs benchmark. Requires at least 10 daily snapshots — if the user has fewer, suggest running firma add snapshot regularly.

Estimated annual dividend income for all holdings. Returns per-ticker yield, annual DPS, and estimated income in display_currency (default USD). Only includes tickers with dividend data.

Recent company news from Finnhub for a single ticker — headline, summary, source, published timestamp, URL. Default lookback is 7 days, capped to limit items (default 10). For news across all holdings in one call, prefer get_market_brief which aggregates the last 24h.

Fetch SEC-reported financials for a ticker. Returns key income statement, cash flow, and balance sheet metrics extracted from XBRL filings.

Valuation deep-dive for a single ticker: PEG ratio, Price/Sales, and FCF yield — computed from 8 quarters of SEC filings. Use when the user asks 'is X overvalued / cheap?', 'what's the PEG?', 'how does the valuation look?'. Requires Finnhub key. Market cap and PE come from the price cache; revenue, EPS, operating cash flow, and capex come from XBRL filings.

Fetch earnings calendar. Without a ticker, returns upcoming earnings for all held tickers. With a ticker, returns history + upcoming.

Curated macro snapshot in one view: 8 indicators (VIX, 10Y Treasury, yield curve, USD index, HY credit spread, breakeven inflation, Fed funds, plus FX vs the requested display currency, each with current value, 30d/90d delta, and 5y average), plus an Economic Stress Index (0–100 from 5 FRED series with per-component breakdown), and a macro regime bias (Risk-on / Mixed / Risk-off from 5 binary signals). The display_currency arg drives the FX series selection (USD = no FX line).

Inspect the local FX rate cache (foreign per 1 USD). Without currency, returns per-currency coverage (count + first/last date). With currency + date, returns the point-in-time rate, falling back to the most recent within lookback_days. With currency + from/to, returns the cached series for that range. With currency alone, returns the limit most-recent rows. USD has no rows (it's the base, always 1.0).

One-shot setup diagnostic. Call this at the start of every conversation, and any time the user asks for analysis but you're unsure what data is available. Returns: API key state, data counts (transactions / balance / flow / prices / snapshots / FX), profile, next_steps for onboarding, capabilities (which kinds of analysis are currently possible), and analyst_context (the persona, principles, data_gating rules, and reasoning frameworks). Treat capabilities as a hard gate — if a required capability is false, follow the matching data_gating rule instead of fabricating an answer.

Read the user's stored profile (birth year, retirement target year, target net worth, risk tolerance, free-form notes). Target net worth is returned in display_currency (default USD). Returns null if no profile is set. Use this to anchor analysis to the user's actual goals rather than generic advice.

Update the user's profile. Partial updates — only provided fields are changed. All fields are optional; capture only what the user volunteers, never invent values. Birth year and retirement target year are 4-digit years; target_net_worth is in the supplied currency (default USD) and stored internally as USD via the latest FX rate; risk tolerance is one of conservative/moderate/aggressive; notes is free-form for preferences/constraints.

Refresh local caches. scope='prices' fetches latest stock prices (US via Finnhub, non-US via Yahoo, all stored in USD; requires finnhub_api_key). scope='fx' backfills the historical FX rate cache from FRED (KRW/JPY/EUR/CNY/GBP/HKD/INR/TWD per USD, increment-only; requires fred_api_key). scope='all' (default) runs prices then fx, mirroring firma sync.

Thought experiment: forward-looking Monte Carlo projection of net worth under caller-supplied assumptions, multi-scenario. Runs monthly GBM under one or more (return, vol) pairs in parallel, adds a fixed monthly contribution, applies one-time life events, and returns P10 / P25 / P50 / P75 / P90 trajectories per scenario. horizon_months accepts any length from 1 (next month) to 720 (60 years) — same tool answers short-horizon outlooks and long-horizon FIRE planning. target_value is optional: when supplied, the response includes probability of reaching it and median months to reach; when omitted, just the distribution at the horizon. All monetary inputs/outputs are in the requested currency (default USD). YOU MUST set scenarios[].expected_annual_return and scenarios[].annual_volatility explicitly and disclose them verbatim to the user — firma does NOT bake in defaults. For reference, brief.risk_summary carries the user's realized 90d annualized_return_pct and annualized_vol_pct — those make a natural 'historical' scenario you can contrast with bear/bull overlays. All scenarios share the same seeded shock sequence so cross-scenario differences reflect (return, vol) — not random noise. For current portfolio state, use get_market_brief — that is the diagnostic tool; this is the thought-experiment tool.

Call this for any short-horizon outlook question (1 day to 1 week). Trigger phrases: "내일", "tomorrow", "이번 주", "next week", "화요일", "수요일", "this Thursday", "how might X day look", "what if [macro event] happens", "FOMC 영향", "earnings 영향", "포트 어떻게 될까", "내 포트는 어떨까". DO NOT answer these from the brief alone — the brief is diagnostic only. This tool turns the brief's measured data into a quant answer. Thought experiment: deterministic conditional analysis. Given hypothetical market shocks, returns per-holding and portfolio P&L impact based on beta. Unlike project_net_worth (stochastic forward distribution over months/years), this is a point estimate per scenario for the immediate future — "if S&P moves −2% and your TSLA beta is 1.6, your TSLA P&L is impact_usd". Workflow: (1) call get_market_brief, (2) read holdings[].fundamentals.beta_5y into beta_overrides, (3) read risk_summary.daily_vol_pct into daily_vol_pct, (4) construct 2-3 scenarios (e.g. bear / base / bull at equity_pct -0.02 / 0 / +0.02; or hawkish / dovish for a Fed event). Caller MUST supply the shocks (the assumption) and disclose them in the answer. Without beta_overrides each ticker defaults to 1.0; without daily_vol_pct the one-sigma range is null. Use for next-day outlook ("if FOMC is hawkish?"), idiosyncratic event sizing ("my biggest position reports tomorrow, what's the dollar range?"), specific-day outlook ("화요일 시장 어떨까"), and rebalance impact ("if I trim TSLA and rotate to JNJ?"). For long-horizon projection (months/years, FIRE planning) use project_net_worth instead.

Review past trades that have a recorded reason (the thesis) and check whether each thesis played out. Returns each thesis trade with the buy price, current price, days held, price change %, whether the position is still held, and an outcome label (validated_holding / underwater_holding / cut_loss / etc — these are descriptive labels, not judgments). Use this when the user asks 'did my last trade work', 'what's the track record of my AAPL theses', 'review my decisions', or when reasoning about a new buy in the same name as past trades. Coverage_pct tells you what fraction of trades have a recorded reason — if low, encourage the user to add reason when logging future trades.

Track the post-exit performance of positions the user has fully sold — the data brokerage apps deliberately don't show (because it would highlight bad sells). For each ticker the user once held but no longer does, returns the last sell date, last sell price, current price, days since exit, post-sell price change %, and a label: missed_rebound (+20% or more since sell — sell was likely premature), good_call (-20% or more — sell saved losses), neutral_exit, or too_recent (<14 days, signal noise). Use when the user is contemplating a sell, reviewing past decisions, or asking 'have my sells worked out?'. Pair with show_thesis_track to connect the original buy thesis to the sell outcome. The summary counts make the user's overall sell discipline visible at a glance.