---
title: "Update an agent tool"
method: PATCH
path: "/v1/tools/{id}"
---

# Update an agent tool

`PATCH /v1/tools/{id}`

## Request

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

Updates a tool - all fields optional, only the ones sent are changed. Two things to watch for: `params` and `headers` both replace the entire existing list, and changing `label` also rewrites the name the model knows the tool by - if you reference it in `systemPrompt`, update that at the same time.

## Path parameters

- `id` string, required

## Request body

- object
  - `label` string: Display name of the webhook tool, also used to derive its name for the agent. Reserved call-control names are not allowed.
  - `description` string: Tell the agent when to call this tool and what it does.
  - `url` string: Public HTTPS endpoint receiving the tool request. Local/private addresses are rejected; the endpoint must respond within timeoutSecs.
  - `method` string: 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`

Updated 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: validation (request), invalid_tool_url (request), private_address (request), invalid_tool_params (request), invalid_tool_headers (request).
- `401`: Error codes: unauthorized (request).
- `403`: Error codes: account_suspended (account).
- `404`: Error codes: tool_not_found (account).
- `429`: Error codes: rate_limited (busy).
- `500`: Error codes: internal_error (service).
- `502`: Error codes: eleven_labs_mismatch (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)