Yoshi

Get posted/current and available cash across all visible depository accounts (checking + savings), with per-account freshness and balance provenance, relevant in-flight transfers, and transfer-aware current-total reconciliation. Freshness `as_of` values are ISO timestamps in UTC. When converting one to the user's timezone, convert the instant exactly; otherwise retain the UTC time and label it UTC. Never relabel the raw UTC clock time as a local timezone. Use this when the user asks: "How much cash do I have?", "Total savings", "Cash across all accounts", or asks for a named depository account's available balance, posted/current balance, pending-balance difference, or balance timestamp. This is the authoritative tool for paired depository balance semantics; do not also call get_financial_position for those questions because its effective position amount cannot distinguish the two provider fields. Use available cash for amounts the user can spend or invest. `total_cash` is available-first, but falls back to posted/current for each account whose provider omits `balance_available`; disclose any such fallback and do not call that portion confirmed available or claim it reflects pending activity and holds. Use posted/current only when the user specifically asks for the posted balance or a balance before pending activity. If the two differ, label both and briefly explain the distinction using `current_balance_basis`, `in_flight_transfers`, and `current_reconciliation`. `total_cash_current` is a raw account sum; never present it as the user's reconciled total when reconciliation is partial or an in-flight transfer has a non-`none` aggregate effect. Prefer `total_cash_current_reconciled` when present. For `partial`, report the available total plus the known account and transfer facts without inventing a reconciled number. Optionally includes historical available-first cash snapshots. For actual transfer capacity, use the transfer endpoints/options tools because operational limits can be lower than the available balance.

get_cash_overview

Get the user's credit score and debt profile in one call. Returns credit score with bureau/model/range, plus total debt, breakdown by type, per-debt details (balance, interest rate, minimum payment, due date), and high-APR debt total.

get_credit_and_debt_profile

Get the full definition of business concept(s). Call this when you want to get more business logic or concepts before generating responses. The concept definition will provide the correct approach, patterns, and common mistakes to avoid. Supports batch retrieval: pass a list of concept IDs to get multiple definitions in a single call (more efficient than parallel calls).

get_domain_concept

Resolve canonical financial metrics using the same definitions and implementation used by one-time and recurring automations. Prefer this over calculating metrics yourself or querying raw tables. In a conversation, portfolio facts return their dollar fields (values, flows, dollar returns, gains, income, fee and trade totals) only with `include_amounts=true`; set it when the user's own words ask for money or the task needs the figures (sizing a trade, rebalancing, a tax-loss question). `portfolio.completed_session_performance` returns the verified, flow-adjusted Yoshi Cash plus Yoshi Brokerage result for one XNYS session: `return_ratio` (0.01 means 1%), opening-baseline and ending session dates, official close time, and data-through time, plus dollar return, opening/closing value, and external net flow with amounts. `latest_completed` selects the newest session eligible after close plus the publication buffer; unavailable canonical closes return `not_finalized`, never an older session. `specific_session` requires the exact `session_date` and never substitutes. For today so far, intraday, premarket, or live-session questions, use `portfolio.market_day`. This fact excludes external and Plaid investments. Currently registered: `portfolio.performance`, which returns TWR, drawdown, value change and peak details; `portfolio.market_day`, which returns the current market-session portfolio return, available top individual-stock performance, and the dollar change and value from the same canonical snapshot used by the product; `cash.position`, which distinguishes posted/current cash from provider-available cash and returns excess cash after canonical reserves, emergency-fund months, and reserve components while conservatively accounting for pending outgoing transfers without double-subtracting provider pending activity. It also exposes every registered price, moving-average, volume, realized-volatility, and volatility-change metric from the automation catalog, plus goal progress, current transfer/account state, durable transfer completion/failure and account connection/disconnection events, and normalized deposit, withdrawal, dividend, or interest occurrences, plus allocation, signed target drift, unrealized gain/loss, and `calendar.exchange_session` for the canonical current/next exchange session, holidays, early closes, and DST. `transfer.summary` returns the user's Yoshi transfer aggregates over a `window` (default `all`): completed deposit and withdrawal totals and counts, net, in-flight and unsuccessful counts, the largest transfer, the most recent completed deposit and withdrawal, and since-inception totals with the first transfer date. Add `group_by` (`month` or `quarter`) for a per-period series plus the period with the largest deposits and withdrawals, or `group_by` `account` (side-by-side Yoshi account totals) or `transfer_type` (per rail). `transfer_rail` (`ach`, `wire`, `check`, `book`, `realtime`) and `transfer_direction` (`inbound`, `outbound`, `internal`) narrow every figure, since-inception included: `check` + `outbound` answers whether the user sent a check. `latest_n` (at most 50) also lists the newest transfers in the window, every status, under the same selectors. By default moves between the user's own accounts are counted but not summed; `include_internal` sums them on the user's own sides (a withdrawal of the sending account, a deposit of the receiving one), only when the user asks to include moves between their own accounts or about transfers of any kind. With `transfer_direction` it keeps that side only. Pass the account in `account_ids` when the question names one. `latest_n` already lists moves between accounts, so a "last few transfers" question never needs `include_internal`. It is the right read for any question about how much was moved in or out, how many transfers there were, the largest or latest completed one, rail-specific history, or contributions over a date range. Without `account_ids` it combines every Yoshi account; with them it covers only transfers whose Yoshi side is one of those accounts (deposits that landed in it, withdrawals that left it, and moves between Yoshi accounts on either side, counted but not summed by default; with `include_internal`, summed on that account's own side), since-inception totals included. `portfolio.statement` returns the user's Yoshi brokerage statement over a `window` (default `ytd`): dividend, interest, fee, buy and sell totals and counts, the largest transaction, dividends by security, and the same window's return with its start value, end value, net flows and market change. Add `interval` (`month` or `quarter`) for a per-period statement series, each with its own totals and return. It is the right read for dividend, fee, or trading totals, per-security dividends, trade counts, a calendar-period return, the best or worst month, or, when the user asks for amounts, a monthly statement that separates contributions from market gains. Without `account_ids` it combines every Yoshi brokerage account the user holds; with them it covers only the activity and value of those brokerage accounts. `cashflow.summary` returns money out of and into Yoshi Cash over posted transactions in a `window` (default `1m`): spending total and count, income total and count, net (income minus spending), and the largest expense and income. Spending here is every outflow except moves between the user's own accounts and rows the user excluded, which on Yoshi Cash is mostly transfers to outside accounts and payments to people, not card purchases; income is inflows categorized as income, mostly interest, never a merchant refund. Describe it that way rather than as card spending. Add `interval` (`month` or `quarter`) for a per-period series with the period of largest spending and income; add `breakdown` (`category` or `merchant`) with `top_n` (default 10, at most 50) for the largest spending and income groups with each one's share. For a total with one merchant or person, pass `merchant` (a case-insensitive substring of the counterparty name), which narrows every figure. Merchant labels are raw counterparty names, so two spellings of one business are two groups, and a counterparty missing from a top-N list is not a zero. It is the right read for money out or in by month, a total with one counterparty or per counterparty, and money out versus income; for a category breakdown of spending alone `get_spending_by_category` remains the direct read. With `account_ids` it covers only those Yoshi Cash accounts. None of these facts covers a linked outside account. An `account_ids` entry must be, for the transfer summary, a Yoshi account the user owns or may read; for the cashflow summary, a Yoshi Cash account the user owns or may read (closed and hidden included for both); for the statement, one of the user's active Yoshi brokerage accounts. Anything else is refused. A transfer or cashflow window ends on today (a deposit or purchase made today counts); a statement period ends on the latest completed market session, so a question that asks for both can see two different end dates. All three accept `window` as a period shorthand (`1w`, `1m`, `3m`, `ytd`, `1y`, `all`) or an explicit inclusive `YYYY-MM-DD,YYYY-MM-DD` range; use the explicit range for a named month, quarter, or year. Use `transfer.status` and `account.connection` only for current state. When the user asks whether something happened within a time window, use the matching durable lifecycle fact: `transfer.completed_event`, `transfer.failed_event`, `account.connected_event`, or `account.disconnected_event`, with `occurrence_window_days`. Never substitute current state for historical occurrence evidence. `cashflow.occurrence` checks the last `occurrence_window_days` days across permitted accounts; it cannot honor an explicit historical `window`, `account_id`, or `account_ids`. For interest credited in a named date range or on a particular account, use `list_transactions` with that date/account scope and inspect the interest credits. Never interpret an unsupported scope or an empty recent window as zero interest in a different historical period. `market.price.current_session_return` reports one security's current-session movement from the previous official regular-session close and preserves an explicit unavailable result when no eligible current-session quote exists. Price-history metrics (returns, rolling highs and lows, moving averages, volume, volatility) answer only from current daily history; when it is out of date they return `stale_history` with the date it ends on: say that date and that it is out of date, and never present older data as current. `security.fundamentals` returns provider-normalized P/E and dividend-yield observations with canonical provenance. `security.analyst_consensus` returns persisted recommendation/target observations and deterministic adjacent-snapshot changes. `security.earnings_calendar` returns the next known provider date and calendar days until it. `portfolio.allocation` is a lookup for one exact selector, not a portfolio-wide breakdown: it always requires both `dimension` and `identifier`. For `position`, identify one held security by its exact ticker or security ID; for `sector` or `asset_class`, use the exact value returned by holdings. Do not call it with only a dimension and do not guess an identifier. If the question needs a holdings or allocation breakdown and no exact selector is already known, call `get_investment_holdings` first, then use its returned values if a single allocation lookup is needed. Other identifier-scoped facts require their corresponding durable id. This tool is read-only. For a user's one-time conditional instruction, resolve the condition here and, only when it is true now, pass the already-selected concrete action to `configure_action`; do not create a recurring or one-shot automation unless the user wants Yoshi to keep watching.

get_financial_metrics

Get a comprehensive overview of the user's finances: net worth, assets vs liabilities, account breakdown by type, and Yoshi Score with component breakdown (Recovery, Capacity, Baseline). Start here for any broad financial question.

get_financial_overview

Analyze the user's income and get Yoshi's recommended allocation. Returns monthly income, variability, current allocation across expenses/debt/emergency fund/investments, and optionally the personalized income strategy (recommended distribution). Replaces the need for separate income summary and strategy calls.

get_income_overview

Get the user's net worth trend over time. Shows how total net worth (assets - liabilities) has changed, with period start/end values and percentage change.

get_net_worth_history

Fetch provider article details by reference from a prior headline response.

get_news_article

List the user's notifications with optional filters. Use this when the user asks: "Any alerts?", "Recent notifications", "Unread notifications", or wants to see system notifications. Use unread_only=true when the user asks for unseen, unread, or missed items. Results are returned newest first. Each item includes its title, body, severity, read state, and occurrence timestamp. For a relative time request such as "this week," use the returned timestamps to include only the requested period; do not describe older returned records as recent.

get_notifications

Get a bounded delayed options chain slice for an equity symbol. Returns calls/puts near the underlying price with strikes, expirations, volume, open interest, and optional greeks. Use only when the user explicitly asks about options.

get_options_chain

Analyze portfolio exposure across asset class, sector, country, region, bond maturity, and credit quality, with fund/ETF look-through where provider data is available.

get_portfolio_exposures

Fetch provider news for the user's largest current holdings and annotate each headline with holding value and portfolio weight.

get_portfolio_news

Get portfolio performance metrics including Time-Weighted Return (TWR) with optional benchmark comparison. Returns total return, realized vs unrealized gains, and daily value series. Benchmarks: VOO (S&P 500), DIA (Dow Jones), VTI (Russell 3000), VO (Russell Midcap), VTWO (Russell 2000), VEA (MSCI EAFE), VWO (MSCI EM), BND (Bloomberg U.S. Agg), USHY (Bloomberg U.S. Corp HY).

get_investment_performance

Get realized gain/loss events from investment sales with summary metrics. Shows individual sale events with ticker, proceeds, cost basis, and gain/loss. Useful for tax planning and understanding realized investment returns.

get_investment_realized_gains

Get bills, subscriptions, and recurring income streams. Returns total monthly recurring commitment, classified into bills vs subscriptions vs recurring income.

get_recurring_expenses

Build the advice-grade context packet required before personalized single-security advice. Use this instead of `research_security` when the user asks Yoshi to personalize, choose, rank, size, add, reduce, trim, hold, avoid, or evaluate whether one or more stocks fit their portfolio. This tool does not make the recommendation; it gathers the required readiness, saved suitability facts, direct holdings, fund look-through exposure, concentration context, product policy, source policy, security data, and evidence refs for the final gate. Do not use this for plain research such as "what does NVDA do" or "summarize NVDA news" unless the user also asks what they should do for their own portfolio. News and history are paginated. Increase their limits or request later pages when needed. `holdings_limit` accepts `all` for complete holdings returned by the provider.

get_security_advice_context

Get provider news headlines and optional press releases for a stock, ETF, or mutual fund. Use this for ticker-specific news or move explanations.

get_security_news

Get historical price data for a single security over a date range. Always use this tool when the user asks about stock price trends, performance over time, or price charts — do not answer from general knowledge. Works for equities, ETFs (security_type='equity'), and mutual funds (security_type='fund'). Dates in MM/DD/YYYY format. start_date must be ≤ end_date.

get_security_price_history

Analyze where the user's money is going for a given period. Returns top categories with amounts and percentages, discretionary vs non-discretionary split, top merchants, and average daily spend.

get_spending_breakdown

Make the explicitly supplied advice purpose active, then fetch current suitability readiness and the exact fields that are missing, stale, inconsistent, or awaiting confirmation for that purpose. The purpose is required: select the semantic lane for the current request. Use it when the purpose changes inside the tool loop or the user explicitly asks to review profile status and that purpose's current profile is not loaded. For a purpose-neutral profile review, use broad_robo. Do not repeat the read when the graph already loaded that purpose. A missing readiness block does not mean no facts are stale or missing. You may summarize saved facts and outstanding field names, but must not ask the user to supply or choose values in chat; the investor-profile Brief owns the questionnaire. An unsupported purpose remains unsupported regardless of profile completeness.

get_suitability_readiness

List the user's existing durable Yoshi automations, including active and paused Rules and Strategies. Use this before creating, editing, pausing, resuming, or discussing recurring trades/transfers, price-triggered trades, alerts, reports, or auto-categorization so you can avoid duplicates and reason from what Yoshi already has scheduled.

list_automations

List active account corrections for the current user. Use this before disable_account_correction when the user asks to undo, revert, remove, clear, or drop an account override or rename.

list_account_corrections

List all user accounts with balances, grouped by type (depository, credit, investment, loan). Includes interest rates, minimum payments, and payment due dates where available.

list_accounts

List the user's pending, queued, scheduled, running, and recent activity across actions, action jobs, automations, briefs, investment trades, first-party cash transactions, and payments. This tool does not expose externally sourced recurring bills or subscriptions. Do not use it to infer upcoming recurring charges from Plaid data. Never use this tool for a historical largest-transfer, transfer count, transfer total, or transfer average, even when the requested window is recent. Those are complete ledger questions; answer them with get_financial_metrics and the transfer.summary fact. Use this when the user asks what is pending, queued, scheduled, coming up, running, awaiting approval, what work Yoshi recently completed, or what will happen next. Do not use this operational surface for an unqualified request to show "recent activity"; that means recent transactions and belongs to list_transactions plus list_investment_transactions. Only include automations and briefs when the user's wording asks about Yoshi's work or another operational lifecycle. If the user asks for pending plus scheduled/coming-up activity in one question, use status=all (or make separate calls). Do not use status=pending by itself for that combined question because it intentionally excludes scheduled future rows. This is the operational visibility surface. It is broader than the UI feed: the feed intentionally shows only timely items, while this tool can look farther ahead. For recurring trades/transfers, use list_activity to see queued or scheduled occurrences and list_automations to inspect the standing automation definition. Bank pending transactions and pending investment trades are separate lifecycles, so do not treat them as one table. Do not use this bounded operational feed to answer historical transfer counts, totals, averages, largest-transfer questions, or to conclude that no ledger transfers occurred in a date range. Use get_financial_metrics with transfer.summary for those complete first-party ledger-history questions. Past/completed rail-specific history, such as whether the user sent a check, ACH, or wire in a past window, also belongs to transfer.summary, with transfer_rail, transfer_direction and latest_n. Use this tool for current pending, running, queued, scheduled, failed, or approval lifecycle questions.

list_activity

List the user's active brief threads — system-generated financial alerts, insights, and action requests from Yoshi automations. Returns title, brief type (needs_you, alert, insight), description, and timestamps. Supports optional filtering by brief_type and cursor-based pagination.

list_briefs

List the user's financial goals with progress tracking. Shows target amount, current value, progress percentage, on-track status, and monthly contribution needed.

list_goals

List the user's exact in-flight transfers that are pending or processing. Use this when the user asks whether money is currently moving, whether a deposit or withdrawal is still pending, how much an in-flight transfer is for, where it is coming from or going to, or what its precise transfer status is. The result is the canonical transfer lifecycle read and includes amount, direction, exact status, and safe source/destination account labels when the API provides them. Internal transfer and account IDs are deliberately withheld from the model; identify transfers to the user by available account labels, amount, date, direction, and status instead. Completed and failed transfers are not returned. Do not substitute pending bank-card transactions or the broader activity feed for this question. For a still-moving status question, start here without first requesting aggregate transfer statistics. If no matching in-flight record exists, that absence alone does not prove completion; use a scoped historical read before claiming it finished. Pending and processing are distinct exact lifecycle statuses. When a row is pending, call it pending and do not use "processing" as a generic synonym for money movement; when a row is processing, call it processing.

list_in_flight_transfers

List the user's current/open investment tax lots with acquisition dates, remaining quantities, cost basis, current value, unrealized gain/loss, holding period, source, price timestamps, and coverage metadata. Use this for lot-level cost-basis questions, unrealized gains or losses by acquisition lot, and short-term versus long-term holding-period observations. Preserve coverage warnings: partial or unavailable data means the institution did not provide complete lots and must never be described as zero gain, zero loss, or a complete portfolio view. Use get_investment_realized_gains for sold positions. This tool provides factual investment records only; it does not determine wash-sale eligibility, tax liability, or which lots the user should sell. Follow suitability policy before personalized tax-aware recommendations.

list_investment_tax_lots

List the user's investment transactions with account, security, date, quantity, price, amount, and fee fields. A simple last-trade answer needs only the side, security, and date; give quantity, price, amount, or fees when the user asks for them. Use this for investment activity questions, fee analysis, fund expense/commission checks, cash-flow reconstruction, buys/sells/transfers/dividends, or tax-adjacent transaction review. For an unqualified request to show "recent activity", pair this tool with list_transactions and merge the Yoshi Trade and Yoshi Cash rows newest first. Set `fees_only=true` when the user specifically asks about explicit transaction fees.

list_investment_transactions

List transactions that are still pending, optionally filtered by account. Use this when the user asks what transactions have not posted yet, whether there are pending card/bank transactions, or what is still processing.

list_pending_transactions

List active transaction corrections for the current user.

list_transaction_corrections

List specific transactions with filtering by date range, account, category, merchant, amount range, and cash flow direction. For natural language queries like 'coffee shops last week', use search_transactions instead.

list_transactions

List endpoints that can participate in transfers: Yoshi accounts, eligible Plaid-linked checking/savings accounts, and saved external accounts. Use this before submit_transfer to discover the correct from_id and to_id. A transfer must have a Yoshi account on one side. Use transfer_available_cents for all-cash transfer sizing; do not ask users to choose between available and current balances.

list_transfer_endpoints

Forget memory content by deleting a file or removing a specific section/fact. Use this for explicit forget requests and proactive high-confidence cleanup when stored memory is clearly outdated or contradicted by stronger evidence. Before removing a section or fact, call memory_read on the file and copy its exact heading text or fact ID, preserving spaces and punctuation (not a URL slug). Use the returned etag as if_match. Preserve unrelated sections and files.

memory_forget

List memory files for the current user. Use this to discover available memory docs by namespace and optional path prefix.

memory_list

Read a memory file by path. Use this when you need exact memory content such as memory/profile.md, memory/index.md, or topic docs.

memory_read

Search memory files by keyword to find relevant paths and snippets. Use this to quickly locate candidate memory files before reading full content.

memory_search

Create or replace a memory file. Use this for explicit remember requests and proactive high-signal memory updates that are likely to help in future conversations.

memory_write

Preview how transaction corrections change income/expense totals. Use only when the user asks to see impact before changing data; do not use when the current turn already clearly confirms or commands applying the correction. For a payment-app internal transfer, first use list_transactions to find an equal, opposite-direction transaction on another owned account within seven days, then pass its returned IDs as internal_transfer_evidence. Never invent evidence.

preview_transaction_correction

Render the accounts dashboard widget showing account balances and optional balance chart. Call list_accounts (and optionally get_balance_history) first. This widget displays accounts and balances ONLY — it does NOT show transactions. Call at most once per response. Skip for pure text answers.

render_accounts_dashboard