Skip to main content
POST
/
ai-agents
/
tools
Create Tool
curl --request POST \
  --url https://{appid}.api-{region}.cometchat.io/v3/ai-agents/tools \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --data '
{
  "displayName": "Get Weather",
  "executionText": "Fetching weather data...",
  "name": "get_weather",
  "description": "Fetches current weather data for a given location",
  "doNotExecute": false,
  "parameters": {
    "type": "object",
    "properties": {
      "username": {
        "type": "string",
        "description": "The username"
      }
    },
    "required": [
      "username"
    ]
  }
}
'
{
  "_id": "myapp_myTool",
  "appId": "my-app-id",
  "name": "myTool",
  "type": "action",
  "displayName": "My Tool",
  "executionText": "Running my tool...",
  "doNotExecute": false,
  "tool": {
    "name": "myTool",
    "description": "A helpful tool",
    "parameters": {
      "type": "object",
      "properties": {},
      "required": []
    }
  },
  "createdAt": "2025-12-01T00:00:00.000Z",
  "updatedAt": "2025-12-01T00:00:00.000Z"
}

Authorizations

​
apikey
string
header
required

API Key (i.e. Rest API Key from the Dashboard).

Body

application/json
​
displayName
string
required

Display name shown in the UI for this tool

Example:

"Get Weather"

​
executionText
string
required

Text displayed while the tool is executing

Example:

"Fetching weather data..."

​
name
string
required

Unique function name for the tool. Must start with a letter, underscore, or dollar sign, followed by alphanumeric characters, underscores, dollar signs, or hyphens.

Pattern: ^[a-zA-Z_$][a-zA-Z0-9_$-]*$
Example:

"get_weather"

​
description
string

Description of what the tool does. Required when doNotExecute is false.

Example:

"Fetches current weather data for a given location"

​
doNotExecute
boolean
default:false

When true, the tool will not be executed locally and parameters/description become optional

​
parameters
object

Tool parameter definitions. Required when doNotExecute is false, but can be an empty object. Must be empty or omitted when doNotExecute is true.

Response

200 - application/json

Tool created successfully

​
_id
string
Example:

"myapp_myTool"

​
appId
string
Example:

"my-app-id"

​
name
string
Example:

"myTool"

​
type
enum<string>
Available options:
action,
tool
Example:

"action"

​
displayName
string
Example:

"My Tool"

​
executionText
string
Example:

"Running my tool..."

​
doNotExecute
boolean
Example:

false

​
tool
object
​
createdAt
string<date-time>
​
updatedAt
string<date-time>