Custom tools - Firedrill

A custom tool is a simulated service you build yourself. Use one when your agent depends on a service that is not in the catalog, such as your own internal API. Custom tools run in an isolated environment in Firedrill. Check the catalog first. If a catalog tool has the right operations, use it and give it your own starting data instead.

Build and upload

Create the package

firedrill tools init my-crm

This creates tool.json and a bundle/ folder with bundle/manifest.json. It does not overwrite an existing tool.json.

Describe the operations

Edit tool.json. Add only the operations your agent uses, with their real request and response shapes.

Write the tool

Put the tool’s code under bundle/app/ and list it in bundle/manifest.json. Use made-up data only. No real customer data, contacts or credentials.

Check the package

firedrill tools validate my-crm

This checks the structure on your machine. Firedrill runs its own checks after upload.

Upload it

Zip the folder’s contents (tool.json and bundle/), then:

firedrill tools push my-crm.zip

The upload creates a private version in your workspace. With --json, add --approve-tool-upload after a person has approved the upload. When Firedrill finishes checking it, the version appears in firedrill tools runnable.

You can also upload a package in the web app under Tools → Import tool.

tool.json

{
  "schema": "firedrill.tool-package.v1",
  "key": "my-crm",
  "version": "1.0.0",
  "name": "My CRM",
  "description": "Our internal customer API.",
  "services": [
    {
      "key": "crm",
      "name": "CRM",
      "surface": null,
      "operations": [
        {
          "name": "customers.get",
          "description": "Get one customer by ID.",
          "effect": "read",
          "input_schema": {
            "type": "object",
            "properties": { "id": { "type": "string" } },
            "required": ["id"]
          },
          "output_schema": { "type": "object" },
          "transport": { "kind": "http", "capability": "<capability>" }
        }
      ]
    }
  ]
}

Field	Description
`key`	Lowercase letters, digits, `_` or `-`, starting with a letter.
`version`	A semantic version such as `1.0.0`.
`services`	At least one service. Each has exactly `key`, `name`, `operations` and `surface`.
`operations[].effect`	`none`, `read`, `write` or `mixed`.
`operations[].transport`	`http`, or `mcp` with `capability`, `path` and `tool`.
`surface`	`null` for an API-only tool, or `{ "capability", "path" }` for a web preview.
`state`	Optional. How the tool stores its data.

Start from the files tools init creates. It fills in the parts of tool.json and the manifest that are easy to get wrong.

Use it

A custom tool works like a catalog tool. Add its version to a world, or start it in a tool session. The plan review shows that it runs isolated and what that costs.

firedrill tools definitions
firedrill tools definitions share <version-id> <workspace-id> use

Organization admins can share a tool version with other workspaces. Others can copy it into their own workspace with tools definitions copy.

Tool sessions

Try your tool on its own.

Worlds

Use it in drills.

Build and upload

tool.json

Use it

Share it

Tool sessions

Worlds