---
title: Register tools
description: Turn an API's OpenAPI document into tools your agents can use,
review them in a manifest, publish them, and manage their lifecycle with
hexel.
url: https://hexelstudio.com/docs/cli/register-tools
---
Your agents call your own APIs through tools that you register in a toolkit of your organization. `hexel` registers many tools at once from an API's OpenAPI document, shows you exactly what it will register before it changes anything, and leaves every new tool as a draft until you publish it.
You need permission to write tools in your organization (`tool-gateway:tool:write`).
## Import an OpenAPI document
Point `hexel` at the document, a file or an `https` URL, in JSON or YAML. OpenAPI 3 and Swagger 2.0 both work.
```bash
hexel tools import openapi https://api.example.com/openapi.json --toolkit EXAMPLE --dry-run
```
```text
Toolkit EXAMPLE (Example API) will be created; auth: api_key
ACTION TOOL METHOD PATH WRITES NOTE
create LIST_ORDERS GET /v2/orders no
create GET_ORDER GET /v2/orders/{id} no
create CREATE_ORDER POST /v2/orders yes
3 create
```
Each operation becomes one tool. **WRITES** marks operations that change data at the destination. A **NOTE** shows the first problem that would stop the tool from being published.
Run the same command without `--dry-run`. `hexel` shows the plan again and asks before it registers anything; pass `--yes` to skip the question.
```bash
hexel tools import openapi https://api.example.com/openapi.json --toolkit EXAMPLE
```
The toolkit is created in your organization if it doesn't exist. Every tool starts as a draft, which agents can't use.
Publishing is your approval: only published tools reach your agents.
```bash
hexel tools tool publish --toolkit EXAMPLE --all
```
The registry checks each tool when you publish it, and refuses one it couldn't run, with the reason. Or pass `--publish` to the import to publish the drafts straight away.
Agents call a tool with a connection of its toolkit: see the console's **Connections**, or `hexel tools connection list`.
### Choose operations
| Flag | Registers |
| --- | --- |
| `--read-only` | Only `GET` operations |
| `--include 'GET /orders*'` | Only operations matching the glob: an operationId, `METHOD /path` or `/path`; repeat for several |
| `--exclude '*Admin*'` | Everything except operations matching the glob |
| `--tag orders` | Only operations with one of these tags |
### How operations become tools
| OpenAPI | Tool |
| --- | --- |
| `operationId` | Slug, in capitals: `listOrders` becomes `LIST_ORDERS` |
| `summary`, `description` | Name and description; agents read the description to choose a tool |
| Path, query parameters, JSON or form body | The tool's inputs; path parameters are required |
| Response `200`, `201` or `202` | The tool's output schema |
| Method | `GET` tools are marked as not changing data; every other method as changing it |
| First server, or `--base-url` | The destination, which must be `https` |
| `info.version`, or `--version` | The tool version |
`hexel` skips an operation it can't register as a tool, and says why. That happens for a request body that isn't JSON or a form (a file upload, for example), a body that isn't an object, a `GET` or `DELETE` that requires a body, and a required header or cookie parameter.
### Authentication
`hexel` reads the document's security schemes. The connection's credential is placed the way the scheme describes:
| Security scheme | Placement |
| --- | --- |
| HTTP bearer, OAuth 2, OpenID Connect | `Authorization: Bearer` |
| API key in a header or query parameter | That header or query parameter |
| HTTP basic | `Authorization: Basic`, from the connection's username and password |
Operations whose `security` is empty are registered without authentication. To place the key differently, pass `--auth bearer`, `--auth header:X-Api-Key`, `--auth query:api_key`, `--auth basic` or `--auth none`.
A header name may contain only letters, digits and `-`. If a document puts its key in a header such as `api_key`, the plan warns you and those tools can't be published. Use `--auth` when the API also accepts the key another way.
## Review in a manifest
To review or edit the tools before registering them, write them to a manifest instead:
```bash
hexel tools import openapi spec.yaml --toolkit EXAMPLE --out tools.yaml
```
The manifest is YAML (or JSON, for a `.json` file) with the registry's toolkit and tool fields: change descriptions, remove tools or adjust inputs, then register it:
```bash
hexel tools apply -f tools.yaml --dry-run
hexel tools apply -f tools.yaml --publish
```
Keep the manifest in your repository and run `hexel tools apply` from CI: with `-o json`, `--dry-run` prints the plan as JSON.
## Run it again
Importing or applying again is safe. `hexel` compares each tool with the one already registered:
| Action | When |
| --- | --- |
| `create` | No tool of that slug and version yet |
| `update` | A draft that differs: it is updated |
| `unchanged` | Identical: left alone |
| `blocked` | A published tool that differs: give the manifest a new version (`--version`) |
## Manage the lifecycle
```bash
hexel tools tool list --toolkit EXAMPLE --lifecycle all
hexel tools tool publish GET_ORDER --toolkit EXAMPLE
hexel tools tool retire --toolkit EXAMPLE --all # published tools are deprecated first
hexel tools tool delete --toolkit EXAMPLE --all # drafts and retired tools
hexel tools toolkit delete EXAMPLE
```
Name tools by slug, with `--toolkit` for drafts, or select every tool of a toolkit with `--all`. `retire` and `delete` ask for confirmation.
## MCP servers
To register an MCP server's tools instead, register the server, import its tools, and publish them:
```bash
hexel tools mcp register https://mcp.example.com/mcp --slug example --name "Example MCP"
hexel tools mcp import
hexel tools tool publish --toolkit --all
```
`mcp import` registers each tool as a draft. A server that needs authentication is imported with `--connection` or `--bearer-env`.