Skip to main content

Creating Custom Tools

This guide walks through the process of creating and registering custom tools in the Cognipeer platform, allowing your AI assistants to interact with your external systems.

Step 1: Plan Your Tool​

Before coding, define what your tool will do:

  1. Identify Purpose: What data or actions will this tool provide?
  2. Define Actions: What specific operations should be available?
  3. Determine Parameters: What inputs will each action require?
  4. Plan API Endpoints: What endpoints will serve these actions?

Step 2: Implement Your API​

Develop the API endpoints that will power your custom tool:

  1. Create a new or use an existing API service
  2. Implement secure authentication
  3. Build endpoints for each tool action
  4. Follow the API implementation guidelines
  5. Test the endpoints thoroughly

Your API should:

  • Accept parameters in the format defined by your tool schema
  • Return properly formatted JSON responses
  • Handle errors gracefully
  • Process requests quickly (ideally under 3 seconds)

Step 3: Create the Tool Definition​

Create a JSON definition for your tool following the custom tool format:

{
  "name": "CRMTool",
  "label": "CRM Integration Tool",
  "actions": [
    {
      "name": "getCustomer",
      "description": "Retrieves customer information from the CRM system",
      "displayName": "Get Customer Information",
      "api": {
        "url": "https://api.yourcompany.com/crm/customers",
        "method": "GET",
        "headers": {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
        }
      },
      "parameters": {
        "type": "object",
        "properties": {
          "customerId": {
            "type": "string",
            "description": "Unique identifier of the customer",
            "required": false
          },
          "email": {
            "type": "string",
            "description": "Email address of the customer",
            "required": false
          }
        }
      }
    },
    // Additional actions...
  ]
}

Step 4: Register Your Tool in Cognipeer​

Register your custom tool in the Cognipeer platform:

  1. Log in to the Cognipeer Dashboard
  2. Navigate to Tools > Custom Tools
  3. Click Add New Tool
  4. Enter a name and description for your tool
  5. Paste your JSON tool definition
  6. Click Save Tool

Step 5: Associate Tool with Peers​

Connect your custom tool to specific Peers:

  1. Go to the Peers section in the dashboard
  2. Select the Peer you want to enhance
  3. Navigate to the Tools tab
  4. Enable your custom tool
  5. Save the changes

Step 6: Test Your Tool​

Test that your tool works correctly:

  1. Open a conversation with the associated Peer
  2. Ask a question that should trigger tool usage
  3. Verify that the tool is called with correct parameters
  4. Check that the response is properly incorporated

Example conversation flow:

User: "Can you tell me about customer Jane Smith?"

Peer: [Calls getCustomer tool with {email: "jane.smith@example.com"}]

Peer: "Jane Smith is a Premium tier customer who joined on January 15, 2025. 
She has purchased 3 products in the last 6 months and has an active support ticket 
regarding her recent order #12345."

Debugging Tips​

If your tool isn't working as expected:

  1. Check API Logs: Verify if the API is being called
  2. Review Parameters: Ensure parameters are being passed correctly
  3. Test Directly: Call your API endpoints directly to verify they work
  4. Examine Responses: Check if your API is returning appropriate responses
  5. Review Tool Definitions: Make sure your JSON schema is valid

Security Considerations​

When implementing custom tools:

  1. Use HTTPS: Secure all API endpoints
  2. Secure Authentication: Use strong API authentication
  3. Validate Input: Check all parameters before processing
  4. Rate Limiting: Prevent abuse of your API
  5. Data Privacy: Only return information appropriate for the user

Advanced Features​

Default Parameter Values​

You can set default values for parameters:

"parameters": {
  "type": "object",
  "properties": {
    "limit": {
      "type": "number",
      "description": "Maximum number of results to return",
      "default": 10
    }
  }
}

Dependent Parameters​

Some parameters may depend on others:

"parameters": {
  "type": "object",
  "properties": {
    "searchType": {
      "type": "string",
      "enum": ["name", "email", "id"],
      "description": "Type of search to perform"
    },
    "searchValue": {
      "type": "string",
      "description": "Value to search for based on searchType"
    }
  }
}

Response Templates​

Provide hints for how the AI should format responses:

"responseTemplate": "Customer {name} has been with us since {signupDate}. Account status: {status}."

Example Use Cases​

Common custom tool implementations:

CRM Integration​

  • Get customer details
  • Create/update customer records
  • View purchase history
  • Check support tickets

ERP/Inventory System​

  • Check product availability
  • View pricing information
  • Process orders
  • Check shipping status

Ticketing System​

  • Create support tickets
  • Check ticket status
  • Update ticket information
  • Assign tickets to team members

Calendar/Scheduling​

  • View available time slots
  • Book appointments
  • Reschedule meetings
  • Send calendar invites

Best Practices​

  1. Clear Descriptions: Write detailed action and parameter descriptions
  2. Consistent Naming: Use clear, consistent naming conventions
  3. Appropriate Permissions: Only expose actions that are appropriate for users
  4. Limited Scope: Each tool should have a focused purpose
  5. Regular Updates: Keep your tool definitions and APIs updated
  6. Comprehensive Testing: Test all possible parameter combinations