# Tools: Create a tool (https://docs.envocal.ai/api-reference/tools/create-a-tool/) > Creates an HTTP tool the tenant's agents can use. Only name, description and config are needed. ## POST `/v1/tenants/{tenantId}/tools` Creates an HTTP tool the tenant's agents can use. Only `name`, `description` and `config` are needed. `config` describes the request (the ToolHttpConfig schema). A tool made here can be opened, tested and saved in the Studio's tool editor, and the other way round, so the config takes what the editor can show. Anything else is refused with a message that says what to write. Arguments the AI model should provide go in `config.variables.agent`, each with a `name` (for example `order_id`). A part of the request takes one with `inputType: "agent"` and that name as its `varName`; a text takes one as `{{order_id}}`. To authenticate, set `credentialId` to a vault credential: its header is added to the request. For any other secret value (an API key in a header of its own), give the header `inputType: "secret"` and the vault secret's id as its `secretId`. A secret can be used in a header only. Never put a secret in the config as a static value. Next: try it with `POST /v1/tenants/{tenantId}/tools/{id}/test`, then give it to an agent with `PUT /v1/tenants/{tenantId}/agents/{id}/tools`. **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. | ### Request body `application/json`: PublicToolCreateDto | Field | Type | | Description | | --- | --- | --- | --- | | `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. Write it for the model. | | `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. Its header is added to the request automatically. | | `config` | ToolHttpConfig | required | The request the tool sends. Required. | ### Request examples **A GET with a value from the AI model in the address**: The model supplies `order_id` when it calls the tool; it fills `{order_id}` in the URL. One fixed query parameter. The vault credential adds its `Authorization` header by itself. ```json { "name": "lookup_order", "description": "Looks up an order by its order number. Use it when the customer asks about an order.", "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": [] } } ``` **A POST with a JSON body and a secret in a header**: The body is built from two values the model supplies (one optional, with allowed values), a fixed value and a text with a system variable in it. The API key comes from a vault secret: the header takes it by the secret's id. ```json { "name": "create_ticket", "displayName": "Create ticket", "description": "Creates a support ticket. Use it when the customer wants a problem followed up.", "channels": [ "phone", "chat" ], "config": { "schemaVersion": 1, "http": { "method": "POST", "url": "https://helpdesk.example.com/api/tickets", "timeoutSeconds": 15, "headers": [ { "key": "X-Api-Key", "type": "string", "inputType": "secret", "secretId": "c41d7f0a-9b6e-4d52-8e13-7a2f5c9b0d34" } ], "query": [], "path": [], "body": { "rootKind": "object", "nodes": [ { "name": "subject", "type": "string", "inputType": "agent", "varName": "subject" }, { "name": "priority", "type": "string", "inputType": "agent", "varName": "priority" }, { "name": "source", "type": "string", "inputType": "static", "value": "voice-agent" }, { "name": "caller", "type": "string", "inputType": "template", "template": "Phone {{system_caller_number}}" } ] } }, "variables": { "agent": [ { "name": "subject", "description": "One sentence describing the problem.", "jsonType": "string", "required": true }, { "name": "priority", "description": "How urgent it is.", "jsonType": "string", "enums": [ "low", "normal", "high" ], "required": false } ], "dynamic": [] }, "responseMapping": [] } } ``` **A tool that runs before the conversation and keeps a value**: Runs when the conversation starts (`availability` is `before`), so it takes no values from the model: the caller's number is a system variable. `responseMapping` keeps the customer's id from the answer in a dynamic variable, for the AI and for later tools. ```json { "name": "lookup_caller", "description": "Finds the customer by the number they call from, before the conversation starts.", "availability": [ "before" ], "channels": [ "phone" ], "config": { "schemaVersion": 1, "http": { "method": "GET", "url": "https://crm.example.com/customers/search", "timeoutSeconds": 5, "headers": [], "query": [ { "name": "phone", "type": "string", "inputType": "system", "varName": "system_caller_number" } ], "path": [], "body": null }, "variables": { "agent": [], "dynamic": [ { "name": "customer_id", "jsonType": "string" } ] }, "responseMapping": [ { "dynamicVar": "customer_id", "jsonPath": "$.data.customer.id" } ] } } ``` **A nested body, a value from an earlier tool, numbers and booleans**: An object and a list in the body, written as `children`. `customer.id` reads the dynamic variable that the `lookupCaller` example stores. Fixed numbers and booleans are written as text (`"30"`, `"true"`); the model's own numbers and booleans are variables of that `jsonType`. ```json { "name": "book_appointment", "displayName": "Book appointment", "description": "Books an appointment for the customer. Use it once the customer has chosen a day and a time.", "channels": [ "phone", "voice_chat" ], "credentialId": "8a6e0c5e-2f43-4c1b-9d7a-5b3f1e2a4c61", "config": { "schemaVersion": 1, "http": { "method": "POST", "url": "https://booking.example.com/api/appointments", "timeoutSeconds": 20, "headers": [ { "key": "X-Source", "type": "string", "inputType": "static", "value": "envocal" } ], "query": [ { "name": "notify", "type": "boolean", "inputType": "static", "value": "true" } ], "path": [], "body": { "rootKind": "object", "nodes": [ { "name": "customer", "type": "object", "inputType": "static", "children": [ { "name": "id", "type": "string", "inputType": "dynamic", "varName": "customer_id" }, { "name": "phone", "type": "string", "inputType": "system", "varName": "system_caller_number" } ] }, { "name": "start", "type": "string", "inputType": "agent", "varName": "start_time" }, { "name": "durationMinutes", "type": "integer", "inputType": "static", "value": "30" }, { "name": "people", "type": "integer", "inputType": "agent", "varName": "people" }, { "name": "firstVisit", "type": "boolean", "inputType": "agent", "varName": "first_visit" }, { "name": "tags", "type": "array", "inputType": "static", "children": [ { "type": "string", "inputType": "static", "value": "voice-agent" }, { "type": "string", "inputType": "agent", "varName": "reason" } ] }, { "name": "note", "type": "string", "inputType": "template", "template": "Booked by phone for customer {{customer_id}}: {{reason}}" } ] } }, "variables": { "agent": [ { "name": "start_time", "description": "Start of the appointment as an ISO 8601 date and time, for example 2026-03-14T09:30:00.", "jsonType": "string", "required": true }, { "name": "people", "description": "How many people are coming.", "jsonType": "integer", "required": true }, { "name": "first_visit", "description": "True if the customer has not been here before.", "jsonType": "boolean", "required": true }, { "name": "reason", "description": "In a few words, what the appointment is for.", "jsonType": "string", "required": true } ], "dynamic": [ { "name": "customer_id", "jsonType": "string" }, { "name": "booking_id", "jsonType": "string" } ] }, "responseMapping": [ { "dynamicVar": "booking_id", "jsonPath": "$.id" } ] } } ``` ### Responses **201** — PublicToolDto: Created. The `Location` header points to the new tool. | 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. **Every problem at once, each with what to write**: `error` is the first problem and `errors` is all of them. Each starts with the field it is about. ```json { "error": "config.http.path[0].varName 'order' is not the name of a variable in config.variables.agent.", "errors": [ "config.http.path[0].varName 'order' is not the name of a variable in config.variables.agent.", "config.http.query[0].value is required for a static value, written as text (\"true\" for a boolean, \"5\" for a number)." ] } ``` **401**: Missing, invalid, revoked or expired API key. **403**: The key lacks the required permission, or the tenant/resource is outside its reach. **409**: A tool with this name already exists in the tenant. **429**: Rate limit exceeded. Retry after the number of seconds in the Retry-After header. ### Example ```bash curl -X POST "https://api.envocal.ai/v1/tenants/current/tools" \ -H "Authorization: Bearer evk_eu_..." \ -H "Content-Type: application/json" \ -d '{"name":"lookup_order","description":"Looks up an order by its order number. Use it when the customer asks about an order.","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":[]}}' ```