> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convocore.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Tool
> Creates a new tool, this route must use the new V3 [endpoints](/api-reference/v3/intro).
## Example Request
```json theme={null}
{
"tool": {
"name": "Get Weather",
"description": "Fetches current weather data for a given location",
"serverUrl": "https://api.example.com/weather",
"method": "GET",
"fields": [
{
"id": "location",
"key": "city",
"type": "string",
"in": "query",
"description": "City name for weather lookup",
"required": true
}
]
}
}
```
`name` and `description` are required. The description helps the AI understand when to use the tool.
Configure `channels` to restrict which platforms can use this tool (e.g., `["web-chat", "whatsapp"]`).
## OpenAPI
````yaml POST /agents/{agentId}/tools
openapi: 3.0.3
info:
title: Convocore OpenAPI
description: Full API reference for Convocore
version: 1.0.4
servers:
- url: https://eu-gcp-api.vg-stuff.com/v3
description: EU Node.js API server
- url: https://na-gcp-api.vg-stuff.com/v3
description: NA Node.js API server
security: []
paths:
/agents/{agentId}/tools:
post:
tags:
- Tools
summary: Add Tool
operationId: toolRouter-addToolToAgent
parameters:
- name: agentId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
tool:
type: object
properties:
isDefault:
type: boolean
description: >-
Indicates whether this tool is the default tool for the
agent. Defaults to false if unspecified.
method:
type: string
enum:
- GET
- POST
- PUT
- PATCH
description: >-
The HTTP method used by this tool. Acceptable values are
'GET', 'POST', 'PUT', or 'PATCH'. Defaults to 'POST' if
unspecified.
name:
type: string
description: >-
The name of the tool, providing a human-readable
identifier for display purposes.
description:
type: string
description: >-
A detailed description of the tool's purpose and
functionality. Helps users understand its role within
the agent.
serverUrl:
type: string
description: >-
The server URL where the tool's operations are
performed. Used for network-based integrations.
serverUrlSecret:
type: string
description: >-
A secret token or key associated with the server URL.
Provides secure access to the tool's backend services.
disabled:
type: boolean
description: >-
Indicates whether the tool is currently disabled. A
disabled tool cannot be used by the agent.
isVapiTool:
type: boolean
description: >-
Indicates whether the tool is a Virtual API (VAPI) tool.
VAPI tools enable interaction with external APIs.
vapiId:
type: string
description: >-
A unique identifier for the VAPI associated with this
tool. Used for integration with specific API endpoints.
isGlobal:
type: boolean
description: >-
If true, this tool is globally accessible to all nodes
and agents. Overrides context-specific restrictions.
variablesIds:
type: array
items:
type: string
description: >-
An array of variable IDs associated with the tool. Each
ID maps to a specific variable used by the tool.
toolsSettings: {}
fields:
type: array
items:
type: object
properties:
in:
type: string
description: >-
Defines the location or context in which the field
is utilized. Common values include 'query',
'body', or 'header'.
type:
type: string
enum:
- string
- number
- boolean
- system
description: >-
Specifies the variable type of the field.
Acceptable values include 'string', 'number',
'boolean', and 'system'.
value:
description: >-
The current assigned value of the field. This
value is optional and supports any type depending
on the field's context.
defaultValue:
description: >-
A predefined value assigned to the field when no
specific value is provided. Useful for ensuring
consistent behavior.
key:
type: string
description: >-
The unique key that identifies this tool field or
variable. Often used for referencing the field
programmatically.
description:
type: string
description: >-
A detailed explanation of the field's purpose and
usage. Helps users understand the field's role in
the system.
required:
type: boolean
description: >-
Indicates whether the presence of this field is
mandatory for successful operation. Defaults to
false if unspecified.
reusable:
type: boolean
description: >-
Denotes whether this field can be reused across
multiple contexts or tools. Useful for reducing
redundancy.
isEnv:
type: boolean
description: >-
Specifies if this field represents an environment
variable, typically used for configuration or
deployment.
isSystem:
type: boolean
description: >-
Indicates whether this field is a system-level
variable, reserved for core operations or internal
use.
isGlobal:
type: boolean
description: >-
If enabled, this field remains globally accessible
to the agent across all operational contexts.
Useful for global constants.
agentId:
type: string
description: >-
References the unique identifier of the agent
associated with this field. Helps in mapping
fields to specific agents.
userId:
type: string
description: >-
References the unique identifier of the user
associated with this field. Useful for
user-specific customizations.
id:
type: string
additionalProperties: false
channels:
type: array
items:
type: string
enum:
- web-chat
- whatsapp
- instagram
- telegram
- discord
- gb-chat
- vapi
- messenger
- voice
- telephony
- outlook
- zoho
- sms
description: The channels that the tool can be used on.
required:
- name
- description
additionalProperties: false
required:
- tool
additionalProperties: false
responses:
'200':
description: Successful response
content:
application/json:
schema:
anyOf:
- type: object
properties:
success:
type: boolean
message:
type: string
data:
type: object
properties:
isDefault:
type: boolean
description: >-
Indicates whether this tool is the default tool
for the agent. Defaults to false if unspecified.
method:
type: string
enum:
- GET
- POST
- PUT
- PATCH
description: >-
The HTTP method used by this tool. Acceptable
values are 'GET', 'POST', 'PUT', or 'PATCH'.
Defaults to 'POST' if unspecified.
id:
type: string
description: >-
A unique identifier for the tool. Ensures distinct
identification within the system.
name:
type: string
description: >-
The name of the tool, providing a human-readable
identifier for display purposes.
description:
type: string
description: >-
A detailed description of the tool's purpose and
functionality. Helps users understand its role
within the agent.
serverUrl:
type: string
description: >-
The server URL where the tool's operations are
performed. Used for network-based integrations.
serverUrlSecret:
type: string
description: >-
A secret token or key associated with the server
URL. Provides secure access to the tool's backend
services.
createdAt:
type: string
description: >-
The timestamp when the tool was created, formatted
as an ISO 8601 string. Useful for tracking tool
lifecycle.
updatedAt:
type: string
description: >-
The timestamp when the tool was last updated,
formatted as an ISO 8601 string. Useful for
versioning and auditing.
disabled:
type: boolean
description: >-
Indicates whether the tool is currently disabled.
A disabled tool cannot be used by the agent.
isVapiTool:
type: boolean
description: >-
Indicates whether the tool is a Virtual API (VAPI)
tool. VAPI tools enable interaction with external
APIs.
vapiId:
type: string
description: >-
A unique identifier for the VAPI associated with
this tool. Used for integration with specific API
endpoints.
isGlobal:
type: boolean
description: >-
If true, this tool is globally accessible to all
nodes and agents. Overrides context-specific
restrictions.
variablesIds:
type: array
items:
type: string
description: >-
An array of variable IDs associated with the tool.
Each ID maps to a specific variable used by the
tool.
agentId:
type: string
description: >-
The unique identifier of the agent associated with
this tool. Helps in linking the tool to a specific
agent.
userId:
type: string
description: >-
The unique identifier of the user associated with
this tool. Used for user-specific configurations
and access control.
backchannellingPhrases:
type: array
items:
type: string
description: >-
An array of phrases used for backchannel
communication. These phrases help in maintaining
conversational flow.
toolsSettings: {}
fields:
type: array
items:
type: object
properties:
id:
type: string
description: >-
A unique identifier for the field, ensuring
it is distinct across the system.
in:
type: string
description: >-
Defines the location or context in which the
field is utilized. Common values include
'query', 'body', or 'header'.
type:
type: string
enum:
- string
- number
- boolean
- system
description: >-
Specifies the variable type of the field.
Acceptable values include 'string',
'number', 'boolean', and 'system'.
value:
description: >-
The current assigned value of the field.
This value is optional and supports any type
depending on the field's context.
defaultValue:
description: >-
A predefined value assigned to the field
when no specific value is provided. Useful
for ensuring consistent behavior.
key:
type: string
description: >-
The unique key that identifies this tool
field or variable. Often used for
referencing the field programmatically.
description:
type: string
description: >-
A detailed explanation of the field's
purpose and usage. Helps users understand
the field's role in the system.
required:
type: boolean
description: >-
Indicates whether the presence of this field
is mandatory for successful operation.
Defaults to false if unspecified.
reusable:
type: boolean
description: >-
Denotes whether this field can be reused
across multiple contexts or tools. Useful
for reducing redundancy.
isEnv:
type: boolean
description: >-
Specifies if this field represents an
environment variable, typically used for
configuration or deployment.
isSystem:
type: boolean
description: >-
Indicates whether this field is a
system-level variable, reserved for core
operations or internal use.
isGlobal:
type: boolean
description: >-
If enabled, this field remains globally
accessible to the agent across all
operational contexts. Useful for global
constants.
agentId:
type: string
description: >-
References the unique identifier of the
agent associated with this field. Helps in
mapping fields to specific agents.
userId:
type: string
description: >-
References the unique identifier of the user
associated with this field. Useful for
user-specific customizations.
required:
- id
additionalProperties: false
channels:
type: array
items:
type: string
enum:
- web-chat
- whatsapp
- instagram
- telegram
- discord
- gb-chat
- vapi
- messenger
- voice
- telephony
- outlook
- zoho
- sms
description: The channels that the tool can be used on.
required:
- id
- name
- description
additionalProperties: false
required:
- success
- message
- data
additionalProperties: false
- {}
default:
$ref: '#/components/responses/error'
security:
- Authorization: []
components:
responses:
error:
description: Error response
content:
application/json:
schema:
type: object
properties:
message:
type: string
code:
type: string
issues:
type: array
items:
type: object
properties:
message:
type: string
required:
- message
additionalProperties: false
required:
- message
- code
additionalProperties: false
securitySchemes:
Authorization:
type: http
scheme: bearer
````