> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> Defines custom tools that agents can invoke during conversations.  **Naming:** The tool name must be unique per application.  **Type:** When `doNotExecute` is `true`, the type is set to `tool`. Otherw

# Create Tool

For the complete error reference, see [Error Guide](/rest-api/byo-ai-agents-apis/error-codes).


## OpenAPI

````yaml post /ai-agents/tools
openapi: 3.0.0
info:
  title: AI Agents APIs
  description: API reference for CometChat AI Agents service
  version: '1.0'
servers:
  - url: https://{appId}.api-{region}.cometchat.io/v3
    variables:
      appId:
        default: appId
        description: (Required) App ID
      region:
        enum:
          - us
          - eu
          - in
        default: us
        description: Select Region
security: []
tags:
  - name: ai-agent
    description: ''
paths:
  /ai-agents/tools:
    post:
      tags:
        - Tools
      summary: Create Tool
      description: >-
        Defines custom tools that agents can invoke during conversations.


        **Naming:** The tool name must be unique per application.


        **Type:** When `doNotExecute` is `true`, the type is set to `tool`.
        Otherwise, it is set to `action`.
      operationId: ToolsController_createTool
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolDto'
      responses:
        '201':
          description: Tool created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  _id:
                    type: string
                    example: myapp_myTool
                  appId:
                    type: string
                    example: my-app-id
                  name:
                    type: string
                    example: myTool
                  type:
                    type: string
                    enum:
                      - action
                      - tool
                    example: action
                  displayName:
                    type: string
                    example: My Tool
                  executionText:
                    type: string
                    example: Running my tool...
                  doNotExecute:
                    type: boolean
                    example: false
                  tool:
                    type: object
                    properties:
                      name:
                        type: string
                        example: myTool
                      description:
                        type: string
                        example: A helpful tool
                      parameters:
                        type: object
                        example:
                          type: object
                          properties: {}
                          required: []
                  createdAt:
                    type: integer
                    format: date-time
                  updatedAt:
                    type: integer
                    format: date-time
              example:
                _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'
      security:
        - apiKey: []
components:
  schemas:
    ToolDto:
      type: object
      properties:
        displayName:
          type: string
          description: Display name shown in the UI for this tool
          example: Get Weather
        description:
          type: string
          description: >-
            Description of what the tool does. Required when doNotExecute is
            false.
          example: Fetches current weather data for a given location
        executionText:
          type: string
          description: Text displayed while the tool is executing
          example: Fetching weather data...
        name:
          type: string
          description: >-
            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
        doNotExecute:
          type: boolean
          description: >-
            When true, the tool will not be executed locally and
            parameters/description become optional
          default: false
        parameters:
          description: >-
            Tool parameter definitions. Required when doNotExecute is false, but
            can be an empty object. Must be empty or omitted when doNotExecute
            is true.
          allOf:
            - $ref: '#/components/schemas/ParametersDto'
      required:
        - displayName
        - executionText
        - name
    ParametersDto:
      type: object
      properties:
        type:
          type: string
          enum:
            - object
          description: The type of the parameters object
          example: object
        properties:
          type: object
          description: >-
            Map of parameter property names to their definitions (type and
            description)
          additionalProperties:
            type: object
            properties:
              type:
                type: string
              description:
                type: string
            required:
              - type
              - description
          example:
            username:
              type: string
              description: The username
        required:
          description: List of required parameter property names
          example:
            - username
          type: array
          items:
            type: string
      required:
        - type
        - properties
  securitySchemes:
    apiKey:
      type: apiKey
      description: API Key (i.e. Rest API Key from the Dashboard).
      name: apikey
      in: header

````