Custom Tools

Custom Tools allow you to extend your agents’ capabilities by creating specialized tools tailored to your specific use cases. Build tools that integrate with your APIs, databases, or implement custom business logic.

Overview

The Custom Tool node lets you use tools that you’ve created in Flowise’s built-in tool builder. These tools can execute custom JavaScript/TypeScript code with defined inputs and outputs, giving your agents access to virtually any functionality you can program.

Custom Tools are created separately in Flowise’s Tool Builder interface and then referenced in your workflows using the Custom Tool node.

Creating a Custom Tool

Access Tool Builder

Navigate to the Tools section in the Flowise dashboard and click Create Tool.

Define Tool Metadata

Provide basic information about your tool:

Name: A unique identifier for the tool (e.g., weatherAPI)
Description: Clear description of what the tool does (helps the agent decide when to use it)

Define Input Schema

Specify the parameters your tool accepts using a JSON schema format:

{
  "location": {
    "type": "string",
    "description": "The city name to get weather for"
  },
  "units": {
    "type": "string",
    "enum": ["celsius", "fahrenheit"],
    "description": "Temperature units"
  }
}

Write Tool Function

Implement the tool’s logic in JavaScript:

// Input parameters are available in the 'input' object
const location = input.location;
const units = input.units || 'celsius';

// Your custom logic here
const response = await fetch(
  `https://api.weather.com/v1?location=${location}&units=${units}`,
  {
    headers: { 'API-Key': 'your-api-key' }
  }
);

const data = await response.json();

// Return the result as a string
return `The weather in ${location} is ${data.temperature}°${units === 'celsius' ? 'C' : 'F'}`;

Save Tool

Save your custom tool. It will now be available for use in the Custom Tool node.

Using Custom Tools in Workflows

Configuration

selectedTool

asyncOptions

required

Select the custom tool you want to use from the dropdown list.This list is populated from all tools you’ve created in the Tool Builder.

returnDirect

boolean

When enabled, the tool’s output is returned directly to the user without further agent processing.Use cases:

Tool already returns a well-formatted response
You want to bypass additional LLM processing for speed
Tool output doesn’t need further interpretation

When enabled, the agent will not be able to use the tool’s output for further reasoning or combine it with other tool results.

Adding to an Agent

Add Custom Tool Node

Drag the Custom Tool node from the Tools category onto your canvas.

Select Your Tool

Use the dropdown to select the custom tool you created.

Configure Return Direct (Optional)

Toggle the “Return Direct” option based on your needs.

Connect to Agent

Connect the Custom Tool node to your agent’s tools input.

Custom Tool Examples

Example 1: Weather API Tool

Tool Definition
Implementation

Name: getWeatherDescription:

Get current weather information for a specific city. 
Returns temperature, conditions, and humidity.

Schema:

{
  "city": {
    "type": "string",
    "description": "City name (e.g., 'London', 'New York')"
  }
}

const city = input.city;
const apiKey = process.env.WEATHER_API_KEY;

try {
  const response = await fetch(
    `https://api.openweathermap.org/data/2.5/weather?q=${city}&appid=${apiKey}&units=metric`
  );
  
  if (!response.ok) {
    return `Unable to fetch weather for ${city}`;
  }
  
  const data = await response.json();
  
  return `Weather in ${city}:
  Temperature: ${data.main.temp}°C
  Conditions: ${data.weather[0].description}
  Humidity: ${data.main.humidity}%`;
} catch (error) {
  return `Error fetching weather: ${error.message}`;
}

Example 2: Database Query Tool

Tool Definition
Implementation

Name: queryUserDatabaseDescription:

Query the user database to find information about users by email or ID.
Returns user details including name, email, and registration date.

Schema:

{
  "searchType": {
    "type": "string",
    "enum": ["email", "id"],
    "description": "Type of search to perform"
  },
  "searchValue": {
    "type": "string",
    "description": "Email address or user ID to search for"
  }
}

const { searchType, searchValue } = input;

// Example using a hypothetical database client
const db = await connectToDatabase();

let query;
if (searchType === 'email') {
  query = { email: searchValue };
} else {
  query = { userId: searchValue };
}

try {
  const user = await db.collection('users').findOne(query);
  
  if (!user) {
    return `No user found with ${searchType}: ${searchValue}`;
  }
  
  return `User Found:
  Name: ${user.name}
  Email: ${user.email}
  Registered: ${user.registrationDate}
  Status: ${user.status}`;
} catch (error) {
  return `Database error: ${error.message}`;
} finally {
  await db.close();
}

Example 3: CRM Integration Tool

Tool Definition
Implementation

Name: createCRMTicketDescription:

Create a support ticket in the CRM system. 
Requires customer email, issue description, and priority level.

Schema:

{
  "customerEmail": {
    "type": "string",
    "description": "Customer's email address"
  },
  "issue": {
    "type": "string",
    "description": "Description of the issue"
  },
  "priority": {
    "type": "string",
    "enum": ["low", "medium", "high", "urgent"],
    "description": "Priority level of the ticket"
  }
}

const { customerEmail, issue, priority } = input;
const crmApiKey = process.env.CRM_API_KEY;

const ticket = {
  customer_email: customerEmail,
  description: issue,
  priority: priority,
  status: 'open',
  created_at: new Date().toISOString()
};

try {
  const response = await fetch('https://crm.example.com/api/tickets', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${crmApiKey}`
    },
    body: JSON.stringify(ticket)
  });
  
  const result = await response.json();
  
  return `Ticket created successfully!
  Ticket ID: ${result.ticket_id}
  Priority: ${priority}
  A confirmation email has been sent to ${customerEmail}`;
} catch (error) {
  return `Failed to create ticket: ${error.message}`;
}

Advanced Features

Using Variables

Custom tools can access Flowise variables (API keys, configuration) stored in the system:

// Variables are available in the execution context
const apiKey = $vars.API_KEY;
const apiEndpoint = $vars.API_ENDPOINT;

const response = await fetch(`${apiEndpoint}/data`, {
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

Accessing Flow Information

Tools can access information about the current chatflow:

// Access chatflow ID
const chatflowId = $flow.chatflowId;

// Use it for logging, analytics, or conditional logic
console.log(`Tool executed in chatflow: ${chatflowId}`);

Error Handling

try {
  const result = await riskyOperation();
  return `Success: ${result}`;
} catch (error) {
  // Return user-friendly error message
  // Don't expose internal implementation details
  return `Unable to complete the operation. Please try again later.`;
}

Schema Definition Guide

The schema defines what inputs your tool accepts. It follows JSON Schema format:

String Input
Number Input
Enum/Options
Boolean Input
Array Input

{
  "parameterName": {
    "type": "string",
    "description": "What this parameter does"
  }
}

{
  "quantity": {
    "type": "number",
    "description": "Quantity to order (must be positive)",
    "minimum": 1
  }
}

{
  "priority": {
    "type": "string",
    "enum": ["low", "medium", "high"],
    "description": "Priority level for the task"
  }
}

{
  "sendEmail": {
    "type": "boolean",
    "description": "Whether to send confirmation email"
  }
}

{
  "tags": {
    "type": "array",
    "items": {
      "type": "string"
    },
    "description": "List of tags to apply"
  }
}

Clear descriptions are crucial! The agent uses these descriptions to understand when and how to use your tool. Be specific about:

What the parameter does
Expected format or examples
Valid ranges or options

Best Practices

Tool Design Guidelines

Single Responsibility: Each tool should do one thing well
Clear Naming: Use descriptive names that indicate the tool’s purpose
Detailed Descriptions: Help the agent understand when to use the tool
Input Validation: Validate inputs before processing
Error Handling: Always return meaningful error messages
Return Strings: Tools should return string responses for the agent to interpret
Keep It Simple: Complex tools are harder for agents to use correctly

Common Pitfalls

Vague Descriptions: Agent won’t know when to use the tool
Complex Schemas: Too many parameters confuse the agent
No Error Handling: Failures can break the agent flow
Exposing Secrets: Never hardcode API keys in tool code
Long Execution: Tools should complete quickly (< 30 seconds)

Debugging Custom Tools

Test Independently

Test your tool function with sample inputs before using it in an agent.

Check Logs

Enable verbose logging to see tool inputs and outputs:

console.log('Tool called with:', input);
const result = await yourFunction(input);
console.log('Tool returning:', result);
return result;

Validate Schema

Ensure your schema correctly defines all required parameters.

Monitor Agent Behavior

Watch how the agent uses your tool in verbose mode to identify issues.

Security Considerations

Security Best Practices

Use Environment Variables: Store API keys and secrets in Flowise variables, never in code
Validate Inputs: Always sanitize and validate user inputs to prevent injection attacks
Limit Permissions: Tools should have minimal necessary permissions
Audit Actions: Log tool usage for security monitoring
Rate Limiting: Implement rate limits to prevent abuse
Timeout Handling: Set reasonable timeouts for external API calls

Performance Optimization

Optimization Strategies

Cache Results: Cache frequently requested data to reduce API calls
Parallel Execution: Use Promise.all for independent operations
Minimize Data: Return only necessary information
Connection Pooling: Reuse database connections when possible
Async Operations: Use async/await for I/O operations

Common Use Cases

API Integration

Connect to third-party APIs (weather, payments, CRM, etc.)

Database Operations

Query, insert, or update records in your database

Business Logic

Implement custom business rules and calculations

File Operations

Read, write, or process files and documents

Notifications

Send emails, SMS, or push notifications

Data Transformation

Format, convert, or process data in custom ways

Tool Agent

Build agents that use custom tools effectively

Agent Overview

Learn about agent fundamentals

Calculator Tool

See built-in tool examples

Variables & Secrets

Manage API keys and configuration

Overview

Language Models

Vector Stores

Document Loaders

Agents & Tools

Overview

Creating a Custom Tool

Using Custom Tools in Workflows

Configuration

Adding to an Agent

Custom Tool Examples

Example 1: Weather API Tool

Example 2: Database Query Tool

Example 3: CRM Integration Tool

Advanced Features

Using Variables

Accessing Flow Information

Error Handling

Schema Definition Guide

Best Practices

Debugging Custom Tools

Security Considerations

Performance Optimization

Common Use Cases

API Integration

Database Operations

Business Logic

File Operations

Notifications

Data Transformation

Tool Agent

Agent Overview

Calculator Tool

Variables & Secrets

Build docs developers (and LLMs) love

Overview

Language Models

Vector Stores

Document Loaders

Agents & Tools

​Overview

​Creating a Custom Tool

​Using Custom Tools in Workflows

​Configuration

​Adding to an Agent

​Custom Tool Examples

​Example 1: Weather API Tool

​Example 2: Database Query Tool

​Example 3: CRM Integration Tool

​Advanced Features

​Using Variables

​Accessing Flow Information

​Error Handling

​Schema Definition Guide

​Best Practices

​Debugging Custom Tools

​Security Considerations

​Performance Optimization

​Common Use Cases

API Integration

Database Operations

Business Logic

File Operations

Notifications

Data Transformation

​Related Resources

Tool Agent

Agent Overview

Calculator Tool

Variables & Secrets

Build docs developers (and LLMs) love

Overview

Creating a Custom Tool

Using Custom Tools in Workflows

Configuration

Adding to an Agent

Custom Tool Examples

Example 1: Weather API Tool

Example 2: Database Query Tool

Example 3: CRM Integration Tool

Advanced Features

Using Variables

Accessing Flow Information

Error Handling

Schema Definition Guide

Best Practices

Debugging Custom Tools

Security Considerations

Performance Optimization

Common Use Cases

Related Resources