Tool Reference

The 13 read-only tools exposed by ByteTree MCP. Each tool wraps the same data plane as the REST API; the REST cross-link on each section shows the equivalent endpoint where one exists, so you can pick the surface that fits the task.

All input schemas use Zod under the hood and validate at the server. Symbols are uppercased internally; dates are ISO YYYY-MM-DD; field projections (fields?: string[]) are honoured wherever present.

Field names like byteTrendCapr200w, trendRegimeLocal30d, trendAge200w, capr, marketCapUsd are ByteTree-proprietary — see the Concepts page for definitions before reasoning about values.

Asset discovery

list_assets

List assets from the ByteTree registry with optional filters. Returns a paginated envelope (count/total/limit/offset/data). Each row carries the full asset document — identifiers (symbol, ISIN), classification (type, status, sector, industry), region/country, currency, exchange (under metadata.exchange), market cap (mktCap in local currency, mktCapUsd in USD) — plus the latest Weekly and Daily ByteTrend CAPR scores (byteTrendCapr200w and byteTrendCapr30d) and their trend regimes. Use get_latest_metrics for the full metrics blob including the Local-variant ByteTrend scores and ~100 other fields.

REST equivalent: GET /api/assets

Response: { count, total, limit, offset, data: AssetDocument[] }

get_asset

Registry detail for a single asset: identifiers (symbol, ISIN), classification (type, status, sector, industry), region/country, currency, exchange, and market cap. Does not include metrics — use get_latest_metrics for ByteTrend scores, trend regimes, returns, and the rest of the metrics blob. The id is either a ticker symbol (uppercased internally) or a Mongo ObjectId.

REST equivalent: GET /api/assets/:id

Response: AssetDocument on success, { id, found: false } on 404.

Metrics

get_latest_metrics

The most recently computed metrics row for a symbol. Includes the four ByteTrend scores (Weekly Local byteTrendLocal200w, Weekly CAPR byteTrendCapr200w, Daily Local byteTrendLocal30d, Daily CAPR byteTrendCapr30d), the four trend regime labels, Weekly trend age (trendAge200w), drawdown, Sharpe, beta, market cap, and ~100 other fields. Returns { symbol, data: null } when no row exists or when the row is older than 7 days (the staleness window) — assets with data gaps drop out of the bulk metric surface entirely until they refresh, so a null here can mean either “never had metrics” or “last metrics older than a week, treated as stale.”

Surfaces ByteTree-proprietary signals: CAPR (Currency-Adjusted Price Relative — asset USD price ÷ MSCI World close), ByteTrend (0–5 composite score in two arcs — Weekly with 200-week/30-week MAs, Daily with 200-day/30-day MAs), and trend regimes (Leading / Emerging / Weakening / Bear / Neutral). Read the Concepts page or the bytetree://glossary resource for predicates and full definitions before reasoning about these fields — these terms are not in any LLM training set.

REST equivalent: GET /api/metrics/latest, GET /api/metrics/:symbol/latest

Response: { symbol, data: MetricsRow | null }

get_metrics_series

Time-series of computed metrics for a symbol. Returns { symbol, count, data: [{ date, …metricFields }] } with metrics merged into each row. Use fields to project a subset (e.g. ["byteTrendCapr200w", "returnUsd1M", "closeUsd"]) — without it, every metric field (~100 per row) is returned, which compounds quickly.

Defaults to a 90-day window ending today when neither from nor to is supplied — pass from (and optionally to) explicitly to widen the range, and lean on fields to keep the response under the 800 KB tool-result cap. Row cadence matches the price-data feed for the asset type: stocks have one row per trading day (no Sat/Sun/holiday rows); crypto has one row per calendar day (24/7 markets).

Forward-return fields (returnFwdUsd1D, 1W, 1M, 3M, 6M, 12M) are populated on historical rows where the forward window is fully observable — useful for signal-conditional analysis like “what was the 3M forward return on every date a stock hit byteTrendCapr200w === 5?”. The latest few rows naturally show null forward-returns whose windows extend past the last observed close.

REST equivalent: GET /api/metrics/:symbol

Response: { symbol, count, data: Array<{ date, …metricFields }> }

rank_assets

Rank active assets by a chosen metric and return the top/bottom N with their latest values. Composed over the bulk metrics map, so the universe is bounded by the 7-day metric staleness window — assets whose latest metrics row is older than seven days (e.g. data-gap symbols) drop out of rankings naturally rather than appearing with stale values. Nulls are excluded from the ranking.

The metric enum mixes ByteTree-proprietary signals (Weekly and Daily ByteTrend scores 0–5 in Local and CAPR variants, the Weekly trend age trendAge200w) with standard finance metrics; read the Concepts page for the precise predicates behind ByteTrend, CAPR, and trend regimes before interpreting the values.

REST equivalent: none — server-side ranking is MCP-only today.

Response: { metric, order, count, total, data: Array<{ symbol, value: number }> }

get_metric_distribution

Cross-sectional distribution of a single metric across the active asset universe, sampled over a date range. The analytical primitive for “describe how the present came to be” — regime tracking (“what fraction of stocks were at Weekly CAPR ByteTrend >= 4 each week over 3 years?”), cohort drift (“how has median Weekly trend age in Asia Pacific evolved?”), and event windows (“score distribution in the 90 days before vs after a major drawdown”).

Output shape branches on the metric:

• ByteTrend scores yield buckets keyed "0"–"5" with all six keys present.
• trendAge200w yields buckets keyed by lower-bound day-count ("0", "5", "30", "90", "365", "1825").
• Continuous metrics (returns, ratios, levels, market cap) yield stats only with no buckets block.

Default frequency is weekly to keep payloads sane; daily over a multi-year window will hit the server-side >5000-projected-rows guard and 400. Asset filters mirror list_assets — type / status / sector / q / grouping + group — except type=fx is rejected (no per-asset distribution surface for FX).

REST equivalent: GET /api/metrics/distribution

Response: { generatedAt, metric, frequency, count, data: Array<{ date, n, stats: { mean, median, p25, p75, p90 }, buckets?: Record<string, number> }> }

get_regime_transitions

Regime-transition event log across the active asset universe — the analytical primitive for “when did regime X fire historically and what did the world look like at that moment?”. Returns one row per detected transition with { symbol, transitionDate, fromRegime, toRegime, metricsAtTransition: {…} }.

The Weekly CAPR window (200w-CAPR) additionally carries confirmedTransitionDate (same as transitionDate for this window — included for clarity), pendingStartDate (the day the candidate streak began, typically four rows earlier in the time-sorted series), and trendAgeAtTransition (always 5 in continuous operation per the confirmation rule).

The other three windows — Weekly Local (200w-Local), Daily CAPR (30d-CAPR), Daily Local (30d-Local) — are raw-only with no confirmation machinery, so those three extra fields are omitted entirely from the response and transitionDate IS the same-day change.

regime is required when direction is "into" or "outOf"; pass direction: "any" (and omit regime) for unfiltered scans of every regime change in the window.

Asset filters mirror list_assets — type / status / sector / q / grouping + group — except type=fx is excluded (no per-asset regime surface for FX).

The server caps at 5001 transitions and 400s past that — bound queries by date range OR an asset filter (especially when direction: "any", where unbounded multi-decade scans can exceed upstream timeouts and return an empty reply rather than a clean error).

See the Concepts page for regime predicates, the Weekly CAPR confirmation state machine, and Weekly-vs-Daily distinctions.

REST equivalent: GET /api/metrics/regime-transitions

Response:

• Weekly CAPR (200w-CAPR): { symbol, window, transitionDate, confirmedTransitionDate, pendingStartDate, fromRegime, toRegime, trendAgeAtTransition, metricsAtTransition }
• Other three windows: { symbol, window, transitionDate, fromRegime, toRegime, metricsAtTransition }

Prices and FX

get_prices

Raw OHLCV price data for a symbol. Returns { symbol, count, data: [{ date, open, high, low, close, volume }] }. Adjusted close is the default (split- and dividend-adjusted). Pass raw: true for the unmodified series with split discontinuities preserved — useful for forensic checks but rarely what an LLM should default to.

Defaults to a 90-day window ending today when neither from nor to is supplied — pass from explicitly to widen, but watch the response size for multi-year queries on liquid stocks. Multi-year OHLCV on an active stock can exceed the 800 KB tool-result cap; if it does, the tool returns an error with narrowing guidance — retry with a tighter from (or chunk the range).

FX symbols return a narrower close-only row shape { date, close } since the FX store does not carry OHLV.

REST equivalent: GET /api/prices/:symbol

Response: { symbol, count, data: Array<{ date, open, high, low, close, volume }> } (or { date, close } for FX)

get_fx_rates

Historical FX rates for a currency pair (e.g. GBPUSD, EURUSD, USDUSD). Returns { symbol, count, data: [{ date, close }] } — close-only, since the FX store does not carry OHLV.

REST equivalent: GET /api/rates, GET /api/fx

Response: { symbol, count, data: Array<{ date, close }> } on success, { pair, found: false } on 404.

Universes and groups

list_grouping_configs

List the GroupingConfig documents that define how assets are grouped into dimensions for get_group_metrics. Each config carries its slug (universe/category), label, type (direct / mapped), source field, fallback strategy, enabled flag, and sort order. Universes (e.g. default, global-trends-200) partition the dimension space; categories within a universe are the dimensions (region, sector, industry, type, country).

REST equivalent: GET /api/universes

No input.

Response: { count, data: GroupingConfig[] }

get_group_metrics

Group-level computed metrics for a (universe, dimension, group) tuple — e.g. (default, region, "North America") or (global-trends-200, industry, "Technology"). Without from/to returns the most recent row only; with a date range returns the time series.

Aggregate fields include assetCount, ByteTrend averages across all four arc/variant combinations (Weekly Local avgByteTrendLocal200w, Weekly CAPR avgByteTrendCapr200w, Daily Local avgByteTrendLocal30d, Daily CAPR avgByteTrendCapr30d, plus median/pctScore equivalents), trend distribution and dominant trend, equal- and cap-weighted return aggregates over 1W/1M/3M/6M/12M, and risk metrics (avgVolatility30w, avgSharpe52w, totalMarketCapUsd, avgDrawdown52w, avgRelStrengthCapped3M/12M).

The two seeded universes are default (provider-native classifications) and global-trends-200 (ByteTree-curated region, sector + industry mappings, with type / country falling back to default). Use list_grouping_configs to discover valid universe/dimension/group combinations.

Aggregate fields use the same ByteTree-proprietary signals as the per-asset metrics; the Concepts page has predicates and definitions.

REST equivalent: GET /api/universes/:universe, GET /api/universes/:u/:category, GET /api/universes/:u/:cat/:group

Response: { count, dimension, group, data: Array<{ date, …aggregateFields }> }

Analysis

summarise_dataset

High-level overview of the ByteTree dataset. Returns asset counts by type and status, per-type price-data date envelopes (earliest, latest, total record count), an FX summary (record count, date range), and a concepts block with one-line definitions of the ByteTree-proprietary signals (CAPR, ByteTrend, Local-vs-CAPR, trend regimes).

Use as a starting tool for any prompt that needs to orient itself — the concepts block ensures the model gets the right framing before it reasons over downstream tool responses. The bytetree://glossary resource (or the Concepts page) has the full definitions.

REST equivalent: none — analysis tool, MCP-only.

No input.

Response: { <summary fields from /api/summary>, concepts: { CAPR, ByteTrend, localVsCapr, trendRegimes, glossary } }

compare_assets

Side-by-side comparison of the latest metrics for a small basket of symbols (1–10). Returns { count, fields, data: [{ symbol, found, …projectedFields }] } — every row has the same keys so the response encodes as a compact tabular form even when some symbols are missing.

The default field set is the canonical 24-field mix: all four ByteTrend scores (Weekly Local/CAPR + Daily Local/CAPR), their daily changes, all four trend regime labels, USD returns over 1W–12M, risk metrics (volatility, Sharpe, beta, drawdowns), Weekly trend age, and market cap. Override via fields for narrower comparisons.

The ByteTrend score, CAPR, and trend regime fields are ByteTree-proprietary; read the Concepts page for definitions before interpreting the values — comparing Weekly Local (byteTrendLocal200w) to Weekly CAPR (byteTrendCapr200w) for the same symbol isolates absolute vs relative leadership, which is what this tool is most useful for.

REST equivalent: none — composable over REST today, MCP exposes as a single tool.

Response: { count, fields: string[], data: Array<{ symbol, found, …projectedFields }> }