# Tools: Update a tool (https://docs.envocal.ai/api-reference/tools/update-a-tool/) > Replaces the tool: read it, change what you need and send all of it back, with the revision you read. A field you leave out gets its default, as when creating: no credential, for example. In config, a variable that keeps its name is the same variable as before, and one with a new name is a new variable. Fields you can't set (id, kind, the timestamps) are ignored if you send them. ## PUT `/v1/tenants/{tenantId}/tools/{id}` Replaces the tool: read it, change what you need and send all of it back, with the `revision` you read. A field you leave out gets its default, as when creating: no credential, for example. In `config`, a variable that keeps its name is the same variable as before, and one with a new name is a new variable. Fields you can't set (`id`, `kind`, the timestamps) are ignored if you send them. **Required permission:** `tools:write` ### Parameters | Name | In | | Type | Description | | --- | --- | --- | --- | --- | | `tenantId` | path | required | string | Tenant id, or `current` for the key's own tenant. Must be the key's tenant or one of its sub-tenants. | | `id` | path | required | string (uuid) | Tool id. | ### Request body `application/json`: PublicToolUpdateDto | Field | Type | | Description | | --- | --- | --- | --- | | `revision` | integer | | The `revision` you read. A stale revision gives 409. | | `name` | string | required | Function name the AI model calls: lower-case letters, digits and `_`, 2 to 64 characters, unique in the tenant (e.g. `lookup_order`). | | `displayName` | string | nullable | The same name written for people, shown in the Studio (e.g. `Lookup order` for `lookup_order`). The Studio makes the function name from it, in lower case with `_` for spaces and other characters, and that has to give `name`. Left out: the same as `name`. | | `description` | string | required | Tells the AI model what the tool does and when to use it. | | `preToolSpeech` | string | nullable | Optional sentence the AI says while the tool runs. | | `availability` | `before` \| `during` \| `after`[] | nullable | Phases the tool can be given to an agent in. Left out: `during`. Agent variables can be used only in a tool that is `during` alone. | | `channels` | `chat` \| `voice_chat` \| `phone`[] | nullable | Channels the tool is used on, in every phase (`chat` is text chat): in a conversation on another channel the tool is left out. Left out: all three. | | `visibility` | `private` \| `shared` | nullable | `private` (the default) or `shared`. | | `credentialType` | string | nullable | Type of credential the tool authenticates with. Left out: the type of `credentialId`, or none. | | `credentialId` | string (uuid) | nullable | Vault credential that authenticates the tool's requests. Left out: none. | | `config` | ToolHttpConfig | required | The request the tool sends. Required. A variable that keeps its name is the same variable as before. | ### Request examples **The whole tool again, with the revision that was read**: An update replaces the tool: read it, change what you need (here the description) and send all of it back with its `revision`. A field left out gets its default, so a credential that isn't sent is removed. ```json { "revision": 3, "name": "lookup_order", "description": "Looks up an order by its order number. Use it when the customer asks where an order is.", "preToolSpeech": "One moment, let me look that up.", "credentialId": "8a6e0c5e-2f43-4c1b-9d7a-5b3f1e2a4c61", "config": { "schemaVersion": 1, "http": { "method": "GET", "url": "https://api.example.com/orders/{order_id}", "timeoutSeconds": 10, "headers": [], "query": [ { "name": "expand", "type": "string", "inputType": "static", "value": "items" } ], "path": [ { "name": "order_id", "type": "string", "inputType": "agent", "varName": "order_id" } ], "body": null }, "variables": { "agent": [ { "name": "order_id", "description": "The customer's order number, digits only.", "jsonType": "string", "required": true } ], "dynamic": [] }, "responseMapping": [] } } ``` ### Responses **200** — PublicToolDto: The updated tool, with its new `revision`. | Field | Type | | Description | | --- | --- | --- | --- | | `id` | string (uuid) | | Tool id. Use it to update, delete and test the tool, and in an agent's tool assignments. | | `tenantId` | string | required | Tenant the tool belongs to. | | `kind` | string | required | Where the tool's definition comes from. `custom`: made by the tenant, from scratch or as a copy of a tool template; everything can be changed. More kinds may be added later (e.g. tools of a connected integration): treat a kind you don't know as read-only. | | `name` | string | required | Function name the AI model calls: lower-case letters, digits and `_`, 2 to 64 characters, unique in the tenant (e.g. `lookup_order`). | | `displayName` | string | required | Name shown in the Studio: the same name written for people (e.g. `Lookup order`). | | `description` | string | required | Tells the AI model what the tool does and when to use it. Write it for the model. | | `preToolSpeech` | string | nullable | Optional sentence the AI says while the tool runs, e.g. "One moment, let me look that up." | | `availability` | `before` \| `during` \| `after`[] | required | Phases the tool can be given to an agent in: `before` (runs when the conversation starts), `during` (the AI model calls it), `after` (runs when the conversation has ended). | | `channels` | `chat` \| `voice_chat` \| `phone`[] | required | Channels the tool is used on, in every phase (`chat` is text chat): in a conversation on another channel the tool is left out. | | `visibility` | `private` \| `shared` | required | `private`: only this tenant uses it. `shared`: it is also offered as a tool template to this tenant and every tenant below it. | | `credentialType` | string | nullable | Type of credential the tool authenticates with (the `type` of a vault credential, e.g. `bearer` or `basic`), or null for none. | | `credentialId` | string (uuid) | nullable | Vault credential that authenticates the tool's requests (`GET /v1/tenants/{tenantId}/vault/credentials`), or null. | | `config` | ToolHttpConfig | | The request the tool sends. A header that takes a vault secret holds the secret's id (`secretId`); a secret's value is never returned. | | `revision` | integer | | Changes with every update. Send back the value you read when updating. | | `createdAt` | string (date-time) | | Creation time (UTC). | | `updatedAt` | string (date-time) | | Last update time (UTC). | **400**: Something in the tool can't be saved; `errors` lists every problem. **401**: Missing, invalid, revoked or expired API key. **403**: The key lacks the required permission, or the tenant/resource is outside its reach. **404**: Not found in this tenant. **409**: A stale `revision` (the tool was changed in the meantime: read it again and retry), or another tool already has this name. **429**: Rate limit exceeded. Retry after the number of seconds in the Retry-After header. ### Example ```bash curl -X PUT "https://api.envocal.ai/v1/tenants/current/tools/{id}" \ -H "Authorization: Bearer evk_eu_..." \ -H "Content-Type: application/json" \ -d '{"revision":3,"name":"lookup_order","description":"Looks up an order by its order number. Use it when the customer asks where an order is.","preToolSpeech":"One moment, let me look that up.","credentialId":"8a6e0c5e-2f43-4c1b-9d7a-5b3f1e2a4c61","config":{"schemaVersion":1,"http":{"method":"GET","url":"https://api.example.com/orders/{order_id}","timeoutSeconds":10,"headers":[],"query":[{"name":"expand","type":"string","inputType":"static","value":"items"}],"path":[{"name":"order_id","type":"string","inputType":"agent","varName":"order_id"}],"body":null},"variables":{"agent":[{"name":"order_id","description":"The customer's order number, digits only.","jsonType":"string","required":true}],"dynamic":[]},"responseMapping":[]}}' ```