> ## 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.

# MCP tool reference

> Inputs and response shapes for every AskFutures MCP tool.

This is the field-level reference for every AskFutures MCP tool. For the
workflow — which tool to call when, and how the pieces fit together — see the
[tools walkthrough](/developers/tools).

<Note>
  **How to read this page.** Each tool lists its **inputs** (what you send) and
  its **result** (what comes back). Every tool returns the standard envelope
  below; the **Result** fields documented per tool are what lands inside
  `structuredContent`.
</Note>

## The result envelope

Every tool returns the same shape. A human-readable summary in `content`, the
structured data in `structuredContent`, and `isError: true` only when something
went wrong.

<ResponseField name="content" type="array">
  A one-element array with a `text` block: a short summary plus a pretty-printed
  copy of the structured data.
</ResponseField>

<ResponseField name="structuredContent" type="object">
  The machine-readable result. The per-tool **Result** fields below describe
  what's in here.
</ResponseField>

<ResponseField name="isError" type="boolean">
  Present and `true` only on failure. On a failure the structured content carries
  the error detail (for example a `status` and, for upstream errors, the failing
  `status` code and `body`).
</ResponseField>

<Tip>
  Most tools that act on a session also return an `app_url` you can open in the
  browser to see the same session, strategy, or backtest in the web app.
</Tip>

## Sessions

A session is the workspace your strategies live in. Create or list one first,
then pass its `session_id` to everything else.

### create\_session

Create an AskFutures session for strategy work.

**Inputs**

<ParamField body="title" type="string">
  Optional session title.
</ParamField>

**Result**

<ResponseField name="session_id" type="string">
  The new session's ID. Pass this to the strategy tools.
</ResponseField>

<ResponseField name="app_url" type="string">
  Link to the session in the web app.
</ResponseField>

### list\_sessions

List the sessions owned by the authenticated user.

**Inputs**

<ParamField body="status" type="string" default="active">
  Filter: `active`, `archived`, or `all`.
</ParamField>

<ParamField body="limit" type="integer" default="20">
  Page size, 1–100.
</ParamField>

<ParamField body="cursor" type="string">
  Opaque pagination cursor from a previous page.
</ParamField>

**Result**

<ResponseField name="sessions" type="array">
  The sessions on this page. Each carries its own `session_id` and `app_url`.
</ResponseField>

<ResponseField name="pagination" type="object">
  Cursor info for fetching the next page, when present.
</ResponseField>

### get\_session

Fetch one session by ID.

**Inputs**

<ParamField body="session_id" type="string" required>
  The session to fetch.
</ParamField>

**Result**

<ResponseField name="session_id" type="string">
  The session ID.
</ResponseField>

<ResponseField name="app_url" type="string">
  Link to the session in the web app.
</ResponseField>

## Strategies

A strategy is the rule-based plan AskFutures builds from your description. See
[Strategies](/concepts/strategies) for the concept.

### create\_strategy

Start building a new strategy from a plain-English description. This is
**asynchronous**: it queues the work and returns an `operation_id`. Call
[`wait_for_completion`](#wait_for_completion) next with that `operation_id`.

By default a backtest runs as part of creation.

**Inputs**

<ParamField body="session_id" type="string" required>
  The session to build in.
</ParamField>

<ParamField body="description" type="string" required>
  The strategy idea, in plain English — e.g. *"Buy Micro Nasdaq when price breaks
  above the first 15-minute high."*
</ParamField>

<ParamField body="backtest" type="boolean" default="true">
  Whether to run a backtest as part of creation. Set `false` to build the rules
  without testing yet, then call
  [`backtest_existing_strategy`](#backtest_existing_strategy) later.
</ParamField>

<ParamField body="idempotency_key" type="string">
  Optional. Reuse the same key to safely retry the same creation request without
  building a duplicate. Generated automatically when omitted.
</ParamField>

<ParamField body="provider" type="string">
  Advanced/optional. Leave unset to use the default.
</ParamField>

**Result**

<ResponseField name="operation_id" type="string">
  The async operation to poll with [`wait_for_completion`](#wait_for_completion)
  (`task="strategy_op"`).
</ResponseField>

<ResponseField name="session_id" type="string">
  The session the strategy is being built in.
</ResponseField>

<ResponseField name="app_url" type="string">
  Link to the session in the web app.
</ResponseField>

### update\_strategy

Start modifying an existing strategy — add a filter, change an exit, swap the
symbol, change the period. Like creation, this is **asynchronous** and returns an
`operation_id`. Every edit becomes a new saved version.

**Inputs**

<ParamField body="session_id" type="string" required>
  The session the strategy lives in.
</ParamField>

<ParamField body="artifact_id" type="string" required>
  The strategy to modify.
</ParamField>

<ParamField body="changes" type="string" required>
  The change, in plain English — e.g. *"Add a 200-tick stop and only trade
  9:30–11:00."*
</ParamField>

<ParamField body="provider" type="string">
  Advanced/optional. Leave unset to use the default.
</ParamField>

**Result**

<ResponseField name="operation_id" type="string">
  The async operation to poll with [`wait_for_completion`](#wait_for_completion)
  (`task="strategy_op"`).
</ResponseField>

<ResponseField name="session_id" type="string">
  The session the strategy lives in.
</ResponseField>

<ResponseField name="app_url" type="string">
  Link to the session in the web app.
</ResponseField>

### list\_strategies

List the strategies in a session, including the canonical parameters you need
for optimization.

**Inputs**

<ParamField body="session_id" type="string" required>
  The session to list.
</ParamField>

**Result**

<ResponseField name="strategies" type="array">
  The strategies in the session. Each entry is summarized — see the fields below.

  <Expandable title="strategy summary fields">
    <ResponseField name="artifact_id" type="string">
      The strategy's ID — pass this to inspect, update, backtest, optimize, or
      delete.
    </ResponseField>

    <ResponseField name="version" type="number">
      The version number. Edits create new versions.
    </ResponseField>

    <ResponseField name="name" type="string">
      The strategy name.
    </ResponseField>

    <ResponseField name="ticker" type="string">
      The traded symbol, e.g. `MNQ`.
    </ResponseField>

    <ResponseField name="timeframeType" type="string">
      The trading style / bar timeframe.
    </ResponseField>

    <ResponseField name="entryDescription" type="string">
      A short description of the entry rule.
    </ResponseField>

    <ResponseField name="lifecycle_status" type="string">
      Where the strategy is in its build, e.g. `creating` or ready.
    </ResponseField>

    <ResponseField name="backtestStatus" type="string">
      `not_tested`, `passed`, or `failed`.
    </ResponseField>

    <ResponseField name="backtestResults" type="object">
      When tested: `tradeCount`, `totalPnl`, `winRate`, `maxDrawdown`,
      `sharpeRatio`.
    </ResponseField>

    <ResponseField name="canonicalParameters" type="array">
      The tunable parameters. Each has `key`, `label`, `value`, `category`, and
      `aliases`. Use the `key` values when configuring an optimization.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination info, when present.
</ResponseField>

<Warning>
  Backtest figures returned here are **hypothetical and simulated**, net of
  modeled slippage and commission. Past performance does not guarantee future
  results. Always test before you trade.
</Warning>

### inspect\_strategy

Fetch one strategy in full: entry/exit rules, exit conditions, parameters, the
extraction plan, and backtest status.

**Inputs**

<ParamField body="session_id" type="string" required>
  The session the strategy lives in.
</ParamField>

<ParamField body="artifact_id" type="string" required>
  The strategy to inspect.
</ParamField>

**Result**

Includes every field from the [`list_strategies`](#list_strategies) summary,
plus:

<ResponseField name="entry_rules" type="array">
  The rules that open positions.
</ResponseField>

<ResponseField name="exit_rules" type="array">
  The rules that close positions.
</ResponseField>

<ResponseField name="parameter_rules" type="array">
  The parameter definitions as they appear on the strategy card.
</ResponseField>

<ResponseField name="exit_conditions" type="array">
  Structured exits — stop, target, trailing stop, max-time, end-of-day.
</ResponseField>

<ResponseField name="extractionPlan" type="object">
  The structured plan AskFutures derived from your description.
</ResponseField>

### delete\_strategy

Delete a draft strategy. The server refuses unless you set `confirm: true`.

**Inputs**

<ParamField body="session_id" type="string" required>
  The session the strategy lives in.
</ParamField>

<ParamField body="artifact_id" type="string" required>
  The strategy to delete.
</ParamField>

<ParamField body="confirm" type="boolean" default="false">
  Must be `true` to actually delete. Anything else is a no-op refusal.
</ParamField>

**Result**

<ResponseField name="artifact_id" type="string">
  The deleted strategy's ID, echoed back on success.
</ResponseField>

## Backtesting

See [Backtesting](/concepts/backtesting) and
[Is the backtest real?](/concepts/is-the-backtest-real) for what the engine does
and doesn't model.

### backtest\_existing\_strategy

Run (or re-run) a backtest on an existing strategy. It does **not** create or
fork — it tests the strategy in place. Because `create_strategy` already
backtests by default, only call this when the strategy was created with
`backtest=false`, when its `backtestStatus` is `not_tested` or `failed`, or when
you explicitly want a re-run.

This is **asynchronous** — poll with [`wait_for_completion`](#wait_for_completion)
(`task="backtest"`).

**Inputs**

<ParamField body="session_id" type="string" required>
  The session the strategy lives in.
</ParamField>

<ParamField body="artifact_id" type="string" required>
  The strategy to backtest.
</ParamField>

**Result**

<ResponseField name="artifact_id" type="string">
  The strategy being backtested.
</ResponseField>

<ResponseField name="session_id" type="string">
  The session.
</ResponseField>

<ResponseField name="app_url" type="string">
  Link to watch the backtest in the web app.
</ResponseField>

<Warning>
  Backtest results are hypothetical and simulated, net of modeled slippage and
  commission. Past performance does not guarantee future results. Always test
  before you trade.
</Warning>

## Optimization

Optimization is a two-step flow: configure the sweep, then run it. See
[Optimization](/concepts/optimization).

### setup\_optimization

Configure an optimization sweep for a backtested strategy. Call
[`list_strategies`](#list_strategies) first to get the canonical parameter
`key` values to sweep.

**Inputs**

<ParamField body="session_id" type="string" required>
  The session the strategy lives in.
</ParamField>

<ParamField body="artifact_id" type="string" required>
  The strategy to optimize. It should already be backtested.
</ParamField>

<ParamField body="parameters" type="array" required>
  The parameters to sweep. Each entry:

  <Expandable title="sweep parameter">
    <ParamField body="name" type="string" required>
      The parameter key (a canonical `key` from `list_strategies`).
    </ParamField>

    <ParamField body="min" type="number" required>
      Lowest value to try.
    </ParamField>

    <ParamField body="max" type="number" required>
      Highest value to try.
    </ParamField>

    <ParamField body="step" type="number" required>
      Increment between values. Must be positive.
    </ParamField>
  </Expandable>
</ParamField>

**Result**

<ResponseField name="optimization_id" type="string">
  The configured batch's ID. Pass it to [`run_optimization`](#run_optimization).
</ResponseField>

<ResponseField name="app_url" type="string">
  Link to the session in the web app.
</ResponseField>

### run\_optimization

Promote a configured batch to running. Queues one backtest per parameter
combination; results land on the strategy when the batch completes.

This is **asynchronous** — poll with [`wait_for_completion`](#wait_for_completion)
(`task="optimization"`).

**Inputs**

<ParamField body="session_id" type="string" required>
  The session the strategy lives in.
</ParamField>

<ParamField body="artifact_id" type="string" required>
  The strategy being optimized.
</ParamField>

<ParamField body="optimization_id" type="string" required>
  The batch ID from [`setup_optimization`](#setup_optimization).
</ParamField>

**Result**

<ResponseField name="optimization_id" type="string">
  The running batch's ID.
</ResponseField>

<ResponseField name="app_url" type="string">
  Link to watch the sweep in the web app.
</ResponseField>

## Async control

Strategy creation, updates, backtests, and optimizations all run in the
background. These two tools let you wait on them and cancel them.

### wait\_for\_completion

Poll an async operation until it succeeds, fails, or the timeout is reached. On
timeout the operation keeps running server-side — just call again later. The
`task` you pass decides which IDs are required.

<Tabs>
  <Tab title="strategy_op">
    For [`create_strategy`](#create_strategy) and
    [`update_strategy`](#update_strategy). Pass the `operation_id`. On success the
    result includes the finished `strategy` summary.
  </Tab>

  <Tab title="backtest">
    For [`backtest_existing_strategy`](#backtest_existing_strategy). Pass the
    `artifact_id`; it polls `backtestStatus`. On success the result includes
    `backtest_results`.
  </Tab>

  <Tab title="optimization">
    For [`run_optimization`](#run_optimization). Pass both `artifact_id` and
    `optimization_id`; it polls the batch. On success the result includes
    `total_combinations`, `failed_count`, and `best_result`.
  </Tab>
</Tabs>

**Inputs**

<ParamField body="session_id" type="string" required>
  The session.
</ParamField>

<ParamField body="task" type="string" required>
  Which kind of wait: `strategy_op`, `backtest`, or `optimization`.
</ParamField>

<ParamField body="operation_id" type="string">
  Required when `task="strategy_op"`.
</ParamField>

<ParamField body="artifact_id" type="string">
  Required when `task="backtest"` or `task="optimization"`.
</ParamField>

<ParamField body="optimization_id" type="string">
  Required when `task="optimization"`.
</ParamField>

<ParamField body="timeout_seconds" type="number" default="45">
  How long to wait this call, 1–300. On timeout the work continues server-side.
</ParamField>

**Result**

<ResponseField name="status" type="string">
  Present as `timed_out` when the wait window elapses but the work is still
  running. Call again to keep waiting.
</ResponseField>

<ResponseField name="strategy" type="object">
  On a successful `strategy_op`: the finished strategy summary.
</ResponseField>

<ResponseField name="backtest_results" type="object">
  On a successful `backtest`: the run's metrics.
</ResponseField>

<ResponseField name="best_result" type="object">
  On a successful `optimization`: the best combination found, alongside
  `total_combinations` and `failed_count`.
</ResponseField>

<Note>
  A failed or timed-out operation comes back with `isError: true` and the
  operation detail (for example `backtestError` for a failed backtest, or the
  batch `error` for a failed sweep).
</Note>

### cancel\_task

Request cancellation of an in-flight task. Returns immediately and is
idempotent.

For optimization, the session's single running sweep is resolved automatically,
stops between combinations, and partial results are kept. For backtests and
create/update, cancellation only takes effect if the worker hasn't started yet —
short in-flight tasks are allowed to finish.

**Inputs**

<ParamField body="session_id" type="string" required>
  The session.
</ParamField>

<ParamField body="task" type="string" required>
  Which task to cancel: `strategy_op`, `backtest`, or `optimization`.
</ParamField>

<ParamField body="operation_id" type="string">
  The operation to cancel, for `strategy_op`.
</ParamField>

<ParamField body="artifact_id" type="string">
  The strategy whose task to cancel, for `backtest` / `optimization`.
</ParamField>

<ParamField body="optimization_id" type="string">
  The sweep to cancel, for `optimization`.
</ParamField>

**Result**

<ResponseField name="session_id" type="string">
  The session, echoed back with the upstream cancellation acknowledgement.
</ResponseField>

## Planning

### write\_todos

Replace the agent's task list for the session. **Full-replace semantics** — send
the entire list every call. Useful for multi-step work, especially when an async
wait may span turns. Keep exactly one item `in_progress` while working, and mark
items `completed` as you finish them.

**Inputs**

<ParamField body="session_id" type="string" required>
  The session.
</ParamField>

<ParamField body="todos" type="array" required>
  The full task list. Each item:

  <Expandable title="todo item">
    <ParamField body="id" type="string" required>
      Stable identifier for the item.
    </ParamField>

    <ParamField body="content" type="string" required>
      What the step is.
    </ParamField>

    <ParamField body="status" type="string" required>
      `pending`, `in_progress`, or `completed`.
    </ParamField>

    <ParamField body="activeForm" type="string">
      Optional present-tense phrasing shown while the item is in progress.
    </ParamField>
  </Expandable>
</ParamField>

**Result**

<ResponseField name="session_id" type="string">
  The session, echoed back with the saved plan.
</ResponseField>

## Reference data

What's available to trade, and the contract specs. Scope is CME Group only (CME,
CBOT, NYMEX, COMEX), \~74 symbols.

### list\_symbols

List all CME Group futures symbols available for trading. Use it to discover
what's available before creating a strategy.

**Inputs**

*None.*

**Result**

<ResponseField name="count" type="number">
  How many symbols were returned.
</ResponseField>

<ResponseField name="symbols" type="array">
  The symbols. Each entry includes `ticker`, `name`, and `sector`.
</ResponseField>

### get\_reference\_data

Look up contract metadata for one symbol.

**Inputs**

<ParamField body="symbol" type="string" required>
  The ticker, e.g. `MNQ`.
</ParamField>

**Result**

The contract specs for the symbol, returned as the structured content directly —
including tick size, tick value, margin, and session hours.

## Next steps

<CardGroup cols={2}>
  <Card title="Tools walkthrough" icon="toolbox" href="/developers/tools">
    The same tools, explained as a workflow.
  </Card>

  <Card title="Recipes" icon="book" href="/developers/recipes">
    End-to-end programmatic examples.
  </Card>

  <Card title="Internal HTTP API" icon="server" href="/api-reference/internal-http-api">
    Why the web app's HTTP layer is private.
  </Card>

  <Card title="Is the backtest real?" icon="shield-check" href="/concepts/is-the-backtest-real">
    Where the AI stops and the deterministic math begins.
  </Card>
</CardGroup>