This endpoint allows you to create a new custom tool for your organization. Tools can be endpoint-based (HTTP API calls), Python functions, or AWS Lambda functions.

​
Request Body

The request body structure varies based on the tool type you’re creating:

​
Response

A successful request returns the created tool object:
Response
{
  "id": 123,
  "name": "get_customer_info",
  "display_name": "Customer Information Lookup",
  "description": "Look up customer information by phone number or email",
  "tool_type": "endpoint",
  "configuration": {
    "url": "https://api.yourcompany.com/customers/lookup",
    "method": "GET",
    "headers": {
      "Authorization": "Bearer [REDACTED]",
      "Content-Type": "application/json"
    },
    "timeout_seconds": 30
  },
  "function_definition": {
    "name": "get_customer_info",
    "description": "Look up customer information by phone number or email",
    "parameters": {
      "type": "object",
      "properties": {
        "phone_number": {
          "type": "string",
          "description": "Customer's phone number in E.164 format"
        },
        "email": {
          "type": "string",
          "description": "Customer's email address"
        }
      },
      "required": ["phone_number"]
    }
  },
  "is_active": true,
  "is_public": false,
  "execution_count": 0,
  "success_rate": 0.0,
  "avg_execution_time": 0.0,
  "organization_id": 456,
  "created_by": 789,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

​
Field Descriptions

  • name (string, required): Unique identifier for the tool within your organization
  • display_name (string, required): Human-readable name shown in the UI
  • description (string, required): Clear description of what the tool does
  • tool_type (string, required): Type of tool ("endpoint", "python_function", or "lambda")
  • configuration (object, required): Tool-specific configuration (varies by type)
  • function_definition (object, required): OpenAI function calling schema
  • is_active (boolean, optional): Whether the tool is active (default: true)
  • is_public (boolean, optional): Whether other organizations can see this tool (default: false)
  • timeout_seconds (integer, optional): Maximum execution time (default: 30)
  • retry_attempts (integer, optional): Number of retry attempts on failure (default: 1)

​
Error Responses

400 Bad Request 
{
  "detail": "Tool name 'get_customer_info' already exists in organization"
}
422 Validation Error 
{
  "detail": [
    {
      "loc": ["body", "tool_type"],
      "msg": "value is not a valid enumeration member; permitted: 'endpoint', 'python_function', 'lambda'",
      "type": "type_error.enum"
    }
  ]
}

​
Configuration Examples

​
Best Practices

  1. Naming: Use clear, descriptive names that indicate the tool’s purpose
  2. Security: Never include sensitive data in tool definitions; use environment variables
  3. Testing: Test tools thoroughly before deploying to production
  4. Documentation: Provide clear descriptions and parameter documentation
  5. Error Handling: Design tools to handle failures gracefully
  6. Performance: Set appropriate timeouts and optimize for call-time execution