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. For the daily check-in, prefer get_brief which already includes this data plus weights, news, earnings, and macro context in one call.

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. Each row has the original currency it was entered in.

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 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 USD, date. Without period returns all periods; with period (YYYY-MM) returns one month. For trend analysis use report_flow which aggregates and adds savings rate.

Raw cached price rows for all synced tickers — current_price, prev_close, change_percent, 52w high/low, dividend yield, sector, country, last sync time. Useful for tool-level inspection or when you need price metadata not exposed by show_portfolio (e.g. sector classification, sync freshness).

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.

The single entry point for any market or portfolio question — call this first before reaching for individual tools. Bundles in one response: full holdings with weights and daily P&L; concentration (HHI by ticker/sector/country); today's movers; recent news per ticker; upcoming earnings; economic calendar; macro snapshot (VIX, 10Y yield, FX impact in home currency); Economic Stress Index (0-100); Macro Regime bias (Risk-on / Mixed / Risk-off from 5 signals); World Bank global macro (GDP growth, inflation, unemployment for major economies); active disaster alerts (GDACS Orange/Red); commodity prices (WTI, Gold, Copper); upcoming dividend calendar for holdings; and pre-computed insights that cross-reference all of the above with portfolio composition. Use this for: 'how is my portfolio doing', 'what's the market situation', 'brief me on this week / next week', 'what should I watch out for', 'any macro risks', 'any upcoming dividends'. Only call individual tools (show_macro / show_stress / show_regime / show_world_intel / show_valuation) when drilling deeper after reading the brief. Cached per day on disk. PRESENTATION RULE: Never list data sections sequentially. The response must be a synthesized narrative. Use insights[] as the primary thread — each entry already cross-references data sources. For each insight, explain the second-order consequence for the portfolio: a mover + upcoming earnings = compounding event risk; a regime shift + sector concentration = tail-risk amplifier; stress score + drawdown = whether to trim or hold. If the same ticker appears across movers, news, and earnings, that is the story — lead with it. Numbers are evidence, not the headline. The goal is one coherent read on what today means for this specific portfolio, not a structured report on what the data contains.

Aggregate balance sheet entries by period. Returns monthly net worth trend sorted by period.

Aggregate cash flow entries by period. Returns monthly income, expenses, net flow, and savings rate sorted by period.

Read-only summary for a period: balance sheet + cash flow entries with computed totals (net_worth, net_flow). Use this to review month-end settlement results after entries are recorded via add_balance / add_flow. Defaults to the current month.

Both balance sheet and cash flow trends in one call. Equivalent to calling report_balance and report_flow with the same limit. 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 stock transaction. For bulk imports: first show the user your detected column mapping and total row count, wait for their confirmation, then call once per row in chronological order (average cost depends on insertion order). 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). For buy/sell, capture the user's reason (the why behind the trade) when they share it — even one short sentence helps later analysis cross-check thesis vs outcome. The currency arg is the trade's native currency, not the user's home currency.

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

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 a single balance sheet entry for a period (also edits — same composite key overwrites). Use this when recording just one or two balance items; 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.

Upsert a single cash flow entry for a period (also edits — same composite key overwrites). Use this when recording just one or two flow items; 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.

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_settle to show the confirmed summary.

Bulk-insert transactions in one call. Use this for any import larger than ~5 rows (CSV / brokerage export / paste). Sorts by date ascending automatically — average cost depends on insertion order. Returns a per-ticker / per-type summary so you can confirm the import to the user. For one-off entries during conversation, prefer add_txn.

Bulk-upsert balance sheet entries (assets + liabilities) across multiple months and categories in one call. Use when importing a net-worth spreadsheet with rows = months and columns = categories. Each entry overwrites if (period, type, sub_type, category) already exists. Returns counts grouped by period. Each entry can specify its own native currency — defaults to USD; non-USD values are converted via historical FX at date.

Bulk-upsert cash flow entries (income + expenses) across multiple months and categories in one call. Use when importing an income/expense spreadsheet with rows = months and columns = categories. Each entry overwrites if (period, type, sub_type, category) already exists.

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 specific holding in a snapshot. Identified by date + ticker.

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. With ticker, returns per-holding time series. 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_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. 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_brief which aggregates the last 24h.

Fetch recent insider buy/sell transactions for a ticker from Finnhub. transactionCode: P=buy, S=sell, A=award, G=gift, M=exercise

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 (8 indicators: VIX, 10Y Treasury, yield curve, USD index, HY credit spread, breakeven inflation, Fed funds, plus FX vs user's home currency). Each indicator has current value, 30d/90d delta, and 5y average. The home_currency arg drives the FX series selection (USD = no FX line).

Economic Stress Index (0–100) computed from 5 FRED series — yield curve (T10Y2Y), bank spread (T10Y3M), volatility (VIXCLS), financial stress (STLFSI4), initial jobless claims (ICSA). Returns total score, label (Low/Moderate/Elevated/Severe/Critical), and per-component breakdown with weights and formulas. Pure descriptive, no advice.

Macro regime bias (Risk-on bias / Mixed / Risk-off bias) from 5 FRED-based binary signals: VIX level, yield curve, HY credit spread, USD trend (30d), and breakeven inflation. Each signal evaluates to bullish/bearish; ≥70% bullish → risk-on, ≤40% → risk-off, otherwise mixed. Returns full signal breakdown — never present as advice.

Global intelligence drill-down: World Bank macro (GDP growth, inflation, unemployment per country) + GDACS active disasters (Orange/Red alerts). No API keys required. Use after get_brief when you need more detail on global risks — e.g. 'which countries are in recession', 'any active crises affecting my holdings', 'compare inflation across major economies'. Shows all currently active alerts, Orange+ by default.

Fetch a FRED (Federal Reserve Economic Data) time series by ID. Returns metadata + observations. Common series: VIXCLS (VIX), DGS10 (10Y Treasury), T10Y2Y (yield curve), DTWEXBGS (Dollar Index), FEDFUNDS, CPIAUCSL, UNRATE, BAMLH0A0HYM2 (HY spread), DEXKOUS (KRW/USD), DEXJPUS (JPY/USD), DEXUSEU (USD/EUR — invert for EUR/USD).

Search the FRED catalog (800K+ economic time series) by keyword. Returns series IDs ranked by popularity. Use this when you don't know the exact series_id for an indicator.

Inspect the local FX rate cache. Without currency, returns per-currency coverage (count + first/last date). With currency, returns the cached series — date range via from/to, or limit most-recent rows. USD has no rows (it's the base, always 1.0).

Look up the historical FX rate for a date and currency from the local cache (foreign per 1 USD). USD always returns 1.0. Falls back to the most recent rate within lookback_days (handles weekends/holidays). Returns null if no rate found in the lookback window. Run sync_fx_rates first to populate the cache.

Backfill historical FX rate cache (KRW, JPY, EUR, CNY, GBP per USD) from FRED. Increment-only: starts from the last cached date, fetches up to today. On first run, backfills from earliest user transaction/balance/flow date. Required for accurate historical currency conversion.

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 in USD, risk tolerance, free-form notes). 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 USD; risk tolerance is one of conservative/moderate/aggressive; notes is free-form for preferences/constraints/tax situation.

Fetch latest stock prices from Finnhub and update local cache. Requires finnhub_api_key in ~/.firma/config.json