Skip to main content

Tool Out

Returns the result of a tool call to the MCP client. This node completes the tool execution flow by sending the tool's output back to the requesting client.

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.
info

If the ContinueOnError property is true, no error is caught when the project is executed, even if a Catch node is used.

Inputs​

  • Caller ID - Unique identifier for the tool call request. This is automatically provided by the system and matches the request to its response channel.
  • Result - The output of the tool execution. Can be any data type (string, number, object, array). Will be automatically serialized to JSON.

How It Works​

The Tool Out node completes the tool execution workflow:

  1. Request Tracking - Receives the Caller ID that identifies the specific client request
  2. Channel Lookup - Finds the response channel associated with this tool call
  3. Result Serialization - Converts the result to JSON format
  4. Response Creation - Creates an MCP-compliant tool result with the content
  5. Client Delivery - Sends the result back to the waiting client through the response channel

The node automatically marshals any result type to JSON and wraps it in a text content response that MCP clients can process.

Requirements​

  • Must receive a valid Caller ID from the message context
  • Result can be any serializable data type
  • Must be used after a Tool In node in the flow

Error Handling​

The node returns specific errors in the following cases:

  • NoCallerId - Failed to get the Caller ID from the message
  • NoResult - Failed to extract the result from the message
  • NoChannel - No response channel found for the provided Caller ID
  • MarshalError - Failed to serialize the result to JSON

Usage Notes​

Flow Structure​

A typical tool execution flow:

  1. Listen node (with Tool In connected to tools port)
  2. Tool In node (receives call with parameters)
  3. Processing logic (business logic, API calls, data operations)
  4. Tool Out node (sends response)

Result Format​

  • Result can be any type: string, number, boolean, object, array
  • Objects and arrays are automatically converted to JSON
  • Primitives (string, number, boolean) are wrapped in JSON
  • The serialized result is sent as text content to the client

Caller ID Management​

  • Caller ID is automatically managed by the system
  • Pass it through your processing nodes unchanged
  • Don't create or modify Caller IDs manually

Examples​

Example 1: Return Simple String​

Tool In receives:

{
  "tool": "get_status",
  "parameters": {}
}

Processing: Check system status

Tool Out inputs:

  • Caller ID: (from message)
  • Result: "System is operational"

Client receives:

{
  "content": [
    {
      "type": "text",
      "text": "\"System is operational\""
    }
  ]
}

Example 2: Return Object​

Tool In receives:

{
  "tool": "get_user",
  "parameters": {"user_id": "123"}
}

Processing: Query database

Tool Out inputs:

  • Caller ID: (from message)
  • Result:
{
  "id": "123",
  "name": "Alice",
  "email": "alice@example.com",
  "role": "admin"
}

Client receives: JSON object serialized as text

Example 3: Return Array​

Tool In receives:

{
  "tool": "search_products",
  "parameters": {"category": "electronics"}
}

Processing: Search database

Tool Out inputs:

  • Caller ID: (from message)
  • Result:
[
  {"id": 1, "name": "Laptop", "price": 999},
  {"id": 2, "name": "Mouse", "price": 25},
  {"id": 3, "name": "Keyboard", "price": 75}
]

Example 4: Return Structured Result​

Tool In receives:

{
  "tool": "analyze_text",
  "parameters": {"text": "Hello world"}
}

Processing: Text analysis

Tool Out inputs:

  • Caller ID: (from message)
  • Result:
{
  "word_count": 2,
  "character_count": 11,
  "language": "en",
  "sentiment": "neutral"
}

Example 5: Return Error​

Tool In receives:

{
  "tool": "get_weather",
  "parameters": {"location": "Invalid City"}
}

Processing: API call fails

Tool Out inputs:

  • Caller ID: (from message)
  • Result:
{
  "success": false,
  "error": "Location not found",
  "code": "LOCATION_NOT_FOUND"
}

Note: Even errors are returned via Tool Out to ensure clients receive a response.

Best Practices​

  1. Always Respond:

    • Every Tool In should have a corresponding Tool Out
    • Always send a response, even for errors
    • Don't leave clients waiting indefinitely

  2. Result Structure:

    • Use consistent result formats across similar tools
    • Include success/error indicators in the result
    • Provide meaningful error messages

  3. Data Types:

    • Return appropriate data types (don't stringify when not needed)
    • Use objects for structured data
    • Use arrays for lists
    • Use primitives for simple values

  4. Error Handling:

    • Catch exceptions in your tool logic
    • Return structured error objects
    • Include error codes for programmatic handling
    • Provide helpful error messages

  5. Performance:

    • Process requests efficiently
    • Avoid blocking operations
    • Set reasonable timeouts
    • Return results as soon as available

  6. Validation:

    • Validate the result before sending
    • Ensure result is serializable
    • Check for null/undefined values

Common Errors and Solutions​

Error: "NoCallerId - Failed to get caller ID"​

Cause: Caller ID is missing from the message context.

Solution:

  • Ensure Tool Out is connected after Tool In
  • Check message context is passed through the flow
  • Verify no nodes clear the message context

Error: "NoChannel - No channel found for caller ID"​

Cause: Response channel doesn't exist for this request.

Solution:

  • Client may have timed out
  • Reduce processing time before Tool Out
  • Check for excessive delays in the flow

Error: "MarshalError - Failed to marshal result"​

Cause: Result contains data that cannot be serialized to JSON.

Solution:

  • Check for circular references in objects
  • Ensure all values are JSON-serializable
  • Remove functions or undefined values from result
  • Test serialization: JSON.stringify(result)

Error: "NoResult - Failed to get result"​

Cause: Result input is missing or inaccessible.

Solution:

  • Ensure Result input is connected
  • Verify processing logic provides a result
  • Check for null/undefined values

Tips for Effective Use​

  1. Caller ID Handling - Pass Caller ID through processing nodes unchanged
  2. Consistent Formats - Use consistent result structures across tools
  3. Fast Response - Process and respond quickly to avoid timeouts
  4. Error Objects - Return structured error information
  5. Logging - Log tool results for debugging
  6. Testing - Test with various result types and sizes
  7. Serialization - Ensure results are JSON-serializable

Integration Patterns​

Pattern 1: Simple Execution​

Tool In → Execute Logic → Tool Out

Direct tool execution and response.

Pattern 2: Database Operation​

Tool In → Validate → Query DB → Format → Tool Out

Database query with validation and formatting.

Pattern 3: External API Call​

Tool In → Call API → Transform Response → Tool Out

Proxy external API with transformation.

Pattern 4: Error Handling​

Tool In → Try → Execute → Tool Out
           ↓
         Catch → Error Object → Tool Out

Proper error handling with responses.

Pattern 5: Multi-Step Processing​

Tool In → Step 1 → Step 2 → Step 3 → Tool Out

Complex multi-stage tool execution.

Pattern 6: Conditional Logic​

Tool In → Validate → Branch → Process A → Tool Out
                        ↓
                      Process B → Tool Out

Conditional execution paths.

Result Examples​

Success Response​

{
  "success": true,
  "data": {
    "temperature": 22,
    "conditions": "sunny"
  }
}

Error Response​

{
  "success": false,
  "error": "Invalid location",
  "code": "INVALID_LOCATION",
  "details": "Location 'XYZ' not found in database"
}

List Response​

{
  "items": [
    {"id": 1, "name": "Item A"},
    {"id": 2, "name": "Item B"}
  ],
  "total": 2,
  "page": 1
}

Detailed Result​

{
  "status": "completed",
  "result": {
    "processed": 150,
    "successful": 148,
    "failed": 2
  },
  "errors": [
    {"line": 10, "message": "Invalid format"},
    {"line": 25, "message": "Missing required field"}
  ],
  "duration_ms": 1250
}