MarketHeist Backtest

decompose_factors

Read-onlyIdempotent

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`label`	No	Optional display name for a custom `assets` portfolio. Default "Custom portfolio".
`assets`	No	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`	No	Yahoo Finance ticker to decompose, e.g. AAPL, QQQ, TLT, ARKK. Omit when using `template` or `strategy`.
`factors`	No	Factor ids to include. Default: MKT, SMB, HML, TERM, CREDIT (long history back to ~2001). All available: MKT, SMB, HML, MOM, QMJ, LOWVOL, TERM, CREDIT. The smart-beta trio (MOM, QMJ, LOWVOL) only has history from ~2011-2013, which shortens the analyzable window — factors without enough overlap are dropped and reported.
`overlay`	No	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`	No	Canonical rule-based strategy whose returns to decompose, e.g. dual-momentum-gem. One of: dual-momentum-gem, tsmom-sp500, faber-trend-timing, sector-momentum-rotation, risk-parity-inverse-vol, gtaa-aggressive, adaptive-asset-allocation. Precomputed; default factors.
`template`	No	Built-in model portfolio whose returns to decompose, e.g. all-weather. 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. Precomputed; default factors.
`frequency`	No	Return frequency for the regression of a `target` ticker. Monthly (default) is standard for factor analysis. Ignored for `template` / `strategy` (always monthly).	1mo
`rebalance`	No	Rebalancing cadence for custom portfolios (templates use their own).	yearly

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedOct 18, 2026

addedInput schema / properties / assets

Added value: +{
+  "description": "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.",
+  "items": {
+    "properties": {
+      "sleeve": {
+        "additionalProperties": true,
+        "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).",
+        "type": "object"
+      },
+      "ticker": {
+        "description": "Yahoo Finance ticker, e.g. VTI, BND, GLD. Omit when `sleeve` is given.",
+        "type": "string"
+      },
+      "weight": {
+        "description": "Target weight in percent.",
+        "type": "number"
+      }
+    },
+    "required": [
+      "weight"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

addedInput schema / properties / label

Added value: +{
+  "description": "Optional display name for a custom `assets` portfolio. Default \"Custom portfolio\".",
+  "type": "string"
+}

addedInput schema / properties / overlay

Added value: +{
+  "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).",
+  "properties": {
+    "kind": {
+      "enum": [
+        "trend-filter"
+      ],
+      "type": "string"
+    },
+    "months": {
+      "description": "Moving-average window in months (≥ 2, e.g. 10).",
+      "type": "number"
+    }
+  },
+  "required": [
+    "kind",
+    "months"
+  ],
+  "type": "object"
+}

addedInput schema / properties / rebalance

Added value: +{
+  "default": "yearly",
+  "description": "Rebalancing cadence for custom portfolios (templates use their own).",
+  "enum": [
+    "none",
+    "monthly",
+    "quarterly",
+    "yearly"
+  ],
+  "type": "string"
+}

Changed5 schema fields changedOct 18, 2026

changedInput schema / properties / frequency / description

Previous value: -"Return frequency for the regression. Monthly (default) is standard for factor analysis."New value: +"Return frequency for the regression of a `target` ticker. Monthly (default) is standard for factor analysis. Ignored for `template` / `strategy` (always monthly)."

addedInput schema / properties / strategy

Added value: +{
+  "description": "Canonical rule-based strategy whose returns to decompose, e.g. dual-momentum-gem. One of: dual-momentum-gem, tsmom-sp500, faber-trend-timing, sector-momentum-rotation, risk-parity-inverse-vol, gtaa-aggressive, adaptive-asset-allocation. Precomputed; default factors.",
+  "enum": [
+    "dual-momentum-gem",
+    "tsmom-sp500",
+    "faber-trend-timing",
+    "sector-momentum-rotation",
+    "risk-parity-inverse-vol",
+    "gtaa-aggressive",
+    "adaptive-asset-allocation"
+  ],
+  "type": "string"
+}

changedInput schema / properties / target / description

Previous value: -"Yahoo Finance ticker to decompose, e.g. AAPL, QQQ, TLT, ARKK."New value: +"Yahoo Finance ticker to decompose, e.g. AAPL, QQQ, TLT, ARKK. Omit when using `template` or `strategy`."

addedInput schema / properties / template

Added value: +{
+  "description": "Built-in model portfolio whose returns to decompose, e.g. all-weather. 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. Precomputed; default factors.",
+  "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"
+}

removedInput schema / required
```
Removed value: -[
-  "target"
-]
```

First observedOct 14, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, yet the description still adds substantial method context: OLS regression on real price history via long-short ETF proxies, 'measured exposure, not a forecast', precomputed monthly data for portfolios, and the drop-and-report behavior when factors lack overlapping history.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose then when-to-use then output then input constraints, so it reads in the right order and every sentence carries information. It is nonetheless a single dense paragraph of roughly 250 words, and the input-mode constraints would scan faster as a short list.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description carries the return-value burden and does so fully: betas, t-stats, additive variance decomposition summing to R², annualized alpha, idiosyncratic vs total volatility, and per-factor holdings for portfolios. Nothing an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds constraints the schema does not encode: exactly one of target/template/strategy/assets, that portfolios ignore `frequency` and `factors` and always use the five default factors monthly, and the short-history caveat on the smart-beta trio. This is genuine cross-parameter meaning beyond the field-level docs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb+resource (decompose a ticker/ETF/portfolio's returns into named factor exposures plus idiosyncratic residual) and enumerates the exact factor set. It also explicitly contrasts itself with the sibling analyze_portfolio, so an agent can route without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an unusually rich when-to-use list framed as real user questions (why two assets move together, growth vs value tilt, how much is just beta, is there real alpha) and names the alternative tool for performance numbers. The when-not condition for each input mode is also stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All MarketHeist Backtest tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?