Skip to main content

Tool In

Defines a custom tool that can be called by LLM agents, allowing agents to execute workflow logic.

Common Properties​

  • Name - The custom name of the node.
  • Color - The custom color of the node.
  • Delay Before (sec) - Waits in seconds before executing the node.
  • Delay After (sec) - Waits in seconds after executing node.
  • Continue On Error - Automation will continue regardless of any error. The default value is false.

Inputs​

  • Caller ID - (string) Caller ID for correlation, automatically passed by the LLM Agent when the tool is called.
  • Tool Name - (string) Name of the tool (e.g., "get_weather", "search_database").
  • Tool Description - (string) Description of what the tool does. This is shown to the LLM to help it understand when to use the tool.
  • Tool Parameters JSON Schema - (string) JSON schema defining the parameters the tool accepts. This tells the LLM what arguments to provide.

Options​

  • Timeout (seconds) - (number) Maximum wait time in seconds for the tool call to finish. Default: 300.

Outputs​

  • Tool Name - (string) Name of the tool being called.
  • Parameters - (object) Arguments passed by the agent to the tool.

How It Works​

The Tool In node creates a custom tool for agents:

  1. Registration - When connected to an LLM Agent's tools port, registers as an available tool
  2. Schema Definition - Provides the tool name, description, and parameter schema to the agent
  3. Tool Call - When the agent decides to use the tool, it calls it with appropriate arguments
  4. Parameter Extraction - The node receives and outputs the tool parameters
  5. Workflow Execution - The connected workflow executes with the tool parameters
  6. Return - The workflow must end with a Tool Out node to return results to the agent

Common Use Cases​

  • Data Retrieval - Fetch data from databases, APIs, or files
  • Calculations - Perform complex computations
  • Web Search - Search the web or specific websites
  • File Operations - Read, write, or process files
  • External Integrations - Call external services or APIs
  • Workflow Automation - Trigger automated workflows
  • State Management - Read or update session state
  • Validation - Validate data or conditions

Tool Parameters JSON Schema​

The JSON schema defines what parameters the tool accepts. Example:

{
  "type": "object",
  "properties": {
    "location": {
      "type": "string",
      "description": "City and country e.g. Bogotá, Colombia"
    },
    "units": {
      "type": "string",
      "description": "Temperature units (celsius or fahrenheit)",
      "enum": ["celsius", "fahrenheit"]
    }
  },
  "required": ["location"]
}

This tells the LLM:

  • The tool accepts a location parameter (required) and a units parameter (optional)
  • Both are strings
  • The purpose of each parameter
  • Valid values for units

Schema Properties​

  • type - Data type (object, string, number, boolean, array)
  • properties - Object defining each parameter
  • required - Array of required parameter names
  • description - Explains the parameter's purpose
  • enum - Valid values for the parameter

Usage Notes​

  • Must Use Tool Out - Every tool workflow must end with a Tool Out node to return results
  • Connection Required - Connect to an LLM Agent's tools port for the tool to be available
  • Clear Descriptions - Use clear, descriptive tool and parameter descriptions to help the LLM use the tool correctly
  • Schema Accuracy - Ensure the JSON schema accurately represents what your tool expects
  • Parameter Validation - Validate parameters in your workflow to handle unexpected inputs
  • Error Handling - Use error handling to gracefully handle tool failures

Error Handling​

The node will return errors in the following cases:

  • Missing required inputs - Tool Name, Description, or Schema not provided
  • Invalid JSON schema - Schema is not valid JSON
  • Connection errors - Not properly connected to an LLM Agent
  • Parameter errors - Agent provides parameters that don't match the schema

Example Tool Definitions​

Weather Tool:

Tool Name: get_weather
Tool Description: Get the current weather for a location
Tool Parameters JSON Schema:
{
  "type": "object",
  "properties": {
    "location": {
      "type": "string",
      "description": "City and country"
    }
  },
  "required": ["location"]
}

Database Query Tool:

Tool Name: query_database
Tool Description: Query the customer database
Tool Parameters JSON Schema:
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "SQL query to execute"
    },
    "limit": {
      "type": "number",
      "description": "Maximum number of results"
    }
  },
  "required": ["query"]
}

Calculation Tool:

Tool Name: calculate
Tool Description: Perform mathematical calculations
Tool Parameters JSON Schema:
{
  "type": "object",
  "properties": {
    "expression": {
      "type": "string",
      "description": "Mathematical expression to evaluate"
    }
  },
  "required": ["expression"]
}

Example Workflow​

Simple Tool:

Tool In → Process Parameters → Tool Out (result)

API Integration Tool:

Tool In → HTTP Request → Transform Response → Tool Out (data)

Database Tool:

Tool In → Validate Query → Execute Query → Format Results → Tool Out (results)

Error Handling Tool:

Tool In → Try-Catch
  ├─ Success: Process → Tool Out (result)
  └─ Error: Error Handler → Tool Out (error message)

Best Practices​

  • Descriptive Names - Use clear, action-oriented tool names (e.g., "search_products" not "tool1")
  • Detailed Descriptions - Provide comprehensive descriptions so the LLM knows when to use the tool
  • Complete Schemas - Include descriptions for all parameters
  • Required vs Optional - Clearly mark which parameters are required
  • Validation - Validate all parameters before using them
  • Error Messages - Return clear error messages when tools fail
  • Timeouts - Set appropriate timeout values for long-running operations
  • Testing - Test tools with various parameter combinations

Integration with LLM Agents​

To use tools with agents:

  1. Add a Tool In node to your workflow
  2. Define the tool name, description, and parameter schema
  3. Connect the Tool In node to an LLM Agent's tools port
  4. Build the tool workflow
  5. End with a Tool Out node

The agent will automatically discover the tool and can decide to use it based on the description and current context.