---
title: "Create a tool"
method: POST
path: "/tool"
tags: ["Tools"]
---

# Create a tool

`POST /tool`

Create a reusable tool in the org Tools library. Two types are supported:
`api_call` and `client_tool` (system tools like transfer/end-call are
configured per-agent, not here). Reference it from an agent by adding its
returned `toolId` to `toolRefs` on the agent config.

Referencing a tool makes it available; it does not force use. The agent only
calls a tool when its prompt tells it to, so describe the tool's purpose and
when to trigger it in the agent's prompt.

## Request body

- CreateToolRequest
  - `definition` RegistryToolDefinition, required — A reusable tool definition for the org Tools registry. Only two types are registry tools: `api_call` (calls your API) and `client_tool` (runs in your app over the websocket). The built-in/system tools — `transfer_call`, `end_call`, `knowledge_base_search`, and the like — are configured per-agent in the agent's Tools tab, not created here.
    - `type` 'api_call' | 'client_tool', required — The registry tool type.
    - `name` string, required — Unique name for the tool (no spaces)
    - `description` string, required — What the tool does — the agent reads this to decide when to call it
    - `enabled` boolean — Whether the tool is enabled
    - `url` string, uri — Required for api_call type. The URL to make the HTTP request to.
    - `method` 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' — Required for api_call type. HTTP method to use.
    - `timeout` integer — Optional for api_call type. Request timeout in milliseconds (1000–30000).
    - `headers` object — Optional for api_call type. Static HTTP headers as a key/value map.
    - `headersArray` object[] — Optional for api_call type. Headers as an array of key/value objects (alternative to `headers` map).
      - `key` string, required
      - `value` string, required
    - `queryParams` object[] — Optional for api_call type. Query parameters to include in the request URL. Values support variable templating like `{{order_id}}`.
      - `key` string, required
      - `value` string, required
    - `requestBody` string — Optional for api_call type. Raw request body as a JSON string. Supports variable templating.
    - `llmParameters` object[] — Optional for api_call type. Parameters the LLM can supply dynamically at runtime.
      - `name` string, required — Parameter name
      - `description` string, required — What the parameter represents
      - `type` 'text' | 'number' | 'boolean' | 'enum', required
      - `values` string[] — Required when type is `enum`. Allowed values.
      - `required` boolean
    - `responseVariables` object[] — Optional for api_call type. Variables to extract from the API response into the agent's variable store.
      - `variableName` string, required — Name to store the extracted value under
      - `jsonPath` string, required — JSON path to extract the value from the response
    - `auth` object — Optional for `api_call` type. Authentication for the outbound request. Credentials are referenced **by secret name** (from the org Secrets vault, see `POST /secret`), never inline. At call time the platform decrypts the secret, injects it into the request, and strips the `auth` block before the config reaches the runtime, cache, or webhooks. `token`, `value`, and `password` below are secret names, not literal values.
      - `type` 'none' | 'bearer' | 'api_key' | 'basic', required — Auth scheme. `bearer` sends `Authorization: Bearer <secret>`; `api_key` sends the secret in a header or query param you name; `basic` sends `Authorization: Basic <base64(username:secret)>`.
      - `token` string — For `bearer`: the name of the secret holding the token.
      - `name` string — For `api_key`: the header or query-param name to send the key under.
      - `location` 'header' | 'query' — For `api_key`: whether the key is sent as a header or a query parameter.
      - `value` string — For `api_key`: the name of the secret holding the key.
      - `username` string — For `basic`: the name of the secret holding the username.
      - `password` string — For `basic`: the name of the secret holding the password.
    - `timeoutMs` integer — Optional for client_tool type. How long the agent waits for `function_call.result` before recovering verbally.
    - `expectsResponse` boolean — Optional for client_tool type. When false, fire-and-forget — the app acts on the event and the agent does not wait for a result.
    - `fillerPhrases` string[] — Optional for client_tool type. Phrases spoken while the tool runs so the pause is not silent.

## Response `201`

Tool created.

- object
  - `status` boolean
  - `data` ToolResource — A tool in the org-level Tools library. Referenced from agents by `toolId` (see `toolRefs` on the agent config). Editing a library tool propagates to every agent that references it.
    - `_id` string — MongoDB id.
    - `toolId` string — Stable public id, format `tool_<24 lowercase alphanumerics>`. This is what agents reference.
    - `organizationId` string
    - `type` string — The tool type (mirrors `definition.type`).
    - `definition` RegistryToolDefinition — A reusable tool definition for the org Tools registry. Only two types are registry tools: `api_call` (calls your API) and `client_tool` (runs in your app over the websocket). The built-in/system tools — `transfer_call`, `end_call`, `knowledge_base_search`, and the like — are configured per-agent in the agent's Tools tab, not created here.
      - `type` 'api_call' | 'client_tool', required — The registry tool type.
      - `name` string, required — Unique name for the tool (no spaces)
      - `description` string, required — What the tool does — the agent reads this to decide when to call it
      - `enabled` boolean — Whether the tool is enabled
      - `url` string, uri — Required for api_call type. The URL to make the HTTP request to.
      - `method` 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' — Required for api_call type. HTTP method to use.
      - `timeout` integer — Optional for api_call type. Request timeout in milliseconds (1000–30000).
      - `headers` object — Optional for api_call type. Static HTTP headers as a key/value map.
      - `headersArray` object[] — Optional for api_call type. Headers as an array of key/value objects (alternative to `headers` map).
        - `key` string, required
        - `value` string, required
      - `queryParams` object[] — Optional for api_call type. Query parameters to include in the request URL. Values support variable templating like `{{order_id}}`.
        - `key` string, required
        - `value` string, required
      - `requestBody` string — Optional for api_call type. Raw request body as a JSON string. Supports variable templating.
      - `llmParameters` object[] — Optional for api_call type. Parameters the LLM can supply dynamically at runtime.
        - `name` string, required — Parameter name
        - `description` string, required — What the parameter represents
        - `type` 'text' | 'number' | 'boolean' | 'enum', required
        - `values` string[] — Required when type is `enum`. Allowed values.
        - `required` boolean
      - `responseVariables` object[] — Optional for api_call type. Variables to extract from the API response into the agent's variable store.
        - `variableName` string, required — Name to store the extracted value under
        - `jsonPath` string, required — JSON path to extract the value from the response
      - `auth` object — Optional for `api_call` type. Authentication for the outbound request. Credentials are referenced **by secret name** (from the org Secrets vault, see `POST /secret`), never inline. At call time the platform decrypts the secret, injects it into the request, and strips the `auth` block before the config reaches the runtime, cache, or webhooks. `token`, `value`, and `password` below are secret names, not literal values.
        - `type` 'none' | 'bearer' | 'api_key' | 'basic', required — Auth scheme. `bearer` sends `Authorization: Bearer <secret>`; `api_key` sends the secret in a header or query param you name; `basic` sends `Authorization: Basic <base64(username:secret)>`.
        - `token` string — For `bearer`: the name of the secret holding the token.
        - `name` string — For `api_key`: the header or query-param name to send the key under.
        - `location` 'header' | 'query' — For `api_key`: whether the key is sent as a header or a query parameter.
        - `value` string — For `api_key`: the name of the secret holding the key.
        - `username` string — For `basic`: the name of the secret holding the username.
        - `password` string — For `basic`: the name of the secret holding the password.
      - `timeoutMs` integer — Optional for client_tool type. How long the agent waits for `function_call.result` before recovering verbally.
      - `expectsResponse` boolean — Optional for client_tool type. When false, fire-and-forget — the app acts on the event and the agent does not wait for a result.
      - `fillerPhrases` string[] — Optional for client_tool type. Phrases spoken while the tool runs so the pause is not silent.
    - `createdAt` string, date-time
    - `updatedAt` string, date-time

## Other responses

- `400` — Invalid input
- `401` — Unauthorized access
- `403` — Forbidden access
- `500` — Internal server error

## Changes

- **2026-09-02** `8546eaa96566` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/smallest-inc/apis/agent-management-api/changes/tool/post.md)

---

[API](https://skmtc.dev/smallest-inc/apis/agent-management-api.md) · [All operations](https://skmtc.dev/smallest-inc/apis/agent-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/smallest-inc/agent-management-api/revisions/8546eaa96566/schema)