# Tools guide (https://docs.envocal.ai/api-reference/tools-guide/) > Create, test, share and assign Agent tools from your own systems with the Envocal API - the calls in order, the request config explained, and four complete examples you can send as they are. Everything in [Creating a Custom Tool](/tools/tools) can also be done from your own systems, or by an AI coding agent, with the [Envocal API](/api-reference): create a tool, test it, share it and give it to an Agent. This page shows the calls in order and four complete tools you can send as they are. In the API, a tool is one object with one `id`. You use that id to change, test and delete the tool, and to give it to an Agent. A tool made with the API can be opened, tested and saved in the Studio's tool editor, and a tool made in the Studio can be read and changed with the API. For that to work, a tool's request holds only what the editor can show. [The request](#the-request) has the rules, and a tool that breaks one is refused with a message that says what to write. ## What you need - An [API key](/vault#api-keys) with **Write** on **Tools**. Add **Read** on **Vault** to look up credentials and secrets, and **Write** on **Agents** to give tools to Agents. - The credential or secret the other system asks for, added in the [Vault](/vault) in the Studio. The API lists their names and ids so you can use them in a tool. It never returns a value, and it can't add or change them. > **Give Tools write only to systems you trust** > > A tool sends a request to an address its author chooses, and carries the credential and secrets attached to > it. A key with **Write** on **Tools** can use the credentials and secrets that the tenant's tools already > use, and with **Read** on **Vault** also every other one in the Vault, and could make a tool that sends them > to any address. The examples use `current` for the key's own tenant. Put a sub-tenant's id there to work in a customer's tenant. ## The calls in order ### 1. Find the credential or secret If the other system needs authentication, look up what the tool will use: ```bash curl https://api.envocal.ai/v1/tenants/current/vault/credentials \ -H "Authorization: Bearer evk_eu_..." ``` ```json [ { "id": "5b0c5f6e-…", "name": "Order system", "type": "bearer" } ] ``` `GET /v1/tenants/current/vault/secrets` lists secrets the same way, with `id` and `name`. Use a **credential** when the other system takes a standard login such as a bearer token or basic auth: its header is added to the request for you. Use a **secret** for any other value that must stay hidden, such as an API key in a header of its own. ### 2. Create the tool `POST /v1/tenants/current/tools` with the tool. Only `name`, `description` and `config` are needed: ```bash curl -X POST https://api.envocal.ai/v1/tenants/current/tools \ -H "Authorization: Bearer evk_eu_..." \ -H "Content-Type: application/json" \ -d @lookup_order.json ``` The answer is `201 Created` with the tool, including its `id` and `revision`. The [examples](#examples) below are complete request bodies. ### 3. Test it `POST /v1/tenants/current/tools/{id}/test` sends the tool's real request once, with the values you give for its variables, and returns what the other system answered: ```bash curl -X POST https://api.envocal.ai/v1/tenants/current/tools/TOOL_ID/test \ -H "Authorization: Bearer evk_eu_..." \ -H "Content-Type: application/json" \ -d '{ "agentVariables": { "order_id": "12345" } }' ``` ```json { "statusCode": 200, "responseHeaders": { "Content-Type": "application/json" }, "bodyText": "{\"id\":\"12345\",\"status\":\"shipped\"}", "bodyJson": { "id": "12345", "status": "shipped" }, "outputVariables": {} } ``` `statusCode` is the other system's answer. A `200` from the API with `statusCode` 401 inside means the request was sent and the other system refused it: check the credential. Send `{}` for a tool without variables. - Give each value under the variable's `name`, as above. - `dynamicVariables` and `systemVariables` take values the same way, for example `{ "systemVariables": { "system_caller_number": "+46701234567" } }`. - `outputVariables` holds what the tool's response mapping read from the answer, under the dynamic variables' names. ### 4. Give it to an Agent An Agent's tools are three lists of tool ids, one per phase. `PUT` replaces all three, so read them first and send them back with the new id added: ```bash curl https://api.envocal.ai/v1/tenants/current/agents/AGENT_ID/tools \ -H "Authorization: Bearer evk_eu_..." ``` ```bash curl -X PUT https://api.envocal.ai/v1/tenants/current/agents/AGENT_ID/tools \ -H "Authorization: Bearer evk_eu_..." \ -H "Content-Type: application/json" \ -d '{ "before": [], "during": ["TOOL_ID"], "after": [] }' ``` | Phase | When the tool runs | | --- | --- | | `before` | When the conversation starts, before the Agent speaks, in list order | | `during` | When the Agent decides to call it during the conversation | | `after` | When the conversation has ended, in list order | A tool can only be placed in a phase that its `availability` includes. ## The fields of a tool | Field | What it is | If you leave it out | | --- | --- | --- | | `name` | The function name the Agent calls: lower-case letters, digits and `_`, 2 to 64 characters, unique in the tenant | Required | | `description` | Tells the Agent what the tool does and when to use it. Write it for the Agent | Required | | `config` | The request the tool sends, see [The request](#the-request) | Required | | `displayName` | The same name written for people, shown in the Studio: `Lookup order` for `lookup_order`. See [The two names](#the-two-names) | Same as `name` | | `preToolSpeech` | A sentence the Agent says while the tool runs | None | | `availability` | The phases the tool can be given to an Agent in: `before`, `during`, `after` | `during` | | `channels` | Where the tool is offered: `chat`, `voice_chat`, `phone` | All three | | `visibility` | `private`, or `shared` to offer it as a template to this tenant and every tenant below it | `private` | | `credentialId` | The Vault credential that authenticates the request | None | | `credentialType` | The type of credential the tool expects, such as `bearer` or `basic` | The type of `credentialId` | A Vault secret is not a field of the tool: the header that sends it holds the secret's id, see [Where a value comes from](#where-a-value-comes-from). A tool you read back also has `id`, `tenantId`, `revision`, `createdAt`, `updatedAt` and `kind`. `kind` is `custom` for the tools a tenant makes itself. More kinds may be added later: treat a kind you don't know as read-only. ### The two names A tool has one name, written two ways: `name` for the Agent (`lookup_order`) and `displayName` for people (`Lookup order`). In the API, `name` is the one you choose, and `displayName` can be left out. The Studio makes the function name from the display name every time it saves a tool: lower case, with `_` for spaces and other characters. So a `displayName` you send has to give your `name` by that rule: | `name` | `displayName` | | | --- | --- | --- | | `lookup_order` | left out | Taken. The display name is `lookup_order` | | `lookup_order` | `Lookup order` or `Lookup Order` | Taken | | `lookup_order` | `Order lookup` | Refused: it gives `order_lookup`. The message says so | A tool renamed in the Studio gets both names changed together, so read a tool before you update it. ## The request `config.http` is the request: `method`, `url`, `timeoutSeconds`, and lists of `headers`, `query` and `path` parameters, plus a `body` for POST, PUT and PATCH. `config.variables` declares the variables the request uses, and `config.responseMapping` says what to keep from the answer. It holds what the Studio's tool editor can show, which is what lets a tool be edited from both sides. The [Create a tool](/api-reference/tools/create-a-tool) page has the complete schema. ### Variables A variable is declared once, in `config.variables`, and the request refers to it by its `name`. | | Agent variable (`config.variables.agent`) | Dynamic variable (`config.variables.dynamic`) | | --- | --- | --- | | What it is | A value the Agent fills in when it calls the tool | A value kept during the conversation, for example from another tool's answer | | `name` | The parameter name the Agent sees: `order_id` | The variable's name, shared between tools and prompts: `customer_id` | | `jsonType` | `string`, `number`, `integer`, `boolean`, `object` or `array` | The same | | Also | `description` (written for the Agent), `required`, `enums` (the allowed values), `example` (the value **Run test** in the Studio starts with) | `description` (a note for people), `placeholder` (the value **Run test** in the Studio starts with) | - A `name` has no spaces and no `{` or `}`, doesn't start with `system_`, and is used once among the tool's variables, agent and dynamic together. So a name alone always says which variable is meant. - To rename a variable, change its `name` and every place in the request that uses it, in the same update. A dynamic variable is shared between tools and prompts by its name, so under a new name it is another variable to them. - Agent variables can be used only in a tool whose `availability` is `during` alone, since it is the Agent that fills them in. ### Where a value comes from Every value in the request says where it comes from with `inputType`: | `inputType` | The value comes from | Set | | --- | --- | --- | | `static` | A fixed value | `value`, always written as text: `"items"`, `"true"`, `"5"` | | `agent` | The Agent, which fills it in when it calls the tool | `varName`: the `name` of an agent variable, such as `order_id` | | `dynamic` | Earlier in the conversation, for example another tool's response | `varName`: the `name` of a dynamic variable, such as `customer_id` | | `system` | The conversation itself | `varName`: the name of a system variable, such as `system_caller_number` | | `secret` | A Vault secret | `secretId`: the secret's `id`, from `GET /v1/tenants/current/vault/secrets` | | `template` | Text with placeholders | `template`: for example `Phone {{system_caller_number}}` | What each part of the request takes: | Part | Its name is in | Types | `inputType` | | --- | --- | --- | --- | | Header | `key` | `string` | `static`, `dynamic`, `secret` | | Query parameter | `name` | `string`, `number`, `integer`, `boolean`, `object`, `array` | `static`, `agent`, `dynamic`, `system`, and `template` for a `string` | | Path parameter | `name` | `string`, `number`, `integer`, `boolean` | `static`, `agent`, `dynamic`, `system` | | Body value | `name` | `string`, `number`, `integer`, `boolean`, `null` | `static`, `agent`, `dynamic`, `system`, and `template` for a `string` | | Body object or array | `name` | `object`, `array` | `static` (it holds `children`), `agent`, `dynamic` | - A variable and the value that takes it have the same type: a `string` query parameter takes a `string` variable. - A path parameter fills a `{name}` in the URL, as in `https://api.example.com/orders/{order_id}`. Every `{name}` in the URL has an item in `path`, and the other way round. - A secret can be used in a header only, and two headers with the same name can't both take one. Never put a password or key in the config as a `static` value: a shared tool's config is copied with every static value in it. - `config.responseMapping` reads values from a JSON response into dynamic variables, for later tools and for the Agent: `{ "dynamicVar": "customer_id", "jsonPath": "$.data.customer.id" }`. **The system variables** All of them are text, so they go in values of type `string`. | `varName` | What it holds | | --- | --- | | `system_caller_number` | The caller's phone number, with country code (E.164) | | `system_caller_region` | The region of the caller's number, such as `SE` | | `system_called_number` | The number that was called, with country code (E.164) | | `system_diversion_number` | The number the call was diverted from, with country code (E.164) | | `system_diversion_region` | The region of the diversion number; empty when the call wasn't diverted | | `system_transcript` | The conversation so far, as text | **Placeholders in a template** A template is text for a `string` value in the query or the body. A placeholder is a variable's name between two braces on each side: - `{{order_id}}`: an agent variable - `{{customer_id}}`: a dynamic variable - `{{system_caller_number}}`: a system variable Example: `"template": "Order {{order_id}} for customer {{customer_id}}"`. A placeholder that is not the name of one of the tool's variables or of a system variable is refused. **The body** `config.http.body` is `{ "rootKind": "object", "nodes": [ … ] }`, or `"rootKind": "array"` for a body that is a list. Each node is one property (or one item of a list): - `name`: the property's name, without spaces and used once within its object. An item of an array needs no name. - `type`: required. `null` is a fixed null and takes nothing else. - `inputType` with `value`, `varName` or `template`, as in the tables above. - `children`: the nodes inside a `static` object or array. - `id`: leave it out in a new node and the server gives the node one. When you update a tool, send the ids back as you read them. A body is for POST, PUT and PATCH. For GET and DELETE, set `"body": null`. **Rules a request must follow** A tool that breaks one of these is answered with `400`, and `errors` says what to write for each: - `method` is required, in capitals: `GET`, `POST`, `PUT`, `PATCH` or `DELETE`. - `timeoutSeconds` is from 3 to 120. - Property names and words such as `static` or `string` are written exactly as in this page, in the same case. - A static `value` is text, also for numbers and booleans: `"5"`, `"true"`. - Every `varName`, every `dynamicVar` and every placeholder is the name of a variable that is declared, of the kind its `inputType` says. - Every header with `inputType` `secret` has the `secretId` of a secret in the tenant's Vault. - The URL holds no `{{…}}` placeholders, only `{name}` for path parameters. ## Examples Each is a complete body for `POST /v1/tenants/current/tools`. The same four are in the [OpenAPI document](https://docs.envocal.ai/openapi.json), as the examples of [Create a tool](/api-reference/tools/create-a-tool), so a coding agent that is given the document has them too. The addresses and the ids are placeholders: replace the URLs, and the ids with ones from your own Vault. ### Look up an order A `GET` with a path parameter the Agent fills in, a fixed query parameter, and a bearer credential. The credential's `Authorization` header is added automatically. ```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": [] } } ``` Test it with `{ "agentVariables": { "order_id": "12345" } }`. ### Create a ticket A `POST` with a JSON body built from two values the Agent provides, a fixed value and a template, and a Vault secret in a header of its own. ```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": [] } } ``` Test it with `{ "agentVariables": { "subject": "Router is offline", "priority": "high" }, "systemVariables": { "system_caller_number": "+46701234567" } }`. The other system receives: ```json { "subject": "Router is offline", "priority": "high", "source": "voice-agent", "caller": "Phone +46701234567" } ``` ### Look up the caller before the call starts A tool for the `before` phase: it runs when the conversation starts, finds the customer by the number they call from, and keeps the customer's id as a dynamic variable for the Agent 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" } ] } } ``` Test it with `{ "systemVariables": { "system_caller_number": "+46701234567" } }`. With a response like `{ "data": { "customer": { "id": "C-42" } } }`, the test's `outputVariables` shows `{ "customer_id": "C-42" }`. ### Book an appointment A `POST` with an object and a list in the body, the customer id that the previous example stored, and numbers and booleans. A fixed number or boolean is written as text (`"30"`, `"true"`). A number or a boolean from the Agent is a variable of that type. ```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" } ] } } ``` Test it with: ```json { "agentVariables": { "start_time": "2026-03-14T09:30:00", "people": 2, "first_visit": true, "reason": "check-up" }, "dynamicVariables": { "customer_id": "C-42" }, "systemVariables": { "system_caller_number": "+46701234567" } } ``` The other system receives: ```json { "customer": { "id": "C-42", "phone": "+46701234567" }, "start": "2026-03-14T09:30:00", "durationMinutes": 30, "people": 2, "firstVisit": true, "tags": ["voice-agent", "check-up"], "note": "Booked by phone for customer C-42: check-up" } ``` ## Change or delete a tool To change a tool, read it, change what you need and send all of it back with `PUT /v1/tenants/current/tools/{id}`, including the `revision` you read: - The whole tool is replaced. A field you leave out gets its default, as when creating: no credential, for example. - `id`, `kind` and the timestamps are ignored if you send them, so you can send back what you read. - A variable is the same variable for as long as it keeps its name. - If someone changed the tool after you read it, you get `409`. Read it again and retry. `DELETE /v1/tenants/current/tools/{id}` removes a tool. While an Agent uses it you get `409`: take it out of the Agents' tool lists first. ## Copy a shared tool A tool set to `shared` is offered as a template to its own tenant and every tenant below it, as with [Use Existing Tool](/tools/tools#use-a-shared-tool) in the Studio. ```bash curl https://api.envocal.ai/v1/tenants/current/tool-templates \ -H "Authorization: Bearer evk_eu_..." ``` Each template shows who shares it, its description, the `credentialType` a copy needs and its `config`. A header that takes a secret is shown without a `secretId`. Make a copy with: ```bash curl -X POST https://api.envocal.ai/v1/tenants/current/tool-templates/TEMPLATE_ID/instantiate \ -H "Authorization: Bearer evk_eu_..." \ -H "Content-Type: application/json" \ -d '{ "name": "orders_lookup", "displayName": "Orders lookup" }' ``` Send `{}` to keep the template's names, or a `name` alone to use it as the display name too. The copy is a `private` tool of your own: the request, the variables, the response mapping, phases and channels are copied, the credential and the secrets are not. Set `credentialId`, and a `secretId` of your own on each header that takes a secret, with a `PUT` on the copy, then test it. Changing the copy never changes the template, and later changes to the template don't reach the copy. ## When a call is refused | Status | Why | What to do | | --- | --- | --- | | `400` on create or update | Something in the tool can't be saved | `errors` lists every problem at once, each with the field it is about and what to write, for example `config.http.path[0].varName 'order' is not the name of a variable in config.variables.agent.` | | `400` on test | The request could not be made | `error` says why: a variable is missing, the credential or a secret isn't set up, the address can't be reached, or the other system didn't answer within `timeoutSeconds` | | `403` | The key lacks the permission, or the tenant is outside its reach | The message names the missing permission | | `404` | No such tool or template in this tenant | Check the id and the tenant in the URL | | `409` | The name is taken, the `revision` is stale, or an Agent still uses the tool | Choose another name, read the tool again, or remove it from the Agents first | | `429` | Too many calls | Wait the number of seconds in the `Retry-After` header. Testing has its own limit of 30 tests a minute per key | **Can the API create credentials and secrets?** No. Credentials and secrets are added and changed in the [Vault](/vault) in the Studio. The API lists their names and ids so a tool can use them, and never returns a value. **Which addresses can a tool call?** Any address that is reachable from the internet, over `http` or `https`. Addresses inside a private network (such as `10.x.x.x` or `192.168.x.x`) and the platform's own internal addresses are refused: the test answers `400` and says so. To reach a system on a private network, contact us at hello@envocal.ai. **How large can a response be?** A tool reads up to 5 MB. A larger response is refused with a message that says so. Ask the other system for less, for example with a query parameter that limits the fields or the number of results. **Does a test count as a conversation?** No. A test sends the tool's request once and starts no conversation. It does reach the other system for real, so a tool that creates or changes something there does it in a test too. **Can I edit an API-made tool in the Studio?** Yes. Tools made with the API and tools made in the Studio are the same tools: both show under **Tools**, open in the tool editor with **Run test** and **Save**, and can be read and changed with the API. When the Studio saves a tool, the tool keeps doing the same thing. These can look different when you read the tool again: - If someone renamed the tool in the Studio, `name` and `displayName` have both changed. See [The two names](#the-two-names). - If someone renamed a variable in the Studio, its new name is in `config.variables` and everywhere the request uses it. - Empty fields the editor keeps are added, such as `example` on an agent variable. **Why is a tool missing from the list?** The list holds the tools the tenant made itself, in the tenant in the URL. A tool of another tenant is not shown, also when it is shared: shared tools are under `tool-templates` until you make a copy. ## Related topics - [Creating a Custom Tool](https://docs.envocal.ai/tools/tools/) - [Complete Examples](https://docs.envocal.ai/tools/examples/) - [Vault](https://docs.envocal.ai/vault/) - [Agents: Tools](https://docs.envocal.ai/agents/tools/)