Skip to main content
Glama

Start a historical backtest

start_backtest
Idempotent

Queue a backtest of any saved strategy in the connected workspace; the run records a spot buy-and-hold of its traded market beside it. Accepts custom code and existing app strategies. Uses the app's sandbox validation, supported markets, bar sizes and date rules; a test uses up to 20,000 bars per feed, and a fitted period is stated in adjustments. Requires the exact saved revision. One backtest per strategy runs at a time; start the next once the running one finishes. Uses 10,000 simulated capital, zero fees and zero slippage. Read the report assumptions for historical runs. Returns an acceptance receipt with run ids, revision (the strategy revision to pass to start_backtest again), tested_revision (the tested code and parameters), queue (runs ahead in the shared backtest queue and an estimated wait) and poll_after_seconds, the interval before the next status check. Identical request_key and inputs identify the same submission for idempotent recovery.

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": {
      "request_key": "<request_key>",
      "strategy_id": "<strategy_id>",
      "revision": "<revision>",
      "start_date": "<start_date>"
    },
    "name": "start_backtest"
  }
}

Input Schema

NameRequiredDescriptionDefault
end_dateNo
revisionYes
start_dateYes
request_keyYesIdempotency UUID identifying one requested write and its unchanged arguments.
strategy_idYes

Output Schema

NameRequiredDescriptionDefault
queueNo
end_tsYes
run_idYes
statusYes
app_urlYes
revisionYes
start_tsYes
data_noteNo
total_barsYes
adjustmentsNo
request_keyYes
strategy_idYes
warmup_fromNo
tested_rulesNo
specificationNo
engine_versionNo
tested_revisionNo
poll_after_secondsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changed
    • addedOutput schema / properties / adjustments
      Added value: +{
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • removedOutput schema / properties / baseline_run_id
      Removed value: -{
      -  "maxLength": 128,
      -  "minLength": 1,
      -  "type": "string"
      -}
    • addedOutput schema / properties / data_note
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / engine_version
      Added value: +{
      +  "maximum": 9007199254740991,
      +  "minimum": -9007199254740991,
      +  "type": "integer"
      +}
    • addedOutput schema / properties / specification
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "conditional_fills": {
      +      "default": "live_range_touch",
      +      "enum": [
      +        "completed_bar_touch",
      +        "live_range_touch"
      +      ],
      +      "type": "string"
      +    },
      +    "conversions": {
      +      "default": [],
      +      "items": {
      +        "oneOf": [
      +          {
      +            "additionalProperties": false,
      +            "properties": {
      +              "assumption": {
      +                "maxLength": 300,
      +                "minLength": 1,
      +                "type": "string"
      +              },
      +              "currency": {
      +                "pattern": "^[A-Z][A-Z0-9]{1,15}$",
      +                "type": "string"
      +              },
      +              "kind": {
      +                "const": "fixed",
      +                "default": "fixed",
      +                "type": "string"
      +              },
      +              "rate": {
      +                "decimalBounds": {
      +                  "gt": 0,
      +                  "maxDigits": 42
      +                },
      +                "pattern": "^-?(0|[1-9][0-9]{0,41})(\\.[0-9]{1,18})?$",
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "assumption",
      +              "currency",
      +              "rate"
      +            ],
      +            "title": "FixedConversion",
      +            "type": "object"
      +          },
      +          {
      +            "additionalProperties": false,
      +            "properties": {
      +              "currency": {
      +                "pattern": "^[A-Z][A-Z0-9]{1,15}$",
      +                "type": "string"
      +              },
      +              "feed_id": {
      +                "pattern": "^[a-z][a-z0-9_]{0,63}$",
      +                "type": "string"
      +              },
      +              "inverted": {
      +                "default": false,
      +                "type": "boolean"
      +              },
      +              "kind": {
      +                "const": "feed",
      +                "default": "feed",
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "currency",
      +              "feed_id"
      +            ],
      +            "title": "FeedConversion",
      +            "type": "object"
      +          }
      +        ]
      +      },
      +      "maxItems": 16,
      +      "type": "array"
      +    },
      +    "execution_feeds": {
      +      "items": {
      +        "pattern": "^[a-z][a-z0-9_]{0,63}$",
      +        "type": "string"
      +      },
      +      "maxItems": 16,
      +      "minItems": 1,
      +      "type": "array"
      +    },
      +    "feeds": {
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "adjustment": {
      +            "default": "raw",
      +            "enum": [
      +              "raw",
      +              "split_adjusted",
      +              "total_return"
      +            ],
      +            "type": "string"
      +          },
      +          "allow_gaps": {
      +            "default": false,
      +            "type": "boolean"
      +          },
      +          "calendar": {
      +            "maxLength": 128,
      +            "minLength": 1,
      +            "type": "string"
      +          },
      +          "id": {
      +            "pattern": "^[a-z][a-z0-9_]{0,63}$",
      +            "type": "string"
      +          },
      +          "instrument": {
      +            "maxLength": 128,
      +            "minLength": 1,
      +            "type": "string"
      +          },
      +          "interval": {
      +            "maxLength": 32,
      +            "minLength": 1,
      +            "type": "string"
      +          },
      +          "lookback": {
      +            "default": 500,
      +            "maximum": 5000,
      +            "minimum": 1,
      +            "type": "integer"
      +          },
      +          "required_history": {
      +            "default": 1,
      +            "maximum": 5000,
      +            "minimum": 1,
      +            "type": "integer"
      +          }
      +        },
      +        "required": [
      +          "calendar",
      +          "id",
      +          "instrument",
      +          "interval"
      +        ],
      +        "title": "FeedSpec",
      +        "type": "object"
      +      },
      +      "maxItems": 32,
      +      "minItems": 1,
      +      "type": "array"
      +    },
      +    "fill_callback_orders": {
      +      "default": "next_trading_minute",
      +      "enum": [
      +        "next_execution_bar",
      +        "next_trading_minute"
      +      ],
      +      "type": "string"
      +    },
      +    "instruments": {
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "allow_short": {
      +            "default": false,
      +            "type": "boolean"
      +          },
      +          "asset_class": {
      +            "enum": [
      +              "crypto",
      +              "equity",
      +              "etf",
      +              "stock",
      +              "index",
      +              "commodity"
      +            ],
      +            "type": "string"
      +          },
      +          "base_currency": {
      +            "anyOf": [
      +              {
      +                "pattern": "^[A-Z][A-Z0-9]{1,15}$",
      +                "type": "string"
      +              },
      +              {
      +                "type": "null"
      +              }
      +            ],
      +            "default": null
      +          },
      +          "id": {
      +            "maxLength": 128,
      +            "minLength": 1,
      +            "type": "string"
      +          },
      +          "perpetual": {
      +            "anyOf": [
      +              {
      +                "additionalProperties": false,
      +                "properties": {
      +                  "contract": {
      +                    "const": "linear",
      +                    "type": "string"
      +                  },
      +                  "funding_interval_ms": {
      +                    "const": 3600000,
      +                    "type": "number"
      +                  },
      +                  "leverage": {
      +                    "maximum": 100,
      +                    "minimum": 1,
      +                    "type": "integer"
      +                  },
      +                  "liquidation": {
      +                    "const": "hyperliquid_isolated_v1",
      +                    "type": "string"
      +                  },
      +                  "margin_mode": {
      +                    "const": "isolated",
      +                    "type": "string"
      +                  },
      +                  "margin_tiers": {
      +                    "items": {
      +                      "additionalProperties": false,
      +                      "properties": {
      +                        "lower_bound": {
      +                          "decimalBounds": {
      +                            "ge": 0,
      +                            "maxDigits": 42
      +                          },
      +                          "pattern": "^-?(0|[1-9][0-9]{0,41})(\\.[0-9]{1,18})?$",
      +                          "type": "string"
      +                        },
      +                        "max_leverage": {
      +                          "maximum": 100,
      +                          "minimum": 1,
      +                          "type": "integer"
      +                        }
      +                      },
      +                      "required": [
      +                        "lower_bound",
      +                        "max_leverage"
      +                      ],
      +                      "title": "MarginTier",
      +                      "type": "object"
      +                    },
      +                    "maxItems": 8,
      +                    "minItems": 1,
      +                    "type": "array"
      +                  },
      +                  "min_order_notional": {
      +                    "decimalBounds": {
      +                      "gt": 0,
      +                      "maxDigits": 42
      +                    },
      +                    "default": "10",
      +                    "pattern": "^-?(0|[1-9][0-9]{0,41})(\\.[0-9]{1,18})?$",
      +                    "type": "string"
      +                  },
      +                  "price_basis": {
      +                    "const": "execution_trades",
      +                    "type": "string"
      +                  }
      +                },
      +                "required": [
      +                  "contract",
      +                  "funding_interval_ms",
      +                  "leverage",
      +                  "liquidation",
      +                  "margin_mode",
      +                  "margin_tiers",
      +                  "price_basis"
      +                ],
      +                "title": "PerpetualSpec",
      +                "type": "object"
      +              },
      +              {
      +                "type": "null"
      +              }
      +            ],
      +            "default": null
      +          },
      +          "quantity_step": {
      +            "decimalBounds": {
      +              "gt": 0,
      +              "maxDigits": 42
      +            },
      +            "pattern": "^-?(0|[1-9][0-9]{0,41})(\\.[0-9]{1,18})?$",
      +            "type": "string"
      +          },
      +          "quote_currency": {
      +            "pattern": "^[A-Z][A-Z0-9]{1,15}$",
      +            "type": "string"
      +          },
      +          "symbol": {
      +            "maxLength": 64,
      +            "minLength": 1,
      +            "type": "string"
      +          },
      +          "venue": {
      +            "maxLength": 64,
      +            "minLength": 1,
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "asset_class",
      +          "id",
      +          "quantity_step",
      +          "quote_currency",
      +          "symbol",
      +          "venue"
      +        ],
      +        "title": "InstrumentSpec",
      +        "type": "object"
      +      },
      +      "maxItems": 16,
      +      "minItems": 1,
      +      "type": "array"
      +    },
      +    "intrabar_ambiguity": {
      +      "default": "minute_detail_stop_first",
      +      "enum": [
      +        "reject",
      +        "minute_detail_stop_first"
      +      ],
      +      "type": "string"
      +    },
      +    "reporting_currency": {
      +      "default": "USD",
      +      "pattern": "^[A-Z][A-Z0-9]{1,15}$",
      +      "type": "string"
      +    },
      +    "schedules": {
      +      "default": [],
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "ambiguous_time": {
      +            "default": "first",
      +            "enum": [
      +              "first",
      +              "second"
      +            ],
      +            "type": "string"
      +          },
      +          "hour": {
      +            "maximum": 23,
      +            "minimum": 0,
      +            "type": "integer"
      +          },
      +          "id": {
      +            "pattern": "^[a-z][a-z0-9_]{0,63}$",
      +            "type": "string"
      +          },
      +          "minute": {
      +            "maximum": 59,
      +            "minimum": 0,
      +            "type": "integer"
      +          },
      +          "nonexistent_time": {
      +            "const": "skip",
      +            "default": "skip",
      +            "type": "string"
      +          },
      +          "timezone": {
      +            "maxLength": 128,
      +            "minLength": 1,
      +            "type": "string"
      +          },
      +          "weekdays": {
      +            "items": {
      +              "maximum": 6,
      +              "minimum": 0,
      +              "type": "integer"
      +            },
      +            "maxItems": 7,
      +            "minItems": 1,
      +            "type": "array"
      +          }
      +        },
      +        "required": [
      +          "hour",
      +          "id",
      +          "minute",
      +          "timezone",
      +          "weekdays"
      +        ],
      +        "title": "ScheduleSpec",
      +        "type": "object"
      +      },
      +      "maxItems": 16,
      +      "type": "array"
      +    },
      +    "schema_version": {
      +      "const": 2,
      +      "default": 2,
      +      "type": "number"
      +    }
      +  },
      +  "required": [
      +    "execution_feeds",
      +    "feeds",
      +    "instruments"
      +  ],
      +  "title": "SimulationSpec",
      +  "type": "object"
      +}
    • addedOutput schema / properties / total_bars / anyOf
      Added value: +[
      +  {
      +    "maximum": 9007199254740991,
      +    "minimum": -9007199254740991,
      +    "type": "integer"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • removedOutput schema / properties / total_bars / maximum
      Removed value: -9007199254740991
    • removedOutput schema / properties / total_bars / minimum
      Removed value: --9007199254740991
    • removedOutput schema / properties / total_bars / type
      Removed value: -"integer"
    • addedOutput schema / properties / warmup_from
      Added value: +{
      +  "type": "number"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "run_id",
      -  "baseline_run_id",
      -  "strategy_id",
      -  "revision",
      -  "start_ts",
      -  "end_ts",
      -  "total_bars",
      -  "status",
      -  "app_url",
      -  "poll_after_seconds",
      -  "request_key"
      -]New value: +[
      +  "run_id",
      +  "strategy_id",
      +  "revision",
      +  "start_ts",
      +  "end_ts",
      +  "total_bars",
      +  "status",
      +  "app_url",
      +  "poll_after_seconds",
      +  "request_key"
      +]
  2. Changed2 schema fields changed
    • addedOutput schema / properties / queue
      Added value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": false,
      +      "properties": {
      +        "estimated_wait_seconds": {
      +          "anyOf": [
      +            {
      +              "maximum": 9007199254740991,
      +              "minimum": -9007199254740991,
      +              "type": "integer"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ]
      +        },
      +        "poll_after_seconds": {
      +          "maximum": 9007199254740991,
      +          "minimum": -9007199254740991,
      +          "type": "integer"
      +        },
      +        "runs_ahead": {
      +          "maximum": 9007199254740991,
      +          "minimum": -9007199254740991,
      +          "type": "integer"
      +        }
      +      },
      +      "required": [
      +        "runs_ahead",
      +        "estimated_wait_seconds",
      +        "poll_after_seconds"
      +      ],
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ]
      +}
    • addedOutput schema / properties / tested_revision
      Added value: +{
      +  "type": "string"
      +}
  3. First observed

TDQS

A4.2/5.0
Behavior5/5

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

Annotations only declare the safety/idempotency profile; the description adds substantial operational context beyond them: 20,000-bar-per-feed cap, sandbox validation and supported market/bar/date rules, fixed 10,000 simulated capital with zero fees and slippage, throughput limits (one run per strategy), queue position and estimated wait, and poll_after_seconds for status checks. It also explains idempotent recovery via request_key, which reinforces rather than contradicts idempotentHint=true.

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

Conciseness3/5

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

Front-loaded with the purpose, which is good, but the remainder is a single dense semicolon-chained paragraph mixing constraints, economics, queue behavior and return fields. Every sentence carries information, yet the lack of grouping (constraints vs. return payload vs. idempotency) makes it harder to scan than it needs to be.

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

Completeness4/5

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

For a complex async, mutating tool this covers the essentials an agent needs: preconditions, concurrency limits, fixed simulation assumptions, and where to check status. The receipt-field enumeration is partly redundant since an output schema exists, and date-range rules are only alluded to rather than stated, keeping it from a 5.

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

Parameters3/5

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

Schema description coverage is only 20% (only request_key is documented in the schema), so the description must compensate. It does explain request_key semantics ('Identical request_key and inputs identify the same submission for idempotent recovery') and stresses that revision must be the 'exact saved revision', but strategy_id, start_date and end_date get no field-level meaning beyond a passing reference to 'date rules'. Partial compensation only.

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?

Opens with a precise verb+resource+scope: 'Queue a backtest of any saved strategy in the connected workspace', and adds a distinguishing behavior (records a spot buy-and-hold of its traded market beside it). It also states what inputs are accepted ('custom code and existing app strategies'), which separates it from create_strategy/update_strategy siblings without opening their schemas.

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

Usage Guidelines4/5

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

Gives concrete preconditions and sequencing rules: 'Requires the exact saved revision' and 'One backtest per strategy runs at a time; start the next once the running one finishes'. It also points to 'Read the report assumptions for historical runs', implying the follow-up report tool. It stops short of naming a sibling alternative or explicitly excluding cases, so it falls below the 5 bar.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources