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

# Tool sessions

> Start synthetic tools on their own, connect a local agent to them and save or reset their state.

A **tool session** runs one or more synthetic tools on their own, outside a drill. Use it to explore a tool, try your agent against it by hand or prepare starting data.

## Start a session

```bash theme={null}
firedrill tools runnable
firedrill tools start <version-id> --seconds 1800
```

`tools start` shows the credit estimate and asks you to approve. With `--json`, it stops with `tool_change_consent_required` and prints the command to run after a person approves. Add `--follow` to wait until the tools are ready.

Pass several version IDs to start several tools together. Use `--service <key>` to start only one service from a tool, or `--file selection.json` to describe the selection in a file:

```json selection.json theme={null}
{
  "duration_seconds": 1800,
  "selections": [
    {
      "implementation_id": "<version-id>",
      "service_key": "gmail",
      "operations": ["messages.list", "messages.send"],
      "seed_id": null,
      "dataset_id": null
    }
  ]
}
```

List at least one operation for each selection. Set `seed_id` or `dataset_id` to choose starting data, but not both.

In the web app, open **Tools**, choose **Select tool**, review the credit budget and start.

## Connect a local agent

```bash theme={null}
firedrill tools access <session-id>
```

This opens local addresses for the session's tools on your machine and prints them. Point your agent or MCP client at them. Access ends when you press Ctrl-C or the session ends. No token is shown to your agent.

Access is read-only by default. Add `--allow-writes` to let your agent change data.

For each tool you get:

* An MCP address for Streamable HTTP clients.
* An HTTP address. Send `POST` with `{"operation": "...", "arguments": {...}}`.

Custom tools give an operations address instead. Send `POST <address>/<service-key>/<operation>` with `{"arguments": {...}}` and an `Idempotency-Key` header, then read the result from the requests address.

## Manage sessions

```bash theme={null}
firedrill tools sessions
firedrill tools session <session-id>
firedrill tools session <session-id> renew --seconds 1800
firedrill tools session <session-id> stop
```

## Save and reset state

```bash theme={null}
firedrill tools state <instance-id> checkpoint
firedrill tools state <instance-id> snapshots
firedrill tools state <instance-id> edit <operation> --file args.json
firedrill tools state <instance-id> reset --seconds 1800
firedrill tools state <instance-id> fork <snapshot-id> --seconds 1800
```

| Command | What it does |
| - | - |
| `checkpoint` | Saves a snapshot of the tool's current data. |
| `snapshots` | Lists saved snapshots. |
| `edit` | Runs one of the tool's own operations against its data, for example to add a record. |
| `reset` | Starts a new session from the starting data. |
| `fork` | Starts a new session from a snapshot. |

`reset` and `fork` start a new session, so they show a credit estimate first. Custom tools keep their own state, and these commands do not apply to them.

## Starting data

Catalog tools start from a seed. Custom tools start from a dataset. Manage datasets with `firedrill tools datasets` or in the web app on the tool's **Data** view.

## From your coding agent

Over MCP, your coding agent can use `firedrill_review_tools`, then `firedrill_quote_tools`, then `firedrill_start_tools` after you approve the estimate. Connecting a local agent to the tools needs the CLI.

> [card] [Synthetic tools](https://docs.firedrill.run/tools/overview.md)
>
> All available services.

> [card] [Custom tools](https://docs.firedrill.run/tools/custom-tools.md)
>
> Simulate your own service.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.