CoinTracker

Use when the user asks to add, connect, or track one or more blockchain public-address wallets. Accepts a batch (1-10) so a user can drop several addresses at once. Each item needs the blockchain network (e.g. BITCOIN, ETHEREUM, BASE, SOLANA) and the public address; the coin is derived from the network. Creates valid wallets independently, then starts one initial background sync for the new wallets when possible. An address alone often does not identify the chain: the same address format is shared across many networks — every EVM chain uses 0x… addresses, and forked chains share their parent's format (so one address can be valid on several networks). Use the network the user named, or infer it only when the address format identifies a single chain. For shared-format addresses, ask the user to confirm the chain before adding; do not guess. Scoped to public-address wallets only — no exchange accounts, xpub/HD, or OAuth-connected wallets. After adding, use get_connected_accounts to check sync status. Synced history feeds the user's tax calculations, so review imported transactions and cost-basis warnings before relying on tax results.

add_wallet_addresses

Use when the user asks to break down taxable income or taxable disposal metrics by time, asset, connected account, or income type — for example staking income by month, gains by asset, cost basis by account, or an all-time total. Pick `metrics` from income, realized_gain_loss (default), cost_basis, proceeds, gross_proceeds, and fees. Income cannot be combined with disposal metrics in one call. Fees cover taxable disposals, not fees across all transactions. Pick one `group_by` dimension from day, week, month, quarter, year, lifetime, asset, connected_account, or income_type, or pair one time dimension (including lifetime) with asset, connected_account, income_type, or term. Group by `term` only alongside a time dimension. The separate `term` argument filters disposals to one term and works with any grouping. Term applies only to disposal metrics and only where the user's jurisdiction distinguishes short and long term. The separate `income_type` argument filters taxable income to one type and works with any income grouping; `income_type` applies only to the income metric. Use `get_tax_summary`, when available, for a tax-year overview and `search_tax_disposals`, when available, for disposal-level rows. Use `tax_year` for filing-year totals; `from_date`/`to_date` and `relative_date_window` use the user's local calendar. Income is attributed by acquisition or receipt time; disposals are attributed by sale time. Omit all date arguments to use the current filing tax year — except with `lifetime`, which then means all-time with no date window. For relative windows like "last 12 months", pass `relative_date_window` (e.g. {"count": 12, "unit": "month"}). Optionally filter to one asset with `asset_label` or one connected account with `connected_account_handle`. Figures use `context.base_currency`; time buckets are UTC-aligned; empty groups are omitted, not zero-filled. Requests that span or match more than 500 grouping combinations are rejected with narrowing guidance. Read-only.

aggregate_tax_metrics

Use when the user asks about connected wallets or exchanges, account balances, sync status, credential action, data completeness, or whether CoinTracker data is ready to rely on for tax/portfolio answers. Returns the authenticated user's CoinTracker connected crypto wallets, exchanges, and manual wallets in one merged list with balances, sync state, last-sync timestamps, and credential-action signals. Use returned `connected_account_handle` values for account-scoped follow-up searches when search tools are available. Default `include_idle_accounts=false` omits unused empty rows but retains active syncs, `sync_status` in {`failed`, `unavailable`, `deleting`, `archived`}, and `credential_action_required=true`. `sync_status=unavailable` means sync cannot run. Treat the cause as unspecified unless `credential_action_required=true` identifies credential action. `sort=attention_first` (default) surfaces rows with `credential_action_required=true` or `sync_status` in {`failed`, `unavailable`} first; `sort=balance` ranks by balance only — use it for 'largest account' questions, since a low `limit` under `attention_first` can push high-balance accounts off the page. When `credential_action_required=true`, `app_links` includes a `reconnect_account` destination — use it rather than guessing a URL. Read-only.

get_connected_accounts

Use when the user asks about crypto portfolio performance or returns over a trailing period, portfolio value, crypto net worth, total holdings, holdings composition, or an asset-specific position. Returns the authenticated user's CoinTracker crypto portfolio value, holdings, cost basis, unrealized P&L (when cost basis is ready), 24-hour change, optional trailing-period performance, explicitly all-time total return on investment, data-quality flags, and uncategorized activity value. When available, use `get_tax_loss_opportunities` for tax-loss harvesting candidates. Default `holdings=overview` returns a bounded slice. Use `order_by` to rank by market value or base-currency unrealized P&L; `value_desc` also prioritizes holdings behind a gap that is not `negligible`. Use `holdings=asset` with `holding_asset_label` to filter holdings by asset label; combine it with `performance_period` for an asset-specific trailing return. Use `holdings=issues` for flagged holdings in priority order. When `starting_value` is zero, `market_return` includes the whole current value; prefer `investment_return` when available. Read `covers_full_period`: infer that nothing was held at the boundary only when it is true. If false, full-period coverage is not established; a null `starting_value` means period returns are unavailable. Use `holdings=none` for totals only; request holdings for breakdowns, rankings, or asset/issue details. Totals match CoinTracker; unpriced holdings limit valuation and returns. A `negligible` `cost_basis_gap` or `total_return_on_investment_gap` is too small to be worth raising unasked. Follow `result_guidance`. Monetary fields use `context.base_currency`. On a value-ranked `overview`, `holdings_returned_value_fraction` says what share of priced value the returned rows carry. Under a P&L ranking, `holdings_unrankable_count` reports unknown-P&L holdings placed after known values. Judge data-quality priority from each holding's `portfolio_totals_effect` and `data_quality_impact`, not flag counts. Read-only.

get_portfolio

Use when the user asks about tax-loss harvesting, harvestable losses, or unrealized losses to review for harvesting. Returns the authenticated user's CoinTracker crypto tax-loss harvesting opportunities, ranked by total unrealized loss. Do not present the result as personalized tax or investment advice. Opportunities are grouped at the (asset, wallet) level, not individual lots. Monetary fields use `context.base_currency`. Read-only.

get_tax_loss_opportunities

Use when the user asks about their crypto taxes, what they owe, capital gains, or a tax-year's totals, income, or accounting-snapshot data-confidence callout counts. Returns the authenticated user's CoinTracker crypto tax summary for a tax year, including curated tax fields plus derived aggregate review-item/callout snapshot signals used to explain data confidence. When available, use `search_transactions` with `needs_review=true` to list which current transactions need attention. When available, use `search_tax_disposals` for transaction-level drivers, ranked realized gains/losses, or disposal cost basis. Omit `tax_year` to use the user's current filing tax year. For net capital gains, prefer `total_capital_gain`; use `short_term_gain` and `long_term_gain` for term detail. `data.total_gains` / `data.total_losses` are jurisdiction-specific totals and may not represent net capital gains for every country. Amounts are crypto-activity subtotals that combine with the user's other gains, losses, and income, so they are not the user's total taxable income or tax owed; report capital gains and income separately, without adding them together. Monetary fields use `context.base_currency`. Read-only.

get_tax_summary

Use when the user asks how to do something in CoinTracker, where a setting or action is, what a feature or plan includes, or about a CoinTracker policy — for example linking a transfer, deleting transactions, or other product how-tos. Also use for account and billing questions (signing in or out, refunds) and yes/no questions about what CoinTracker covers, insures, or is liable for, including mid-conversation. Searches CoinTracker's public help center by meaning and returns at most 3 support articles, closest first, each with `title`, `url`, `distance` (0-1, lower is closer), and a plain-text `excerpt`. Pass the task in plain words as `query`, without names, amounts, addresses, or account details. The closest articles are returned even when none fits, so use an article only if its `excerpt` clearly answers the question; `weak_match=true` means no article was a close match, and it does not mean a feature is absent. Cite the article `url` when describing its steps. Not for the authenticated user's own numbers or transactions; use the data tools for those. Articles describe general product behavior and policy, not this user's account; do not state that the user qualifies, is eligible, or is affected unless a data tool shows it. Read-only.

search_help_center

Use when the user asks for per-transaction realized gains/losses, ranked gains or losses, disposal proceeds, disposal cost basis, holding-period detail, or transaction-level tax-year drivers. Searches the authenticated user's CoinTracker realized crypto tax disposal outcomes: sales, trades, fees, or other outflows with realized gain/loss. When available, use `get_tax_summary` for year-level capital-gain totals. Supports top gains (`order_by=gain_desc`), largest losses (`gain_asc`), largest absolute gains/losses (`abs_gain_desc`), asset-specific disposals, and account-specific disposals. Each summary is lot-derived and includes core disposal accounting facts: proceeds, cost basis, realized gain/loss, short/long-term split when applicable, holding period, and zero-cost-basis lot count. When `search_transactions` is available, pass a returned `transaction_id` to it for deeper row-level detail. Provide either `tax_year` or `from_date`/`to_date`; omit all date arguments to use the user's current filing tax year. For relative windows like "last 90 days", pass `relative_date_window` (e.g. {"count": 90, "unit": "day"}) and the window resolves to `from_date`/`to_date` using the user's timezone and today; do not also pass `tax_year` or `from_date`/`to_date`. Scoped filters combine with AND. Do not ask this tool to filter by short/long-term, tax event, gain range, or zero-cost-basis status; those are lot-derived summary fields returned after the search page is selected. Monetary fields use `context.base_currency`. Read-only.

search_tax_disposals

Use when the user asks about specific crypto transactions, transaction history, asset flows, account activity, transaction hashes, imports/manual edits, or on-chain activity. Searches the user's CoinTracker transaction history with scoped filters and pagination (pages 1-5). Use as a drilldown tool after deciding which transaction slice is needed. Scoped filters combine with AND. For relative windows like "last 30 days", pass `relative_date_window` (e.g. {"count": 30, "unit": "day"}), resolved in the user's timezone; do not also pass `tax_year`, `from_date`, or `to_date`. For a named whole tax year, pass `tax_year` instead of dates or a window; do not broaden beyond that year if no rows match. `needs_review=true` lists transactions currently flagged for review, a live list that can differ from `get_tax_summary` review counts. Reasons are observed conditions, not diagnoses. Use `get_tax_summary` for aggregate review counts and year-level taxable income (`taxable_income_context` is row-level). `total_value` is null on unpriced rows or while cost basis is recomputing — treat as unknown, not zero. `order_by=value_desc` / `value_asc` rank by that field, unpriced rows last. It ranks by transaction value, not realized gain/loss; when available, use `search_tax_disposals` for gains/losses, disposal cost basis, or short/long-term breakdowns. `transaction_category` is applied after page selection, so a short page can still have `has_next_page=true`. Asset symbols are returned as stored and may use lookalike (Cyrillic/zero-width) characters; do not treat symbol equality as identity. Default searches respect display preferences; identifier lookups and `needs_review` bypass them. `include_category_details=true` adds per-operation `category_details`: exact category, replacement choices, fee flag, asset flows. Replacement choices are what the rules permit, not what is correct. Read-only.

search_transactions