Run a historical backtest against the engine.
Quota-counted and compute-bound. Validate the
strategy first (validate_strategy is far cheaper). On a 504 compute
timeout, do NOT retry the same request — reduce the date range, use a
coarser frequency, or simplify the strategy. On 429/503, wait for the
advertised Retry-After before retrying.
Args:
data_source: Either inline OHLCV ({"ohlcv": {dates, open, high,
low, close, volume?}} as parallel arrays, ISO-8601 dates) or a
server-side fetch ({"symbol", "start", "end", "frequency"} —
requires a paid plan).
strategy: Strategy document (indicators[] + condition_tree).
Mutually exclusive with signals.
signals: Precomputed signal series ({"dates": [...], "values":
[-1|0|1, ...]}). Mutually exclusive with strategy.
execution: Execution/cost/risk/sizing settings. Use values from
get_catalog('execution-modes'/'stop-types'/'sizing-methods');
omit for engine defaults.
benchmark: Optional benchmark data source (same shape as
data_source) — when given, the result also carries
benchmark-relative metrics (beta, alpha, information ratio,
tracking error, up/down capture) and bar-alignment info.
data_inputs: Optional custom time-series the strategy references
(name -> {dates, values}).
response_detail: 'summary' (default — headline metrics, smallest),
'stats' (every metric), 'full' (plus trades and series
downsampled to a fixed, server-controlled number of points).
include: Optional add-on blocks at any detail level: 'trades',
'equity_curve', 'monthly_returns', 'yearly_returns',
'signal_diagnostics' (which per-bar entry/exit conditions
fired, as capped fire-date lists — {"available": false, ...}
if the run has none, e.g. precomputed signals).
trades_limit: Max trades returned when trades are included.
Returns:
The shaped result at the requested detail (including
``benchmark_relative``/``alignment`` when a benchmark was given);
an oversized result is thinned and marked ``truncated_by_mcp``. If
the engine rejects the request as invalid (400/422), returns
{"accepted": false, "error": ...} so you can fix the named
field(s) and retry. Capacity, timeout, and permission failures
(e.g. 429/503/504/401/403) raise a tool error carrying explicit
recovery guidance.
