Tool sessions - Firedrill

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

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:

selection.json

{
  "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

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

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

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.

Synthetic tools

All available services.

Custom tools

Simulate your own service.