Skip to main content

Tool Out

Returns results from a custom tool workflow back to the calling agent.

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 from the Tool In node.
  • Result - (object) Tool result to return to the agent. This can be any data type (string, number, object, array).

Outputs​

This node does not have outputs (it terminates the tool workflow).

How It Works​

The Tool Out node completes a tool execution:

  1. Input Reception - Receives the Caller ID from the tool context
  2. Result Processing - Processes the Result input
  3. Control Return - Signals the tool simulation to end
  4. Result Delivery - Returns the result to the agent
  5. Agent Continuation - The agent receives the result and continues processing

Common Use Cases​

  • Returning Data - Return fetched data to the agent
  • Returning Status - Indicate success or failure
  • Error Messages - Return error information when tools fail
  • Computed Results - Return calculation or processing results
  • Confirmation - Confirm that an action was completed

Usage Notes​

  • Required for Tools - Every Tool In workflow must end with a Tool Out
  • No Outputs - This is a terminal node with no output connections
  • Result Required - Unlike Callback Out, Tool Out typically needs a meaningful result
  • Caller ID Match - The Caller ID must match the one from Tool In
  • Synchronous Return - The agent waits for Tool Out to be reached before continuing
  • Single Return - Each tool workflow should have exactly one Tool Out execution path
  • Result Format - The result should match what the agent expects based on the tool's purpose

Error Handling​

The node will return errors in the following cases:

  • Missing Caller ID - Tool context is not properly set
  • Invalid Caller ID - Caller ID doesn't match an active tool call
  • Tool simulation error - Internal error in the tool system

Result Types​

String Results:

"Weather in London: 18°C, Cloudy"

Object Results:

{
  "temperature": 18,
  "condition": "Cloudy",
  "humidity": 65
}

Array Results:

[
  \{"name": "Product A", "price": 29.99\},
  \{"name": "Product B", "price": 39.99\}
]

Boolean Results:

true

Error Results:

{
  "error": "Database connection failed",
  "code": "DB_ERROR"
}

Example Workflows​

Simple Data Retrieval:

Tool In → Fetch Data → Tool Out (data)

API Call:

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

Calculation:

Tool In → Perform Calculation → Tool Out (result)

Conditional Tool:

Tool In → Check Condition
  ├─ If Found: Get Data → Tool Out (data)
  └─ If Not Found: Tool Out (error message)

Error Handling:

Tool In → Try Block
  ├─ Success: Process → Tool Out (result)
  └─ Error: Format Error → Tool Out (error object)

Best Practices​

  • Meaningful Results - Return data that helps the agent accomplish its goal
  • Consistent Format - Use consistent result structures for similar tools
  • Error Information - Include helpful error messages when tools fail
  • Data Validation - Validate results before returning them
  • Keep It Simple - Return only necessary data, avoid bloated results
  • Handle All Paths - Ensure every execution path leads to Tool Out
  • Document Format - Document the expected result format in tool descriptions

Integration Patterns​

With Tool In:

Tool In (parameters)
  ↓
[Tool Processing Logic]
  ↓
Tool Out (result)

With Error Handling:

Tool In
  ↓
Try-Catch
  ├─ Success Path → Tool Out (success result)
  └─ Error Path → Tool Out (error result)

With Validation:

Tool In
  ↓
Validate Parameters
  ├─ Valid → Execute → Tool Out (result)
  └─ Invalid → Tool Out (validation error)

Agent Perspective​

From the agent's perspective:

  1. Agent decides to call a tool based on the conversation
  2. Agent provides parameters according to the tool's schema
  3. Tool workflow executes
  4. Tool Out returns the result
  5. Agent receives the result as text or structured data
  6. Agent uses the result to formulate its response

Result Formatting​

For Text Results:

  • Use clear, readable text
  • Include relevant details
  • Format data appropriately

For Structured Results:

  • Use consistent JSON structures
  • Include descriptive keys
  • Avoid unnecessary nesting

For Error Results:

  • Include error message
  • Optionally include error code
  • Provide actionable information

Troubleshooting​

Agent Doesn't Receive Result:

  • Verify Tool Out is reached in all execution paths
  • Check Caller ID is passed correctly
  • Ensure Result is properly set

Result Not Useful to Agent:

  • Review result format and content
  • Ensure it matches tool's purpose
  • Simplify if too complex

Tool Execution Hangs:

  • Check for infinite loops
  • Ensure Tool Out is reachable
  • Verify timeout settings

Performance Considerations​

  • Execution Time - Tools block agent execution; keep them fast
  • Result Size - Large results may impact agent processing
  • Resource Usage - Minimize resource-intensive operations
  • Timeout - Set appropriate timeout values on Tool In