Tool Calling

Extend AI capabilities with custom tools.

Overview

Tool calling allows the AI to:

• Execute functions
• Call external APIs
• Access databases
• Perform actions

Defining Tools

Via Dashboard

1. Navigate to Tools
2. Click Add Tool
3. Define:
   • Name
   • Description
   • Parameters
   • Handler

Tool Schema

{
  "name": "search_database",
  "description": "Search the knowledge base for information",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query"
      },
      "limit": {
        "type": "number",
        "default": 10
      }
    },
    "required": ["query"]
  }
}

Tool Types

API Tool

Calls external API:

{
  "type": "api",
  "config": {
    "url": "https://api.example.com/search",
    "method": "GET"
  }
}

Function Tool

Executes code:

{
  "type": "function",
  "config": {
    "handler": "async ({ query }) => { ... }"
  }
}

MCP Tool

From MCP server:

{
  "type": "mcp",
  "config": {
    "server_id": "mcp-server-1",
    "tool_name": "search"
  }
}

How It Works

User: "What's the weather in Tokyo?"
        │
        ▼
┌───────────────────┐
│   AI Reasoning    │
│   "Need weather"  │
└────────┬──────────┘
         │
         ▼
┌───────────────────┐
│   Tool Call       │
│   get_weather     │
│   {"city":"Tokyo"}│
└────────┬──────────┘
         │
         ▼
┌───────────────────┐
│   Execute Tool    │
│   → Weather API   │
└────────┬──────────┘
         │
         ▼
┌───────────────────┐
│   AI Response     │
│   "It's 22°C..."  │
└───────────────────┘

Message Format

Tool Call

{
  "role": "assistant",
  "content": null,
  "tool_calls": [{
    "id": "call_123",
    "type": "function",
    "function": {
      "name": "get_weather",
      "arguments": "{\"city\": \"Tokyo\"}"
    }
  }]
}

Tool Result

{
  "role": "tool",
  "tool_call_id": "call_123",
  "content": "{\"temp\": 22, \"condition\": \"sunny\"}"
}

Best Practices

1. Clear Descriptions

Write descriptive tool descriptions:

{
  "description": "Search the product catalog by name, category, or price range. Returns up to 10 matching products."
}

2. Validate Parameters

Define required fields and types:

{
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "required": ["email"]
}

3. Handle Errors

Return clear error messages:

{
  "error": "Product not found",
  "code": "NOT_FOUND"
}

4. Limit Tool Count

Enable only relevant tools per agent.

API Reference

See Tools API for complete endpoint documentation.