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 can also be done from your own systems, or by an AI coding agent, with the Envocal API: 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 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 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 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
Find the credential or secret
If the other system needs authentication, look up what the tool will use:
curl https://api.envocal.ai/v1/tenants/current/vault/credentials \
-H "Authorization: Bearer evk_eu_..."[
{ "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.
Create the tool
POST /v1/tenants/current/tools with the tool. Only name, description and config are needed:
curl -X POST https://api.envocal.ai/v1/tenants/current/tools \
-H "Authorization: Bearer evk_eu_..." \
-H "Content-Type: application/json" \
-d @lookup_order.jsonThe answer is 201 Created with the tool, including its id and revision. The
examples below are complete request bodies.
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:
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" } }'{
"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. dynamicVariablesandsystemVariablestake values the same way, for example{ "systemVariables": { "system_caller_number": "+46701234567" } }.outputVariablesholds what the tool's response mapping read from the answer, under the dynamic variables' names.
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:
curl https://api.envocal.ai/v1/tenants/current/agents/AGENT_ID/tools \
-H "Authorization: Bearer evk_eu_..."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 | Required |
displayName | The same name written for people, shown in the Studio: Lookup order for lookup_order. See 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.
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 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
namehas no spaces and no{or}, doesn't start withsystem_, 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
nameand 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
availabilityisduringalone, 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
stringquery parameter takes astringvariable. - A path parameter fills a
{name}in the URL, as inhttps://api.example.com/orders/{order_id}. Every{name}in the URL has an item inpath, 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
staticvalue: a shared tool's config is copied with every static value in it. config.responseMappingreads values from a JSON response into dynamic variables, for later tools and for the Agent:{ "dynamicVar": "customer_id", "jsonPath": "$.data.customer.id" }.
Examples
Each is a complete body for POST /v1/tenants/current/tools. The same four are in the
OpenAPI document, as the examples of 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.
{
"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.
{
"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:
{ "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.
{
"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.
{
"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:
{
"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:
{
"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,kindand 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 in the Studio.
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:
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 |
API Reference
Provision tenants, agents and their tools, knowledge bases and phone numbers, and read conversations and usage, from your own systems.
MCP server
Connect an AI assistant to Envocal with the Model Context Protocol, and let it build and manage Agents, tools and knowledge bases while you talk to it. Add Envocal to Claude or ChatGPT as a custom connector and sign in, or connect Claude Code, Cursor or VS Code with an API key.