---
title: "Create an agent tool"
method: POST
path: "/v1/tools"
---

# Create an agent tool

`POST /v1/tools`

## Request

- Base URL: `https://volai.cz`
- URL: `https://volai.cz/v1/tools`
- Auth: HTTP bearer

Creates a tool. `label` is the readable name; the name the model sees is derived from it automatically (`Verify order` -> `verify_order`) and returned in the `name` field. `description` is the only thing the model bases its decision of WHEN to use the tool on - write it as an instruction ("Use when the caller asks where their order is."), 10 to 1000 characters.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `label` string, required: Display name of the webhook tool, also used to derive its name for the agent. Reserved call-control names are not allowed.
  - `description` string, required: Tell the agent when to call this tool and what it does.
  - `url` string, required: Public HTTPS endpoint receiving the tool request. Local/private addresses are rejected; the endpoint must respond within timeoutSecs.
  - `method` string, required: HTTP request method: GET puts parameters in the query string, POST sends JSON. Case-insensitive GET or POST only.
  - `headers` object: Complete map of custom HTTP headers; {} clears them on PATCH. Values are secrets and returned redacted. Header names are case-insensitive and must be unique. host, content-length, x-conversation-id and x-caller-id are reserved.
  - `params` object[]: Complete parameter list. [] removes all parameters on PATCH. Names must be unique.
    - `name` string, required: Name sent to the endpoint: letter or underscore first, then letters, digits or underscores.
    - `type` 'string' | 'number' | 'boolean', required: JSON value type sent to the endpoint.
    - `source` 'llm' | 'caller_number' | 'called_number' | 'constant', required: llm asks the agent to supply the value; caller_number and called_number use call metadata; constant uses constantValue.
    - `description` string: Instructions for an llm-sourced parameter; required for source llm. Explain how to obtain the value from the conversation.
    - `constantValue` string: Fixed text value required for source constant; omit for other sources.
    - `required` boolean: For source llm, whether the parameter must be supplied. Defaults to false.
  - `timeoutSecs` integer: Maximum wait for the endpoint's response during a call, in whole seconds. Defaults to 20.

## Response `200`

Created tool

- object
  - `tool` object, required
    - `id` string, required
    - `name` string, required
    - `label` string, required
    - `description` string, required
    - `url` string, required
    - `method` 'GET' | 'POST', required
    - `headers` object, required
    - `params` object[], required
      - `name` string, required
      - `type` 'string' | 'number' | 'boolean', required
      - `source` 'llm' | 'caller_number' | 'called_number' | 'constant', required
      - `description` string
      - `constantValue` string
      - `required` boolean
    - `timeoutSecs` number, required
    - `createdAt` number, required
    - `updatedAt` number, required
  - `warnings` object[]: Present only when the saved text (agent configuration, draft or tool description), the call variables, the task name or variables, or the trial call prompt contains wording that may come across as impersonating an authority or another institution, or as a request for sensitive information - code agent_misuse_suspected. It never blocks the request; the field is absent when there is nothing to flag.
    - `code` 'agent_misuse_suspected', required
    - `message` object, required
      - `cs` string, required
      - `en` string, required

## Other responses

- `400`: Error codes: tool_limit (account), invalid_tool_name (request), invalid_tool_url (request), private_address (request), invalid_tool_params (request), invalid_tool_headers (request), validation (request).
- `401`: Error codes: unauthorized (request).
- `403`: Error codes: account_suspended (account).
- `409`: Error codes: idempotency_in_progress (busy).
- `429`: Error codes: rate_limited (busy).
- `500`: Error codes: internal_error (service).
- `502`: Error codes: eleven_labs_error (service).

---

[API](https://skmtc.dev/volai/apis/volai-rest-api.md) · [All operations](https://skmtc.dev/volai/apis/volai-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/volai/apis/volai-rest-api/revisions/12029b05e2fa?raw)