Skip to main content
Glama

Backtest a strategy

run_backtest

Backtests a trading rule on this server's price history: one backtesting.py Strategy class, one symbol, one bar size, in a study. Use it to test, backtest or evaluate a trading rule or strategy. Returns summary figures (return, drawdown, Sharpe, win rate, trades, a grade, whether it beat buy-and-hold) and the run's trades (when each entered and left, which exit ended it, its side, win or loss), never prices or bars; a figure may be withheld, with the reason. Waits up to 90 s, then answers status "running" with a run_id for get_result.

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": {
      "study_id": "<study_id>",
      "code": "<code>",
      "symbol": "<symbol>",
      "timeframe": "<timeframe>"
    },
    "name": "run_backtest"
  }
}

Input Schema

NameRequiredDescriptionDefault
codeYesOne backtesting.py Strategy class (describe_data has the rules).
costsNoThe costs: two fractions of the trade value, or a list of costs each in its own unit.
labelNoA short text shown with the run.
symbolYesOne ticker ("QQQ", "BTCUSD", "EURUSD").
windowNoDates ({from, to}; `to` may be "latest") or the last N days, months or years ({last: {n, unit}}). Left out: the standard history, the newest bars counted back from the newest bar, cut at the start of the hold-out.
study_idYesThe id create_study returned.
timeframeYes
account_usdNoThe starting account, in US dollars.
stated_rulesNoRules the trades are checked against, one per kind.

Output Schema

NameRequiredDescriptionDefault
nextNo
basisNo
gradeNo
linesNo
marketNo
reasonNo
run_idNo
statusYes
windowNo
messageNo
metricsNo
noticesNo
versionNo
headlineNo
held_outNo
settingsNo
study_idNo
warningsNo
retryableNo
cost_tableNoEvery cost the run charged: each component (commission, slippage, spread) with its amount, unit and basis, what it comes to per round trip, when it is taken, and whether it is yours (caller) or the market's default; the round trip summed by unit (pips on a currency pair, the costs stated in pips). Costs you send replace the market's defaults side by side: a commission replaces the default commission, a slippage or a spread replaces the default slippage, a side you leave out is charged at the market's default, and nothing is added on top.
disclaimerNoThe hypothetical-performance line, on a result (a run, or a study's runs): the same text the app shows with every result.
look_aheadNo
trade_listNoThe run's trades in the order they were made, a page at a time: when each entered and left (a day on daily bars; a time on the `clock` on shorter ones; "open at the end" for a trade still open when the data ended), its side, whether it won or lost after costs, and which exit ended it (a word: stop, exit rule, target, time limit…). No prices, levels, sizes or returns.
buy_and_holdNo
replayed_fromNo
grade_withheldNo
runs_left_todayNo
hold_out_estimateNo
poll_after_secondsNo
stated_rule_breaksNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • changedInput schema / properties / costs / oneOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "commission": {
      -        "description": "A fraction of the trade value at entry (0.0005 is 0.05%), charged once per round trip.",
      -        "maximum": 0.05,
      -        "minimum": 0,
      -        "type": "number"
      -      },
      -      "slippage": {
      -        "description": "A fraction of the trade value per fill (entry and exit).",
      -        "maximum": 0.05,
      -        "minimum": 0,
      -        "type": "number"
      -      }
      -    },
      -    "required": [],
      -    "type": "object"
      -  },
      -  {
      -    "items": {
      -      "additionalProperties": false,
      -      "properties": {
      -        "amount": {
      -          "description": "The figure in `unit` (0.005 usd_per_share is half a cent a share; 0.1 percent is 0.1%).",
      -          "minimum": 0,
      -          "type": "number"
      -        },
      -        "basis": {
      -          "description": "per_side: on each fill; round_trip: once for the entry and exit together.",
      -          "enum": [
      -            "per_side",
      -            "round_trip"
      -          ],
      -          "type": "string"
      -        },
      -        "side": {
      -          "enum": [
      -            "commission",
      -            "slippage",
      -            "spread"
      -          ],
      -          "type": "string"
      -        },
      -        "unit": {
      -          "description": "usd_per_share on stocks and ETFs; usd_per_ounce on spot gold and silver; pips on currency pairs; percent, bps and usd_per_order (a flat fee per order, such as a broker's fee per order or per lot) on any market.",
      -          "enum": [
      -            "percent",
      -            "bps",
      -            "usd_per_share",
      -            "usd_per_ounce",
      -            "pips",
      -            "usd_per_order"
      -          ],
      -          "type": "string"
      -        }
      -      },
      -      "required": [
      -        "side",
      -        "amount",
      -        "unit",
      -        "basis"
      -      ],
      -      "type": "object"
      -    },
      -    "maxItems": 6,
      -    "minItems": 1,
      -    "type": "array"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "commission": {
      +        "description": "A fraction of the trade value at entry (0.0005 is 0.05%), charged once per round trip.",
      +        "maximum": 0.05,
      +        "minimum": 0,
      +        "type": "number"
      +      },
      +      "slippage": {
      +        "description": "A fraction of the trade value per fill (entry and exit).",
      +        "maximum": 0.05,
      +        "minimum": 0,
      +        "type": "number"
      +      }
      +    },
      +    "required": [],
      +    "type": "object"
      +  },
      +  {
      +    "items": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "amount": {
      +          "description": "The figure in `unit` (0.005 usd_per_share is half a cent a share; 0.1 percent is 0.1%).",
      +          "minimum": 0,
      +          "type": "number"
      +        },
      +        "basis": {
      +          "description": "per_side: on each fill; round_trip: once for the entry and exit together.",
      +          "enum": [
      +            "per_side",
      +            "round_trip"
      +          ],
      +          "type": "string"
      +        },
      +        "lot_ounces": {
      +          "description": "usd_per_lot only: the lot's size in ounces. Left out, the standard lot: 100 oz of gold, 5,000 oz of silver.",
      +          "exclusiveMinimum": 0,
      +          "type": "number"
      +        },
      +        "side": {
      +          "enum": [
      +            "commission",
      +            "slippage",
      +            "spread"
      +          ],
      +          "type": "string"
      +        },
      +        "unit": {
      +          "description": "usd_per_share on stocks and ETFs; usd_per_ounce, and usd_per_lot for a commission per lot, on spot gold and silver; pips on currency pairs; percent, bps and usd_per_order (a flat fee per order, whatever its size) on any market.",
      +          "enum": [
      +            "percent",
      +            "bps",
      +            "usd_per_share",
      +            "usd_per_ounce",
      +            "pips",
      +            "usd_per_order",
      +            "usd_per_lot"
      +          ],
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "side",
      +        "amount",
      +        "unit",
      +        "basis"
      +      ],
      +      "type": "object"
      +    },
      +    "maxItems": 6,
      +    "minItems": 1,
      +    "type": "array"
      +  }
      +]
    • changedOutput schema / properties / cost_table / properties / components / items / properties / unit / enum
      Previous value: -[
      -  "percent",
      -  "bps",
      -  "usd_per_share",
      -  "usd_per_ounce",
      -  "pips",
      -  "usd_per_order"
      -]New value: +[
      +  "percent",
      +  "bps",
      +  "usd_per_share",
      +  "usd_per_ounce",
      +  "pips",
      +  "usd_per_order",
      +  "usd_per_lot"
      +]
    • addedOutput schema / properties / settings / properties / costs_charged / properties / value / items / properties / lot_ounces
      Added value: +{
      +  "type": "number"
      +}
    • changedOutput schema / properties / settings / properties / costs_charged / properties / value / items / properties / unit / enum
      Previous value: -[
      -  "percent",
      -  "bps",
      -  "usd_per_share",
      -  "usd_per_ounce",
      -  "pips",
      -  "usd_per_order"
      -]New value: +[
      +  "percent",
      +  "bps",
      +  "usd_per_share",
      +  "usd_per_ounce",
      +  "pips",
      +  "usd_per_order",
      +  "usd_per_lot"
      +]
  2. Changed4 schema fields changed
    • changedInput schema / properties / costs / oneOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "commission": {
      -        "description": "A fraction of the trade value at entry (0.0005 is 0.05%), charged once per round trip.",
      -        "maximum": 0.05,
      -        "minimum": 0,
      -        "type": "number"
      -      },
      -      "slippage": {
      -        "description": "A fraction of the trade value per fill (entry and exit).",
      -        "maximum": 0.05,
      -        "minimum": 0,
      -        "type": "number"
      -      }
      -    },
      -    "required": [],
      -    "type": "object"
      -  },
      -  {
      -    "items": {
      -      "additionalProperties": false,
      -      "properties": {
      -        "amount": {
      -          "description": "The figure in `unit` (0.005 usd_per_share is half a cent a share; 0.1 percent is 0.1%).",
      -          "minimum": 0,
      -          "type": "number"
      -        },
      -        "basis": {
      -          "description": "per_side: on each fill; round_trip: once for the entry and exit together.",
      -          "enum": [
      -            "per_side",
      -            "round_trip"
      -          ],
      -          "type": "string"
      -        },
      -        "side": {
      -          "enum": [
      -            "commission",
      -            "slippage",
      -            "spread"
      -          ],
      -          "type": "string"
      -        },
      -        "unit": {
      -          "description": "usd_per_share on stocks and ETFs; usd_per_ounce on spot gold and silver; pips on currency pairs; percent, bps and usd_per_order (a flat fee per order) on any market.",
      -          "enum": [
      -            "percent",
      -            "bps",
      -            "usd_per_share",
      -            "usd_per_ounce",
      -            "pips",
      -            "usd_per_order"
      -          ],
      -          "type": "string"
      -        }
      -      },
      -      "required": [
      -        "side",
      -        "amount",
      -        "unit",
      -        "basis"
      -      ],
      -      "type": "object"
      -    },
      -    "maxItems": 6,
      -    "minItems": 1,
      -    "type": "array"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "commission": {
      +        "description": "A fraction of the trade value at entry (0.0005 is 0.05%), charged once per round trip.",
      +        "maximum": 0.05,
      +        "minimum": 0,
      +        "type": "number"
      +      },
      +      "slippage": {
      +        "description": "A fraction of the trade value per fill (entry and exit).",
      +        "maximum": 0.05,
      +        "minimum": 0,
      +        "type": "number"
      +      }
      +    },
      +    "required": [],
      +    "type": "object"
      +  },
      +  {
      +    "items": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "amount": {
      +          "description": "The figure in `unit` (0.005 usd_per_share is half a cent a share; 0.1 percent is 0.1%).",
      +          "minimum": 0,
      +          "type": "number"
      +        },
      +        "basis": {
      +          "description": "per_side: on each fill; round_trip: once for the entry and exit together.",
      +          "enum": [
      +            "per_side",
      +            "round_trip"
      +          ],
      +          "type": "string"
      +        },
      +        "side": {
      +          "enum": [
      +            "commission",
      +            "slippage",
      +            "spread"
      +          ],
      +          "type": "string"
      +        },
      +        "unit": {
      +          "description": "usd_per_share on stocks and ETFs; usd_per_ounce on spot gold and silver; pips on currency pairs; percent, bps and usd_per_order (a flat fee per order, such as a broker's fee per order or per lot) on any market.",
      +          "enum": [
      +            "percent",
      +            "bps",
      +            "usd_per_share",
      +            "usd_per_ounce",
      +            "pips",
      +            "usd_per_order"
      +          ],
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "side",
      +        "amount",
      +        "unit",
      +        "basis"
      +      ],
      +      "type": "object"
      +    },
      +    "maxItems": 6,
      +    "minItems": 1,
      +    "type": "array"
      +  }
      +]
    • addedOutput schema / properties / cost_table
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Every cost the run charged: each component (commission, slippage, spread) with its amount, unit and basis, what it comes to per round trip, when it is taken, and whether it is yours (caller) or the market's default; the round trip summed by unit (pips on a currency pair, the costs stated in pips). Costs you send replace the market's defaults side by side: a commission replaces the default commission, a slippage or a spread replaces the default slippage, a side you leave out is charged at the market's default, and nothing is added on top.",
      +  "properties": {
      +    "components": {
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "amount": {
      +            "type": "number"
      +          },
      +          "basis": {
      +            "enum": [
      +              "per_side",
      +              "round_trip"
      +            ],
      +            "type": "string"
      +          },
      +          "charged": {
      +            "description": "When and on what the engine takes it.",
      +            "type": "string"
      +          },
      +          "component": {
      +            "enum": [
      +              "commission",
      +              "slippage",
      +              "spread"
      +            ],
      +            "type": "string"
      +          },
      +          "origin": {
      +            "description": "caller: your costs; default: the market's default.",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "per_round_trip": {
      +            "additionalProperties": false,
      +            "properties": {
      +              "amount": {
      +                "type": "number"
      +              },
      +              "unit": {
      +                "enum": [
      +                  "bps",
      +                  "pips",
      +                  "usd",
      +                  "usd_per_share",
      +                  "usd_per_ounce"
      +                ],
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "amount",
      +              "unit"
      +            ],
      +            "type": "object"
      +          },
      +          "unit": {
      +            "enum": [
      +              "percent",
      +              "bps",
      +              "usd_per_share",
      +              "usd_per_ounce",
      +              "pips",
      +              "usd_per_order"
      +            ],
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "component",
      +          "amount",
      +          "unit",
      +          "basis",
      +          "per_round_trip",
      +          "charged",
      +          "origin"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "defaults_replaced": {
      +      "description": "The market defaults your costs replaced: none of them was charged, and nothing was added to your costs.",
      +      "items": {
      +        "enum": [
      +          "commission",
      +          "slippage"
      +        ],
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "round_trip_total": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "bps_of_value": {
      +          "type": "number"
      +        },
      +        "pips": {
      +          "type": "number"
      +        },
      +        "usd": {
      +          "type": "number"
      +        },
      +        "usd_per_ounce": {
      +          "type": "number"
      +        },
      +        "usd_per_share": {
      +          "type": "number"
      +        }
      +      },
      +      "required": [
      +        "bps_of_value"
      +      ],
      +      "type": "object"
      +    }
      +  },
      +  "required": [
      +    "components",
      +    "defaults_replaced",
      +    "round_trip_total"
      +  ],
      +  "type": "object"
      +}
    • addedOutput schema / properties / market / properties / derived_only / description
      Added value: +"True when the market-data licence lets the account see only results derived from the prices (figures, never the prices or bars themselves). It says what may be shown, not how the quote is made."
    • addedOutput schema / properties / window / properties / gaps
      Added value: +{
      +  "items": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "from": {
      +        "type": "string"
      +      },
      +      "to": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "from",
      +      "to"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
  3. First observed

TDQS

A4.4/5.0
Behavior5/5

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

Annotations only declare a non-read-only, non-destructive, non-idempotent, closed-world call; the description goes well beyond that. It discloses the 90-second wait and the 'running' status fallback with a run_id, the exact shape of the returned summary figures and trade rows, that prices and bars are never returned, and that individual figures may be withheld with a stated reason.

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?

Everything is packed into one front-loaded paragraph that leads with the verb and resource before the return-value caveats, and no sentence is filler. The dense semicolon-chained structure makes it harder to scan than it needs to be, but it is appropriately sized for a tool this rich.

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?

For a nine-parameter, non-idempotent run tool with an output schema, the description covers the calling contract, the timeout/follow-up path, the return shape and the withholding caveat. An agent has everything needed to invoke it and to interpret a 'running' response.

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 coverage is 89%, so the schema already documents nearly every parameter, including the code class, costs, window and stated_rules. The description restates that code is one Strategy class, one symbol and one bar size but adds no syntax, defaults or units beyond that, which is the expected baseline when the schema carries the load.

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 description names a concrete verb and resource ('Backtests a trading rule on this server's price history') and pins down the unit of work: one Strategy class, one symbol, one bar size, inside a study. It also implicitly separates the tool from the polling sibling by naming get_result as the follow-up, so an agent can identify it without opening the schema.

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?

'Use it to test, backtest or evaluate a trading rule or strategy' gives a clear invocation context, and the long-run behavior is routed explicitly to get_result with a run_id. It does not, however, say when to prefer run_held_out_test or compare_trades instead, so the alternative-selection guidance is only partial.

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