> ## Documentation Index > Fetch the complete documentation index at: https://docs.burki.dev/llms.txt > Use this file to discover all available pages before exploring further. # Create Tool > Create a custom Burki tool backed by an HTTP endpoint, Python function, or AWS Lambda function for assistants to call during conversations.

Create a Callable Tool

Tools let assistants take action during a conversation. Use this endpoint to register HTTP endpoints, Python functions, or AWS Lambda functions that the AI can call when it needs external data or business logic.

How this endpoint behaves

You register a tool once per organization, then attach it to one or more assistants. Supported tool types are HTTP endpoints, Python functions, and AWS Lambda functions.

Each tool carries a name, description, and configuration block. The assistant uses that metadata when deciding whether to invoke the tool during a conversation.

### Request Body The request body structure varies based on the tool type you're creating: Create a tool that makes HTTP requests to external APIs. ```json Example Request theme={null} { "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 YOUR_API_KEY", "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 } ``` Create a tool that executes custom Python code. ```json Example Request theme={null} { "name": "calculate_loan_payment", "display_name": "Loan Payment Calculator", "description": "Calculate monthly loan payment based on principal, rate, and term", "tool_type": "python_function", "configuration": { "python_code": "def calculate_monthly_payment(principal, annual_rate, years):\n monthly_rate = annual_rate / 100 / 12\n num_payments = years * 12\n \n if monthly_rate == 0:\n return principal / num_payments\n \n payment = principal * (monthly_rate * (1 + monthly_rate) ** num_payments) / ((1 + monthly_rate) ** num_payments - 1)\n \n return {\n 'monthly_payment': round(payment, 2),\n 'total_paid': round(payment * num_payments, 2),\n 'total_interest': round((payment * num_payments) - principal, 2)\n }", "timeout_seconds": 10 }, "function_definition": { "name": "calculate_loan_payment", "description": "Calculate monthly loan payment and totals", "parameters": { "type": "object", "properties": { "principal": { "type": "number", "description": "Loan principal amount in dollars" }, "annual_rate": { "type": "number", "description": "Annual interest rate as percentage (e.g., 5.5 for 5.5%)" }, "years": { "type": "integer", "description": "Loan term in years" } }, "required": ["principal", "annual_rate", "years"] } }, "is_active": true } ``` Create a tool that invokes AWS Lambda functions. ```json Example Request theme={null} { "name": "customer_lookup_lambda", "display_name": "Customer Lookup (Lambda)", "description": "Look up customer data using AWS Lambda function", "tool_type": "lambda", "configuration": { "function_name": "customer-lookup-function", "aws_region": "us-east-1", "invocation_type": "RequestResponse", "timeout_seconds": 30 }, "function_definition": { "name": "customer_lookup", "description": "Look up customer information from database", "parameters": { "type": "object", "properties": { "customer_id": { "type": "string", "description": "Unique customer identifier" }, "phone_number": { "type": "string", "description": "Customer phone number" } }, "required": ["customer_id"] } }, "is_active": true } ``` ### Response A successful request returns the created tool object: ```json Response theme={null} { "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** ```json theme={null} { "detail": "Tool name 'get_customer_info' already exists in organization" } ``` **422 Validation Error** ```json theme={null} { "detail": [ { "loc": ["body", "tool_type"], "msg": "value is not a valid enumeration member; permitted: 'endpoint', 'python_function', 'lambda'", "type": "type_error.enum" } ] } ``` ### Configuration Examples ```json theme={null} { "configuration": { "url": "https://api.example.com/data", "method": "POST", "headers": { "Authorization": "Bearer ${API_KEY}", "Content-Type": "application/json", "User-Agent": "Burki/1.0" }, "timeout_seconds": 45, "follow_redirects": true, "verify_ssl": true, "request_template": { "query": "SELECT * FROM customers WHERE phone = '${phone_number}'", "format": "json" } } } ``` ```json theme={null} { "configuration": { "python_code": "import requests\nimport pandas as pd\nfrom datetime import datetime\n\ndef analyze_customer_data(customer_id):\n # Fetch data from API\n response = requests.get(f'https://api.internal.com/customers/{customer_id}')\n data = response.json()\n \n # Process with pandas\n df = pd.DataFrame(data['transactions'])\n \n return {\n 'total_spent': df['amount'].sum(),\n 'transaction_count': len(df),\n 'last_purchase': df['date'].max(),\n 'avg_order_value': df['amount'].mean()\n }", "timeout_seconds": 15, "max_memory_mb": 128 } } ``` ```json theme={null} { "configuration": { "function_name": "customer-analytics-prod", "aws_region": "us-west-2", "invocation_type": "RequestResponse", "environment_variables": { "DATABASE_URL": "${DB_URL}", "API_KEY": "${EXTERNAL_API_KEY}" }, "timeout_seconds": 60 } } ``` ### 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