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

# Custom tools

> Build a simulated version of a service that is not in the catalog, such as your own internal API, and use it in drills.

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](https://docs.firedrill.run/tools/overview.md), 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

**1. Create the package**

```bash theme={null}
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`.

**2. Describe the operations**

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

**3. 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.

**4. Check the package**

```bash theme={null}
firedrill tools validate my-crm
```

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

**5. Upload it**

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

```bash theme={null}
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

```json tool.json theme={null}
{
  "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](https://docs.firedrill.run/build/worlds.md), or start it in a [tool session](https://docs.firedrill.run/tools/sessions.md). The plan review shows that it runs isolated and what that costs.

## Share it

```bash theme={null}
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`.

> [card] [Tool sessions](https://docs.firedrill.run/tools/sessions.md)
>
> Try your tool on its own.

> [card] [Worlds](https://docs.firedrill.run/build/worlds.md)
>
> Use it in drills.


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