> ## Documentation Index
> Fetch the complete documentation index at: https://docs.askfutures.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Recipes

> Copy-paste end-to-end flows over the AskFutures MCP tools: build & backtest a strategy, re-test an existing one, run a parameter sweep, cancel a long task, and look up contract specs.

Each recipe chains real [MCP tools](/developers/tools) in the order you'd call
them. The calls are shown as tool name + arguments — your client phrases them as
its own tool invocations. The golden rule runs through all of them: **kick off,
then `wait_for_completion`.** See [developer concepts](/developers/concepts) for
the why.

<Info>
  Every metric below is a hypothetical, simulated backtest result — deterministic
  math over real historical prices, net of modeled slippage and commission, not
  advice. Past performance does not guarantee future results. Always test before
  you trade.
</Info>

## Recipe 1 — Create a strategy and backtest it

The most common flow. `create_strategy` builds the rules **and** runs a backtest
in one shot (it's on by default), so you wait once on the build, then read the
finished strategy.

<Steps>
  <Step title="Create a session">
    Get a `session_id` to hang everything off of.
  </Step>

  <Step title="Start the strategy">
    Describe the idea in plain English. You get back an `operation_id`.
  </Step>

  <Step title="Wait for the build">
    Poll the `operation_id` with `task='strategy_op'`. On success the result
    carries the finished strategy summary, including its `backtestResults`.
  </Step>

  <Step title="Read the result">
    Inspect the strategy, and hand the `app_url` to your user so they can open
    the strategy card and **Strategy Flow** chart.
  </Step>
</Steps>

<CodeGroup>
  ```json 1. create_session theme={null}
  {
    "title": "MNQ opening-range breakout"
  }
  ```

  ```json 2. create_strategy theme={null}
  {
    "session_id": "<session_id from step 1>",
    "description": "Buy Micro Nasdaq when price breaks above the first 15-minute high, exit at end of day"
  }
  ```

  ```json 3. wait_for_completion theme={null}
  {
    "session_id": "<session_id>",
    "task": "strategy_op",
    "operation_id": "<operation_id from step 2>",
    "timeout_seconds": 120
  }
  ```

  ```json 4. inspect_strategy theme={null}
  {
    "session_id": "<session_id>",
    "artifact_id": "<artifact_id from step 3>"
  }
  ```
</CodeGroup>

<Tip>
  If step 3 returns `status: "timed_out"`, the build is still running
  server-side. Call `wait_for_completion` again with the same `operation_id` —
  it's not an error.
</Tip>

<Warning>
  Don't backtest or optimize the artifact until step 3 reports `succeeded`. Until
  then the strategy is still `creating`. Results are hypothetical and simulated —
  past performance does not guarantee future results.
</Warning>

## Recipe 2 — Backtest an existing strategy

You already have a strategy artifact (maybe created with `backtest=false`, or its
`backtestStatus` is `not_tested` / `failed`, or you just want a fresh run).
`backtest_existing_strategy` re-tests it **in place** — no new version, no fork.

<Steps>
  <Step title="Find the artifact">
    `list_strategies` to get the `artifact_id` and its current `backtestStatus`.
  </Step>

  <Step title="Start the backtest">
    `backtest_existing_strategy` kicks it off.
  </Step>

  <Step title="Wait on the artifact">
    Poll with `task='backtest'` and the `artifact_id` — `wait_for_completion`
    watches the artifact's `backtestStatus`.
  </Step>
</Steps>

<CodeGroup>
  ```json 1. list_strategies theme={null}
  {
    "session_id": "<session_id>"
  }
  ```

  ```json 2. backtest_existing_strategy theme={null}
  {
    "session_id": "<session_id>",
    "artifact_id": "<artifact_id>"
  }
  ```

  ```json 3. wait_for_completion theme={null}
  {
    "session_id": "<session_id>",
    "task": "backtest",
    "artifact_id": "<artifact_id>",
    "timeout_seconds": 120
  }
  ```
</CodeGroup>

On success you get `backtest_results` — `tradeCount`, `totalPnl`, `winRate`,
`maxDrawdown`, `sharpeRatio`. See the
[metrics glossary](/reference/metrics-glossary) for what each one means.

## Recipe 3 — Run a parameter sweep

Optimization is a **two-step** async flow: configure the batch, then run it. You
need the strategy's **canonical parameter keys** first — those come from
`list_strategies`.

<Steps>
  <Step title="Get the parameter keys">
    `list_strategies` returns each strategy's `canonicalParameters`. Use the
    `key` of each parameter you want to sweep.
  </Step>

  <Step title="Configure the sweep">
    `setup_optimization` with a range (`min`, `max`, `step`) per parameter. It
    returns an `optimization_id`. Nothing runs yet.
  </Step>

  <Step title="Run it">
    `run_optimization` promotes the batch to running — one backtest per
    combination.
  </Step>

  <Step title="Wait for the batch">
    Poll with `task='optimization'`, passing **both** the `artifact_id` and the
    `optimization_id`.
  </Step>
</Steps>

<CodeGroup>
  ```json 1. list_strategies theme={null}
  {
    "session_id": "<session_id>"
  }
  ```

  ```json 2. setup_optimization theme={null}
  {
    "session_id": "<session_id>",
    "artifact_id": "<artifact_id>",
    "parameters": [
      { "name": "ema_fast_period", "min": 5, "max": 20, "step": 1 },
      { "name": "stop_loss", "min": 200, "max": 600, "step": 50 }
    ]
  }
  ```

  ```json 3. run_optimization theme={null}
  {
    "session_id": "<session_id>",
    "artifact_id": "<artifact_id>",
    "optimization_id": "<optimization_id from step 2>"
  }
  ```

  ```json 4. wait_for_completion theme={null}
  {
    "session_id": "<session_id>",
    "task": "optimization",
    "artifact_id": "<artifact_id>",
    "optimization_id": "<optimization_id>",
    "timeout_seconds": 300
  }
  ```
</CodeGroup>

A completed batch reports `total_combinations`, `failed_count`, and a
`best_result`.

<Warning>
  A sweep is the easiest way to fool yourself. The "best" combination is the one
  that fit the **past** best — it may not repeat. Treat optimizer output as a
  starting point, not a promise. Past performance does not guarantee future
  results. See [optimization](/concepts/optimization).
</Warning>

## Recipe 4 — Cancel a long-running task

A sweep across many combinations can run for a while. `cancel_task` requests a
stop. It's idempotent, returns immediately, and behaves differently per task
type.

<Tabs>
  <Tab title="Optimization">
    The session's single running sweep is resolved automatically — it stops
    between combinations and **keeps the partial results**.

    ```json cancel_task theme={null}
    {
      "session_id": "<session_id>",
      "task": "optimization",
      "artifact_id": "<artifact_id>",
      "optimization_id": "<optimization_id>"
    }
    ```
  </Tab>

  <Tab title="Backtest">
    Cancel only takes effect if the worker hasn't started yet — a short
    in-flight backtest is allowed to finish.

    ```json cancel_task theme={null}
    {
      "session_id": "<session_id>",
      "task": "backtest",
      "artifact_id": "<artifact_id>"
    }
    ```
  </Tab>

  <Tab title="Strategy build / update">
    Same rule as a backtest: only cancellable before the worker picks it up.

    ```json cancel_task theme={null}
    {
      "session_id": "<session_id>",
      "task": "strategy_op",
      "operation_id": "<operation_id>"
    }
    ```
  </Tab>
</Tabs>

<Note>
  `cancel_task` returns right away — it requests the stop, it doesn't block until
  the task winds down. If you were waiting, your `wait_for_completion` loop will
  see the task settle on its next poll.
</Note>

## Recipe 5 — Look up contract specs

Before you size stops, targets, or position math, get the tick details right.
Discover symbols, then pull the specs for the one you'll trade.

<Steps>
  <Step title="Discover what's tradable">
    `list_symbols` returns every CME Group symbol with its ticker, name, and
    sector.
  </Step>

  <Step title="Pull the specs">
    `get_reference_data` for a single symbol returns tick size, tick value,
    margin, and session hours.
  </Step>
</Steps>

<CodeGroup>
  ```json 1. list_symbols theme={null}
  {}
  ```

  ```json 2. get_reference_data theme={null}
  {
    "symbol": "MNQ"
  }
  ```
</CodeGroup>

<Tip>
  `list_symbols` takes no arguments. Use it to confirm a symbol is in scope
  (CME, CBOT, NYMEX, COMEX only) before you build a strategy on it, then
  `get_reference_data` for the tick math.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="MCP tools" icon="toolbox" href="/developers/tools">
    The full reference for every tool's inputs and outputs.
  </Card>

  <Card title="Developer concepts" icon="sitemap" href="/developers/concepts">
    Sessions, operations, status fields, and the async model.
  </Card>

  <Card title="Optimization" icon="sliders" href="/concepts/optimization">
    What a sweep does — and how not to overfit.
  </Card>

  <Card title="Is the backtest real?" icon="shield-check" href="/concepts/is-the-backtest-real">
    Why the numbers are reproducible and what they do and don't model.
  </Card>
</CardGroup>