# Tools: Create a tool from a template (https://docs.envocal.ai/api-reference/tools/create-a-tool-from-a-template/) > Copies a tool template into a new private tool of the tenant: the request with its static values, the variables, the response mapping, phases, channels and the credential type. The credential and the vault secrets are not copied: set credentialId, and secretId on each header that takes a secret, on the new tool with PUT /v1/tenants/{tenantId}/tools/{id}. ## POST `/v1/tenants/{tenantId}/tool-templates/{templateId}/instantiate` Copies a tool template into a new `private` tool of the tenant: the request with its static values, the variables, the response mapping, phases, channels and the credential type. The credential and the vault secrets are not copied: set `credentialId`, and `secretId` on each header that takes a secret, on the new tool with `PUT /v1/tenants/{tenantId}/tools/{id}`. The copy is the tenant's own. Changing it never changes the template, and later changes to the template don't reach the copy. **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. | | `templateId` | path | required | string (uuid) | Template id (from the template list). | ### Request body `application/json`: PublicToolInstantiateDto | Field | Type | | Description | | --- | --- | --- | --- | | `name` | string | nullable | Function name of the new tool: lower-case letters, digits and `_`, 2 to 64 characters, unique in the tenant. Left out: the template's name. | | `displayName` | string | nullable | The same name written for people, shown in the Studio; it has to give `name`, as when creating a tool. Left out: the template's when it fits the name, else the same as `name`. | | `description` | string | nullable | Description for the AI model. Left out: the template's. | ### Request examples **A copy with names of its own**: The display name is the name written for people. To keep the template's names, send an empty object. ```json { "name": "orders_lookup", "displayName": "Orders lookup" } ``` ### 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**: The copy 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**: No such template visible to the tenant. **409**: A tool with this name already exists in the tenant: choose another `name`. **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/tool-templates/{templateId}/instantiate" \ -H "Authorization: Bearer evk_eu_..." \ -H "Content-Type: application/json" \ -d '{"name":"orders_lookup","displayName":"Orders lookup"}' ```