BotSpot: AI Trading, Backtests and Bots

Check backtest status

backtest_status

Read-onlyIdempotent

Fetch the latest status/stage for a backtest by id. Response includes stage plus a rich structuredContent.progress snapshot of the current heartbeat:

percent, eta, elapsed, simulationDate, portfolioValue, totalReturnPct, heartbeatElapsedSeconds
orders: array of open/recent orders from the simulation's current iteration, sanitized to the same shape as get_deployment_order_telemetry — the 7 canonical fields (timestamp, symbol, action, quantity, price, order_id, status, reason) PLUS flat option/contract metadata (asset_type, strike, expiration, option_type, order_type) surfaced from the nested asset dict when the strategy trades options/futures so callers can render e.g. "SPY 2024-01-24 465 PUT smart_limit" without parsing OSI themselves. null if the heartbeat omits orders or the payload was malformed. Handles both live-listener Order.to_dict() and backtest-heartbeat Order.to_minimal_dict() shapes.
positions: array of current holdings sanitized to the same essential-fields shape as get_deployment_position_telemetry (symbol, quantity, avg_fill_price, current_price, market_value, pnl, pnl_percent, asset_type, exchange, currency, multiplier, expiration, strike, option_type, underlying_symbol, asset). Accepts both full Position.to_dict() and compact Position.to_minimal_dict() (qty/val/pnl) shapes.
dataProvider: the provider slug the backtest is routing through (e.g. botspot_auto, ibkr, thetadata) so you can confirm routing mid-run without waiting for settings.json at completion. If you are monitoring, summarize those fields (progress + current results) instead of repeatedly polling. Finished runs also return rejectedOrderCount (null when not known yet) and errorSummary (first error line, null when none). After any slow or failed backtest, call once with includeTiming=true to see where the time went (timing.run, timing.data.sharedCache, timing.strategy) and, for failed runs, failureSummary (what failed and why, e.g. the asset, bar size and date of missing history). Numbers the run does not record are null and explained in timing.missing. For iteration counts and the slowest functions, rerun with start_backtest profile=true (profiling makes that run slower). To measure cold data speed, rerun with start_backtest cache="off".

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "backtestId": "<backtestId>"
    },
    "name": "backtest_status"
  }
}

Input Schema

Name	Required	Description	Default
`backtestId`	Yes	Actual backtest run UUID. Use the id returned by list_backtests or an explicit user-provided backtest id. Do not use a strategy id, aiStrategyId, revisionId, browser URL revisionId, conversation id, or a placeholder such as <unknown>.
`includeTiming`	No	Set true after a slow or failed backtest to get `timing`: where the run spent its time (waiting to start, startup, simulation seconds, simulated days per minute, end-of-run reports, upload), shared market-data cache hits, misses and bytes, and, for runs started with start_backtest profile=true, iteration counts and the slowest functions. Numbers a run does not record are null and listed in `timing.missing` with the reason. Reads a few small result files, so leave it off while polling.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 12, 2026

addedInput schema / properties / includeTiming

Added value: +{
+  "description": "Set true after a slow or failed backtest to get `timing`: where the run spent its time (waiting to start, startup, simulation seconds, simulated days per minute, end-of-run reports, upload), shared market-data cache hits, misses and bytes, and, for runs started with start_backtest profile=true, iteration counts and the slowest functions. Numbers a run does not record are null and listed in `timing.missing` with the reason. Reads a few small result files, so leave it off while polling.",
+  "type": "boolean"
+}

First observedOct 23, 2026

TDQS

A4.7/5.0

Behavior5/5

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

It goes far beyond annotations by describing the precise structure of the return data, including fields like `percent`, `eta`, `elapsed`, and complex nested arrays for `orders` and `positions`. This replaces the lack of an output schema with highly specific behavioral documentation.

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

Conciseness2/5

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

The description is extremely verbose, resembling a complete API reference rather than a concise AI guidance block. While the detail is necessary for this complex tool, the length makes it poor from a structural standpoint.

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?

Given the complexity of the return data, the description is exceptionally complete. It specifies the formats of nested data structures, enumerates provider slugs, and advises on profiling for specific performance metrics.

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?

The description provides crucial usage constraints for the `backtestId` parameter (e.g., 'Do not use a strategy id, aiStrategyId...') and elaborates extensively on what the `includeTiming` flag reveals, adding significant context beyond the schema definition.

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?

The tool clearly states its purpose is to 'fetch the latest status/stage for a backtest by id,' distinguishing it from other sibling tools like those fetching logs or charts.

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?

The description provides specific operational advice, such as advising users to summarize fields instead of repeatedly polling, and specifying when to use `includeTiming=true` (slow or failed backtests).

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

All BotSpot: AI Trading, Backtests and Bots 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.