analyze_portfolio

Analyze an asset-allocation ('lazy') portfolio and get long-run performance computed from real monthly price history (proxy-extended for decades of data), not estimated: CAGR, max drawdown, volatility, Sharpe, Sortino, Ulcer index, $10,000 growth, the number of independent bets (holdings whose returns average a correlation of 0.5 or more count as one group, then the effective count of groups by risk share), the top risk driver, trailing Sharpe, and a `validity` block (provenance, caveats, a reproduce-me hash) plus a `cite` block with the marketheist.io pages that show the same numbers. Use it for 'how did 60/40 / All Weather / Golden Butterfly perform' or for a custom mix. Provide exactly one of: a `template` id (19 model portfolios, listed in list_portfolios), a `strategy` id (7 rule-based canonical strategies, e.g. dual-momentum-gem) or a custom `assets` allocation (plain tickers and nested portfolios, rotations, strategies as holdings via `sleeve`). Template and strategy ids are answered from precomputed data through the stated month (instant, not rate-limited); custom assets and an `overlay` are computed live from market data. For seasonality and calendar years use portfolio_returns; for drawdown episodes and diversification use portfolio_risk; to compare portfolios use compare_portfolios. Read-only; surface the caveats when reporting.

read-only

Argument	Type	Description
label	string	Optional display name for a custom `assets` portfolio. Default "Custom portfolio".
assets	array	Custom allocation (omit if using `template` or `strategy`). Weights are percentages summing to ~100. A holding is a plain ticker OR a strategy node via `sleeve`.
overlay	object	Optional portfolio-level trend-filter overlay applied to the WHOLE book: hold the entire portfolio only while its own level is above its N-month moving average, otherwise cash. Composition is monthly (a 10-month filter ≈ the classic 200-day one).
strategy	string	Canonical rule-based strategy to analyze. One of: dual-momentum-gem, tsmom-sp500, faber-trend-timing, sector-momentum-rotation, risk-parity-inverse-vol, gtaa-aggressive, adaptive-asset-allocation. Answered from precomputed data. Omit when using `template` or `assets`.
template	string	Built-in model portfolio to analyze. One of: golden-butterfly, all-weather, permanent, dragon, faber-ivy, faber-gaa, bogleheads-3fund, wealthfront-classic, betterment-core, classic-60-40, classic-40-60, swensen, ferri-core-four, couch-potato, coffeehouse, no-brainer, larry, buffett-90-10, total-sp500. Omit to analyze a custom `assets` allocation instead.
rebalance	string	Rebalancing cadence for custom portfolios (templates use their own).

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "label": {
      "type": "string",
      "description": "Optional display name for a custom `assets` portfolio. Default \"Custom portfolio\"."
    },
    "assets": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "weight"
        ],
        "properties": {
          "sleeve": {
            "type": "object",
            "description": "Advanced: a strategy node instead of a plain ticker — the app's SleeveRef, resolved server-side. Supported: a rotation/selection (`{source:'selection', config:{universe:[{ticker}], signal:{kind:'indicator', indicatorId, params} | {kind:'trailing-return', lookbackMonths, skipMonths (>= 1; the ranking for a month only sees data through the previous month-end)}, topK, weighting, rebalance}, label}`), a strategy-over-node (`{source:'strategy-over', child:{ticker}, config:<BacktestConfig>, label}`), a saved strategy preset (`{source:'backtest-live', ticker, frequency, config, presetId, label}`), a curated public-library strategy (`{source:'backtest-public', strategyId, label}`), a published backtest share (`{source:'backtest-share', shareId, label}`), a gallery template (`{source:'portfolio-public', templateId, label}`), or a nested portfolio (`{source:'portfolio-mine', portfolioId, config, label}`). Strategies with a config get a node-level overfit check (a share carries only its frozen curve, so no overfit).",
            "additionalProperties": true
          },
          "ticker": {
            "type": "string",
            "description": "Yahoo Finance ticker, e.g. VTI, BND, GLD. Omit when `sleeve` is given."
          },
          "weight": {
            "type": "number",
            "description": "Target weight in percent."
          }
        }
      },
      "description": "Custom allocation (omit if using `template` or `strategy`). Weights are percentages summing to ~100. A holding is a plain ticker OR a strategy node via `sleeve`."
    },
    "overlay": {
      "type": "object",
      "required": [
        "kind",
        "months"
      ],
      "properties": {
        "kind": {
          "enum": [
            "trend-filter"
          ],
          "type": "string"
        },
        "months": {
          "type": "number",
          "description": "Moving-average window in months (≥ 2, e.g. 10)."
        }
      },
      "description": "Optional portfolio-level trend-filter overlay applied to the WHOLE book: hold the entire portfolio only while its own level is above its N-month moving average, otherwise cash. Composition is monthly (a 10-month filter ≈ the classic 200-day one)."
    },
    "strategy": {
      "enum": [
        "dual-momentum-gem",
        "tsmom-sp500",
        "faber-trend-timing",
        "sector-momentum-rotation",
        "risk-parity-inverse-vol",
        "gtaa-aggressive",
        "adaptive-asset-allocation"
      ],
      "type": "string",
      "description": "Canonical rule-based strategy to analyze. One of: dual-momentum-gem, tsmom-sp500, faber-trend-timing, sector-momentum-rotation, risk-parity-inverse-vol, gtaa-aggressive, adaptive-asset-allocation. Answered from precomputed data. Omit when using `template` or `assets`."
    },
    "template": {
      "enum": [
        "golden-butterfly",
        "all-weather",
        "permanent",
        "dragon",
        "faber-ivy",
        "faber-gaa",
        "bogleheads-3fund",
        "wealthfront-classic",
        "betterment-core",
        "classic-60-40",
        "classic-40-60",
        "swensen",
        "ferri-core-four",
        "couch-potato",
        "coffeehouse",
        "no-brainer",
        "larry",
        "buffett-90-10",
        "total-sp500"
      ],
      "type": "string",
      "description": "Built-in model portfolio to analyze. One of: golden-butterfly, all-weather, permanent, dragon, faber-ivy, faber-gaa, bogleheads-3fund, wealthfront-classic, betterment-core, classic-60-40, classic-40-60, swensen, ferri-core-four, couch-potato, coffeehouse, no-brainer, larry, buffett-90-10, total-sp500. Omit to analyze a custom `assets` allocation instead."
    },
    "rebalance": {
      "enum": [
        "none",
        "monthly",
        "quarterly",
        "yearly"
      ],
      "type": "string",
      "default": "yearly",
      "description": "Rebalancing cadence for custom portfolios (templates use their own)."
    }
  }
}

compare_portfolios

Compare 2 to 4 portfolios (built-in model portfolios, canonical strategies or your own allocations) side by side over their COMMON window, which is the only fair comparison: two pages' headline numbers usually cover different periods (a portfolio holding gold starts in 2004, the Ivy portfolio in 1996). Returns CAGR, volatility, max drawdown, Sharpe, Sortino, Ulcer index, best/worst year and longest time underwater on the aligned months, each portfolio's own full-window figures (labelled with their start), the pairwise correlation of their monthly returns and a calendar-year table. Use it for 'All Weather vs Golden Butterfly vs 60/40', 'which of these held up better', 'my portfolio vs 60/40'. Each item in `portfolios` has exactly one of `template` or `strategy` (ids from list_portfolios) or `assets` (your own allocation, including nested portfolios, rotations and strategies as holdings, with optional `rebalance` and `overlay`), plus an optional `label`. Ids are precomputed from the monthly refresh; `assets` entries are computed live (at most 2 custom entries and 24 distinct tickers per call). Read-only. For one portfolio's detail use analyze_portfolio, portfolio_returns or portfolio_risk.

read-only

Argument	Type	Description
years	integer	Calendar-year rows to include (most recent N years of the common window; 0 = none). Default 10.
portfolios*	array	2 to 4 portfolios to compare, e.g. [{"template":"all-weather"},{"template":"golden-butterfly"},{"template":"classic-60-40","label":"60/40"}].

Input schema (JSON)

{
  "type": "object",
  "required": [
    "portfolios"
  ],
  "properties": {
    "years": {
      "type": "integer",
      "default": 10,
      "maximum": 30,
      "minimum": 0,
      "description": "Calendar-year rows to include (most recent N years of the common window; 0 = none). Default 10."
    },
    "portfolios": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "description": "Optional display name for this column."
          },
          "assets": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "weight"
              ],
              "properties": {
                "sleeve": {
                  "type": "object",
                  "description": "Advanced: a strategy node instead of a plain ticker — the app's SleeveRef, resolved server-side. Supported: a rotation/selection (`{source:'selection', config:{universe:[{ticker}], signal:{kind:'indicator', indicatorId, params} | {kind:'trailing-return', lookbackMonths, skipMonths (>= 1; the ranking for a month only sees data through the previous month-end)}, topK, weighting, rebalance}, label}`), a strategy-over-node (`{source:'strategy-over', child:{ticker}, config:<BacktestConfig>, label}`), a saved strategy preset (`{source:'backtest-live', ticker, frequency, config, presetId, label}`), a curated public-library strategy (`{source:'backtest-public', strategyId, label}`), a published backtest share (`{source:'backtest-share', shareId, label}`), a gallery template (`{source:'portfolio-public', templateId, label}`), or a nested portfolio (`{source:'portfolio-mine', portfolioId, config, label}`). Strategies with a config get a node-level overfit check (a share carries only its frozen curve, so no overfit).",
                  "additionalProperties": true
                },
                "ticker": {
                  "type": "string",
                  "description": "Yahoo Finance ticker, e.g. VTI, BND, GLD. Omit when `sleeve` is given."
                },
                "weight": {
                  "type": "number",
                  "description": "Target weight in percent."
                }
              }
            },
            "description": "Your own allocation instead of an id, computed live. Same format as analyze_portfolio's `assets` (plain tickers, or nested portfolios, rotations and strategies via `sleeve`)."
          },
          "overlay": {
            "type": "object",
            "required": [
              "kind",
              "months"
            ],
            "properties": {
              "kind": {
                "enum": [
                  "trend-filter"
                ],
                "type": "string"
              },
              "months": {
                "type": "number",
                "description": "Moving-average window in months (≥ 2, e.g. 10)."
              }
            },
            "description": "Optional portfolio-level trend-filter overlay applied to the WHOLE book: hold the entire portfolio only while its own level is above its N-month moving average, otherwise cash. Composition is monthly (a 10-month filter ≈ the classic 200-day one)."
          },
          "strategy": {
            "type": "string",
            "description": "Canonical strategy id (list_portfolios shows all 7)."
          },
          "template": {
            "type": "string",
            "description": "Built-in model portfolio id (list_portfolios shows all 19)."
          },
          "rebalance": {
            "enum": [
              "none",
              "monthly",
              "quarterly",
              "yearly"
            ],
            "type": "string",
            "default": "yearly",
            "description": "Rebalancing cadence for custom portfolios (templates use their own)."
          }
        }
      },
      "maxItems": 4,
      "minItems": 2,
      "description": "2 to 4 portfolios to compare, e.g. [{\"template\":\"all-weather\"},{\"template\":\"golden-butterfly\"},{\"template\":\"classic-60-40\",\"label\":\"60/40\"}]."
    }
  }
}

decompose_factors

Explain WHAT DRIVES the returns of a ticker, ETF or built-in portfolio by decomposing them into common factor exposures (market, size, value, momentum, quality, low-volatility, duration, credit) plus an idiosyncratic residual. Use this when the user asks why two assets move together, what a fund is really exposed to, whether a stock is a growth or value tilt, how much of a return is just market beta, whether it has real alpha, or what is driving a portfolio's returns. Returns betas (loadings), t-stats, an additive variance decomposition (shares sum to R²), annualized alpha, idiosyncratic vs total volatility, and for a portfolio the holdings that drive each factor. Computed by OLS regression on real price history via tradeable ETF proxies (long-short factor spreads): measured exposure, not a forecast. Provide exactly one of `target` (a ticker, computed live), `template` (a built-in model portfolio), `strategy` (a canonical strategy) or `assets` (your own allocation, including nested portfolios, rotations and strategies as holdings, computed live); portfolio ids are answered from precomputed monthly data through the stated month. Portfolios (ids and `assets`) use the five default factors (market, size, value, duration, credit), are monthly and ignore `frequency` and `factors`. For performance numbers use analyze_portfolio. Read-only.

read-only

Argument	Type	Description
label	string	Optional display name for a custom `assets` portfolio. Default "Custom portfolio".
assets	array	Your own allocation instead of an id, computed live (monthly, default factors; the answer also lists the holdings behind each factor). Same format as analyze_portfolio: plain tickers and nested portfolios, rotations or strategies via `sleeve`. Weights in percent, summing to ~100.
target	string

find_guides

Search MarketHeist's 90 published research pages and get the page's own verdict and numbers, with its URL to cite: 18 strategy guides (60/40, All Weather, Golden Butterfly, DCA vs lump sum, ...), 26 fund-history pages (how far back an ETF can be tested), 18 trend-filter pages (what a 10-month trend filter did to each portfolio), 16 risk breakdowns (share of risk vs share of money) and 12 rule-robustness pages (does the 200-day average or the golden cross survive other settings, costs and held-out years). Each result returns the title, current verdict, 3-7 headline numbers with the data month, and the last change-log entries. Use it to give a sourced, dated answer to 'does the 200-day average work on SPY', 'would a trend filter have helped All Weather in 2022', 'how far back does VXUS go'. `query` is free words, a ticker or a portfolio name; `slug` returns one page in full (e.g. 'risk/classic-60-40', 'robustness/sma-200-spy'). Read-only and precomputed from the monthly refresh. For live numbers on your own allocation use analyze_portfolio or run_backtest.

read-only

Argument	Type	Description
set	string	Restrict to one page set: strategies, history, trend, risk or robustness. Default any.
slug	string	Exact page as '<set>/<id>', e.g. 'risk/classic-60-40' or 'robustness/sma-200-spy'. Returns that page in full (every number, labels, change log); `query` is ignored.
limit	integer	Maximum results for a search (1-10). Default 5.
query	string	Words, a ticker or a portfolio name, e.g. '200-day SPY', 'all weather trend', 'VXUS', 'golden cross'.

fund_history

Tell how far back a fund can be tested on MarketHeist once its history is extended with older substitute funds: the proxy chain (e.g. VXUS <- VGTSX), the extended start month, the ETF's own first month and, for the 26 funds with a history page, how closely each stand-in tracked the ETF while both existed (grade close / approximate / stand-in, worst tracking error), the extended-history vs ETF-only CAGR and how many S&P 500 declines the extension adds. Use it for 'can I backtest VXUS to 2000', 'how reliable is the pre-2011 data for BND', before quoting any long-run number for a fund. One `ticker` per call (e.g. VXUS, VTI, TLT, GLD). Read-only and static: no market-data fetch. A ticker with no proxy chain starts at its own inception. For returns of the fund use portfolio_returns; for the rules behind a portfolio's start date use analyze_portfolio.

read-only

Argument	Type	Description
ticker*	string	Fund or ETF ticker, e.g. VXUS, VTI, BND, TLT, GLD, DBMF. Case-insensitive; one ticker per call.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "ticker"
  ],
  "properties": {
    "ticker": {
      "type": "string",
      "description": "Fund or ETF ticker, e.g. VXUS, VTI, BND, TLT, GLD, DBMF. Case-insensitive; one ticker per call."
    }
  }
}

list_indicators

List the built-in technical indicators available for backtesting (RSI, moving-average crossovers, ADX, Bollinger, CCI, Stochastic, and more) with their IDs, parameters with defaults, and each indicator's default long rule. Call this to answer what strategies or indicators can be tested, or before run_backtest when unsure which indicator_id or parameters to use. Takes no arguments. Read-only and static (no market data is fetched, never rate-limited by the live budget). To find portfolios and strategies instead, use list_portfolios.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "properties": {}
}

list_portfolios

List every portfolio and strategy the other tools accept by id, with a one-line description, holdings, headline CAGR / max drawdown / Sharpe with the start month and the data month, and the marketheist.io page and guide URLs. Three kinds: `template` (19 buy-and-hold model portfolios such as classic-60-40, all-weather, golden-butterfly, permanent; used as `template` in analyze_portfolio, portfolio_returns, portfolio_risk, compare_portfolios, decompose_factors), `strategy` (7 rule-based canonical strategies such as dual-momentum-gem and faber-trend-timing; used as `strategy`), and `library_strategy` (19 curated single-asset backtest strategies, usable as holdings via {source:'backtest-public', strategyId} in analyze_portfolio). Call this first when you do not know an id, to avoid guessing. `query` filters by name, id or a holding ticker (e.g. 'gold', 'TLT'). Read-only and precomputed (data through the stated month); the numbers are full-window headline figures over each entry's own start, so use compare_portfolios for a like-for-like comparison.

read-only

Argument	Type	Description
kind	string	Which list: template (model portfolios), strategy (canonical rule-based strategies), library_strategy (curated backtest strategies) or all. Default all.
query	string	Optional filter on name, id, description or a holding ticker, e.g. 'gold', 'momentum', 'TLT'.

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "kind": {
      "enum": [
        "all",
        "template",
        "strategy",
        "library_strategy"
      ],
      "type": "string",
      "default": "all",
      "description": "Which list: template (model portfolios), strategy (canonical rule-based strategies), library_strategy (curated backtest strategies) or all. Default all."
    },
    "query": {
      "type": "string",
      "description": "Optional filter on name, id, description or a holding ticker, e.g. 'gold', 'momentum', 'TLT'."
    }
  }
}

portfolio_returns

Look up how a portfolio, strategy or fund actually returned: seasonality by calendar month (average return, share of positive months, number of years and a t-statistic so a thin 'September effect' is not presented as a law), calendar-year returns with partial years labelled (optionally next to the S&P 500), trailing 1/3/5/10/20/30-year returns, and the best and worst year and month. Use it for 'is September bad for 60/40', 'what did All Weather return in 2022', 'how has SPY done over 10 years', 'what did my own portfolio return each year'. Pass exactly one of `template` (e.g. all-weather, classic-60-40), `strategy` (e.g. dual-momentum-gem), `ticker` (any Yahoo ticker) or `assets` (your own allocation, including nested portfolios, rotations and strategies as holdings via `sleeve`, with optional `rebalance` and `overlay`); list_portfolios shows every valid id. Built-in ids and the funds with a history page are precomputed from the monthly refresh (instant); other tickers and `assets` are computed live from market data (proxy-extended monthly total returns). Read-only; every answer says which month the data runs through. For risk and drawdowns use portfolio_risk; to compare portfolios use compare_portfolios.

read-only

Argument	Type	Description
label	string	Optional display name for a custom `assets` portfolio. Default "Custom portfolio".
years	integer	Limit the calendar-year table to the most recent N years (e.g. 10). Default: all years.
assets	array	Your own allocation instead of an id, computed live (monthly composition, proxy-extended). Same format as analyze_portfolio: plain tickers and nested portfolios, rotations or strategies via `sleeve`. Weights in percent, summing to ~100.

portfolio_risk

Answer both 'how bad did it get' and 'is it really diversified' for a built-in model portfolio, a canonical strategy or your own portfolio. Drawdowns: the deepest peak-to-trough episodes with months to trough and recovery, Ulcer index, longest time underwater, monthly VaR/CVaR 95, worst month and year, and returns in 2008, 2020 and 2022. Diversification: each holding's share of the risk next to its share of the money (60/40 is about 60% of the money and 93% of the risk), the number of independent bets over the full window, the last 10 years and the 36 months to Feb 2009 and Dec 2022, co-movement groups, near-duplicate pairs and the equal-risk weights. Correlations: the holdings' correlation matrix. Pass exactly one of `template` (e.g. classic-60-40, all-weather), `strategy` (e.g. faber-trend-timing) or `assets` (your own allocation, including nested portfolios, rotations and strategies as holdings via `sleeve`, with optional `rebalance` and `overlay`); list_portfolios shows valid ids. `sections` limits the output. Ids are precomputed from the monthly refresh (instant); `assets` are computed live, with independent bets over the full window (and the last 10 years for plain tickers); the 2008 and 2022 windows are computed for built-in portfolios only. Read-only. For headline CAGR/Sharpe use analyze_portfolio; for calendar returns use portfolio_returns.

read-only

Argument	Type	Description
label	string	Optional display name for a custom `assets` portfolio. Default "Custom portfolio".
assets	array	Your own allocation instead of an id, computed live (drawdowns, risk share, bets and correlations of your own mix). Same format as analyze_portfolio: plain tickers and nested portfolios, rotations or strategies via `sleeve`. Weights in percent, summing to ~100.
overlay	object

run_backtest

Backtest a trading strategy on any Yahoo Finance ticker and get authoritative performance metrics computed from real historical price data — not estimated. Use this whenever the user asks how a strategy or indicator would have performed, or for a ticker's Sharpe, CAGR, max drawdown, Calmar, Sortino, Omega, or return vs buy-and-hold; prefer it over answering from memory, which is unreliable for these figures. Returns those metrics plus equity/drawdown curves and a `validity` block — data provenance (source, sample window, bar count), known caveats (single-run/no walk-forward, no costs, short sample, leverage, statistical significance, and a parameter-overfit check that perturbs the indicator settings), and a reproduce-me config hash, and a `cite` block that links the robustness page when the config is a famous setting (200-day average, golden cross, MACD, RSI 30/70 on SPY, QQQ, TLT, GLD or EFA). Surface the caveats when reporting results. Always pass execution_delay=1 to avoid lookahead bias. Call list_indicators first if unsure which indicator_id to use. Single asset only: for allocations use analyze_portfolio. Read-only; live market data, so heavy callers can hit the daily live-data limit.

read-only

Argument	Type	Description
ticker*	string	Yahoo Finance ticker symbol (e.g. AAPL, ^NDX, BTC-USD, SPY).
lookback	integer	Rolling window for position_rule_type=percentile.
direction	string	Long when indicator is above (or below) threshold/MA/percentile.
frequency	string	Bar frequency. Default: 1wk.

MarketHeist Backtest

Try it

analyze_portfolio Read-only

MarketHeist Backtest

Try it

analyze_portfolio Read-only

Tools (10)