Custom Tool Format

Custom tools in Cognipeer follow a specific JSON format that defines their properties, actions, API endpoints, and parameters. This document explains the structure and required fields in detail.

JSON Structure Overview

A custom tool definition is a JSON object with the following main sections:

1. Tool metadata: Basic information about the tool
2. Actions: Array of operations the tool can perform
3. API configuration: HTTP endpoints and request details
4. Parameters: Input schema for each action

Complete Example

Below is a complete example of a custom tool definition:

{
  "name": "ExampleTool",
  "label": "Example Tool",
  "actions": [
    {
      "name": "getInfo",
      "description": "Retrieves general information from the Example API.",
      "displayName": "Get General Information",
      "api": {
        "url": "https://api.example.com/v1/info",
        "method": "GET",
        "headers": {
          "Authorization": "Bearer <YOUR_API_KEY>",
          "Content-Type": "application/json"
        }
      },
      "parameters": {
        "type": "object",
        "properties": {
          "infoType": {
            "type": "string",
            "description": "Type of information to retrieve (e.g., 'summary', 'details').",
            "required": true
          }
        }
      }
    },
    {
      "name": "createItem",
      "description": "Creates a new item in the Example system.",
      "displayName": "Create New Item",
      "api": {
        "url": "https://api.example.com/v1/items",
        "method": "POST",
        "headers": {
          "Authorization": "Bearer <YOUR_API_KEY>",
          "Content-Type": "application/json"
        }
      },
      "parameters": {
        "type": "object",
        "properties": {
          "itemName": {
            "type": "string",
            "description": "The name of the item to create.",
            "required": true
          },
          "itemDescription": {
            "type": "string",
            "description": "A brief description of the item.",
            "required": false
          }
        }
      }
    }
  ]
}

Field Definitions

Root Level Properties

Property	Type	Required	Description
name	string	Yes	Unique identifier for the tool. Use camelCase without spaces.
label	string	Yes	Human-readable name for the tool displayed in the UI.
actions	array	Yes	Array of action objects that define the operations the tool can perform.

Action Properties

Each item in the actions array has the following properties:

Property	Type	Required	Description
name	string	Yes	Unique identifier for the action within this tool. Use camelCase.
description	string	Yes	Detailed description of what the action does. This helps the AI understand when to use it.
displayName	string	Yes	Human-readable name for the action displayed in the UI.
api	object	Yes	Configuration for the HTTP request to be made.
parameters	object	Yes	JSON Schema defining the expected input parameters.

API Configuration

The api object defines the HTTP request configuration:

Property	Type	Required	Description
url	string	Yes	Full URL of the API endpoint.
method	string	Yes	HTTP method: "GET", "POST", "PUT", "DELETE", etc.
headers	object	No	HTTP headers to include with the request.

Parameters Schema

The parameters object uses JSON Schema to define the input structure:

Property	Type	Required	Description
type	string	Yes	Almost always "object" for a parameters schema.
properties	object	Yes	Defines each parameter that can be passed to the action.

Each parameter in the properties object has:

Property	Type	Required	Description
type	string	Yes	Data type: "string", "number", "boolean", "array", or "object".
description	string	Yes	Explains the purpose of the parameter. Helps the AI use it correctly.
required	boolean	No	Whether the parameter must be provided. Default is false.
enum	array	No	For string types, limits the values to a specific set of options.
format	string	No	For strings, specifies format like "date-time", "email", etc.

Parameter Types

Custom tools support these parameter types:

String

"customerName": {
  "type": "string",
  "description": "Full name of the customer",
  "required": true
}

Number

"amount": {
  "type": "number",
  "description": "Transaction amount in USD",
  "required": true
}

Boolean

"isPriority": {
  "type": "boolean",
  "description": "Whether this is a priority request",
  "required": false
}

Array

"items": {
  "type": "array",
  "description": "List of item IDs to process",
  "items": {
    "type": "string"
  },
  "required": true
}

Object

"address": {
  "type": "object",
  "description": "Customer shipping address",
  "properties": {
    "street": {
      "type": "string",
      "required": true
    },
    "city": {
      "type": "string",
      "required": true
    },
    "zipCode": {
      "type": "string",
      "required": true
    }
  },
  "required": false
}

Request Flow

When a Peer invokes a custom tool:

1. User asks a question or makes a request
2. Peer determines a custom tool action is needed
3. Peer extracts necessary parameters from the conversation
4. Cognipeer system makes the HTTP request to your API as configured
5. API response is returned to the Peer
6. Peer incorporates the response into its answer to the user

Best Practices

1. Clear Descriptions: Write detailed descriptions for both actions and parameters
2. Specific Names: Use clear, specific action names that describe what they do
3. Required Parameters: Only mark parameters as required if they're truly needed
4. Proper Authentication: Use appropriate API authentication methods
5. Error Handling: Ensure your API returns clear error messages
6. Response Format: Structure API responses for easy parsing by the AI

Next Steps

• Creating Custom Tools: Learn how to build and register custom tools
• Tool Parameters: Detailed guide to parameter configuration
• Examples: Practical examples and implementation patterns