PineForge-Codegen

backtest_pine_grid

Sweep PineScript strategy inputs and overrides to find optimal settings. Transpiles once, runs all combinations, and returns a ranked list sorted by net PnL or chosen metric.

Instructions

Use when the user wants to optimize, sweep, tune, or compare PineScript parameter values (e.g. 'try fast length 8/12/19', 'find the best commission/qty settings') rather than test a single configuration — for one fixed configuration use backtest_pine. Run a parameter sweep: transpile the Pine source ONCE (locally, in-container), then re-run the same compiled strategy against the OHLCV CSV across the cartesian product of inputs × overrides grids. Returns a ranked list of {inputs, overrides, summary, elapsed_seconds} entries sorted by sort_by descending, plus the top entry under best. Cap: max_combinations (default 64). Set concurrency > 1 to run backtests in parallel — each docker container has its own startup overhead, so 2-4 is usually plenty.

Input Schema

TableJSON Schema

Name	Required	Description
`image`	No	Docker image override. Defaults to ghcr.io/pineforge-4pass/pineforge-engine:latest.
`inputs`	No	Grid of input.*() names → list of values to sweep. Example: {"Fast Length": [8, 12, 19], "Slow Length": [21, 26, 39]}
`source`	Yes	PineScript v6 source.
`runtime`	No	Engine runtime args applied to every combo in the sweep. Same shape as backtest_pine.runtime — input_tf / script_tf / bar_magnifier / magnifier_samples / magnifier_dist. Currently fixed across the grid (not swept); add to the grid axes through future versions if you need to vary them.
`sort_by`	No	summary.* field to rank by, descending. Default net_pnl.
`overrides`	No	Grid of strategy(...) header overrides → list of values, one axis per key. Example: {"default_qty_value": [1, 5], "commission_value": [0.04]}. Call list_engine_params for the full catalog with types and enum values.
`concurrency`	No	Parallel backtests. Default 1.
`report_path`	No	Where to write the full sweep JSON IF it is too large to return inline. Oversized sweeps are offloaded here and the tool returns the best + top-ranked combinations + report_path; read the file for all combinations. Defaults to pineforge-grid-<timestamp>.json in the working dir.
`fixed_inputs`	No	Inputs applied to every combo (overridden by per-combo `inputs` keys).
`include_trades`	No	Include the per-trade list in each result. Default false (saves tokens).
`ohlcv_csv_path`	Yes	Path to OHLCV CSV (same format as backtest_pine).
`fixed_overrides`	No	Overrides applied to every combo (overridden by per-combo `overrides` keys).
`max_combinations`	No	Hard cap on combinations. Default 64.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv0.9.30Sep 11, 2026

removedInput schema / properties / fixed_inputs / additionalProperties / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "number"
-  },
-  {
-    "type": "boolean"
-  }
-]

addedInput schema / properties / fixed_inputs / additionalProperties / type
```
Added value: +[
+  "string",
+  "number",
+  "boolean"
+]
```

removedInput schema / properties / inputs / additionalProperties / items / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "number"
-  },
-  {
-    "type": "boolean"
-  }
-]

addedInput schema / properties / inputs / additionalProperties / items / type
```
Added value: +[
+  "string",
+  "number",
+  "boolean"
+]
```

Changed1 schema field changedv0.9.0Jun 9, 2026

addedInput schema / properties / report_path

Added value: +{
+  "description": "Where to write the full sweep JSON IF it is too large to return inline. Oversized sweeps are offloaded here and the tool returns the best + top-ranked combinations + report_path; read the file for all combinations. Defaults to pineforge-grid-<timestamp>.json in the working dir.",
+  "type": "string"
+}

First observedv0.8.4Jun 7, 2026

TDQS

A4.4/5.0

Behavior4/5

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

No annotations, so the description carries the burden and does well: it discloses the transpile-once-then-rerun execution model, the ranked return shape, the default cap (max_combinations 64), and container startup overhead guidance for concurrency. It stops short of stating auth/runtime limits or error behavior, but covers the operationally salient traits.

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?

Three dense sentences with the trigger front-loaded, but the middle sentence packs transpile model, grid semantics, return shape, cap, and concurrency into one run-on. Information-rich yet structurally overloaded; a list or additional breaks would improve scannability.

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 13-parameter nested-grid tool with no output schema and no annotations, the description covers the sweep model, ranking, cap, concurrency, and oversized-report offload. It leaves concurrency default/limits and error surface to the schema, which is reasonable here since schema coverage is 100%.

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

Parameters4/5

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

Schema coverage is already 100%, so baseline is 3, and the description adds real cross-parameter meaning beyond the schema: the cartesian product semantics of inputs × overrides, the ranked-output contract tied to sort_by, the concurrency overhead tradeoff, and the report_path offload behavior when a sweep is too large.

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 specific verb and resource ('run a parameter sweep' over 'the same compiled strategy against the OHLCV CSV across the cartesian product of `inputs` × `overrides` grids'), and explicitly distinguishes itself from sibling backtest_pine ('for one fixed configuration use backtest_pine'). An agent can select correctly 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?

Opens with an explicit trigger ('when the user wants to optimize, sweep, tune, or compare PineScript parameter values') including example phrasings, and names the alternative (backtest_pine) plus the condition selecting it. Exclusions and trigger are both stated.

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

Deploy Server

backtest_pine_grid

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools