Tool In

Defines a tool that can be called by MCP clients. Tools are executable functions that perform specific operations when invoked by AI applications. Tool In nodes receive call requests with parameters and trigger your automation workflows to execute the tool 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.

info

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

Inputs

• Tool Name - The unique name of the tool. This identifies the tool to MCP clients. Must be unique within the server.
• Tool Description - A description explaining what the tool does, its purpose, and when to use it. This helps AI systems understand when to call the tool.
• Tool In Arguments JSON Schema - A JSON Schema definition specifying the input parameters the tool accepts. This follows OpenAI function calling schema format.

Outputs

• Tool Name - The name of the tool that was called by the client.
• Parameters - An object containing all arguments passed by the client when calling the tool.

How It Works

When a Tool In node is connected to a Listen node's tools port:

1. Registration - The tool is registered with the MCP server at startup using the name, description, and argument schema
2. Discovery - Clients can discover the tool via ListTools
3. Client Call - When a client calls the tool with arguments
4. Validation - Arguments are validated against the JSON Schema
5. Triggering - The Tool In node receives the call and outputs the tool name and parameters
6. Processing - Your flow executes the tool logic
7. Response - A Tool Out node sends the result back to the client

JSON Schema Format

The Tool In Arguments JSON Schema defines the tool's input parameters using JSON Schema (draft-07). This is the same format used by OpenAI function calling.

Example schema:

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

Requirements

• Must be connected to a Listen node's tools port
• Tool Name must be unique within the server
• Tool In Arguments JSON Schema must be valid JSON Schema
• Schema should accurately describe expected parameters

Usage Notes

Tool Design

Good Tool Characteristics:

• Single, well-defined purpose
• Clear input/output contract
• Meaningful error messages
• Reasonable execution time
• Idempotent when possible

Tool Naming:

• Use descriptive, action-oriented names (e.g., get_weather, send_email, query_database)
• Use lowercase with underscores
• Avoid ambiguous or overly generic names

Schema Design

Required vs Optional Parameters:

• Mark essential parameters as required
• Make parameters optional when reasonable defaults exist
• Document default behavior in descriptions

Parameter Types:

• Use appropriate JSON Schema types: string, number, integer, boolean, array, object
• Use enum for limited sets of values
• Use pattern for string validation
• Use minimum/maximum for number ranges

Descriptions:

• Every parameter should have a clear description
• Include examples of valid values
• Mention any constraints or formatting requirements

Examples

Example 1: Weather Tool

Configuration:

• Tool Name: get_weather
• Tool Description: Get current weather for a location
• Tool In Arguments JSON Schema:

{
  "type": "object",
  "properties": {
    "location": {
      "type": "string",
      "description": "City and country, e.g. Paris, France"
    },
    "unit": {
      "type": "string",
      "enum": ["celsius", "fahrenheit"],
      "description": "Temperature unit (default: celsius)"
    }
  },
  "required": ["location"]
}

Client Call:

{
  "name": "get_weather",
  "arguments": {
    "location": "Tokyo, Japan",
    "unit": "celsius"
  }
}

Tool In Outputs:

• Tool Name: get_weather
• Parameters: {"location": "Tokyo, Japan", "unit": "celsius"}

---

Example 2: Database Query Tool

Configuration:

• Tool Name: query_database
• Tool Description: Execute a read-only SQL query on the database
• Tool In Arguments JSON Schema:

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "SQL SELECT query to execute"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000,
      "description": "Maximum number of rows to return (default: 100)"
    }
  },
  "required": ["query"]
}

Use Case: Allow AI to query database while enforcing safety constraints.

---

Example 3: Send Email Tool

Configuration:

• Tool Name: send_email
• Tool Description: Send an email message
• Tool In Arguments JSON Schema:

{
  "type": "object",
  "properties": {
    "to": {
      "type": "string",
      "description": "Recipient email address"
    },
    "subject": {
      "type": "string",
      "description": "Email subject line"
    },
    "body": {
      "type": "string",
      "description": "Email body content"
    },
    "priority": {
      "type": "string",
      "enum": ["low", "normal", "high"],
      "description": "Email priority (default: normal)"
    }
  },
  "required": ["to", "subject", "body"]
}

---

Example 4: File Search Tool

Configuration:

• Tool Name: search_files
• Tool Description: Search for files matching criteria
• Tool In Arguments JSON Schema:

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Directory path to search in"
    },
    "pattern": {
      "type": "string",
      "description": "File name pattern (supports wildcards)"
    },
    "file_type": {
      "type": "string",
      "enum": ["file", "directory", "any"],
      "description": "Type of items to find (default: file)"
    },
    "max_results": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Maximum results to return (default: 10)"
    }
  },
  "required": ["path", "pattern"]
}

---

Example 5: Complex Data Processing Tool

Configuration:

• Tool Name: process_data
• Tool Description: Process data with specified transformations
• Tool In Arguments JSON Schema:

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Array of data objects to process"
    },
    "operations": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["filter", "sort", "aggregate", "transform"]
      },
      "description": "List of operations to apply"
    },
    "config": {
      "type": "object",
      "description": "Configuration options for operations"
    }
  },
  "required": ["data", "operations"]
}

Best Practices

1. Tool Naming:

   • Use verb-noun format (e.g., get_weather, send_email, update_record)
   • Be specific and descriptive
   • Use consistent naming conventions across tools

2. Descriptions:

   • Clearly explain what the tool does
   • Mention any side effects (writes to database, sends emails, etc.)
   • Include usage examples in the description
   • Document expected behavior and limitations

3. Schema Design:

   • Make schemas as specific as possible
   • Use appropriate constraints (enum, pattern, min/max)
   • Provide helpful parameter descriptions
   • Mark truly required parameters as required
   • Use defaults for optional parameters

4. Parameter Validation:

   • Let the schema handle basic validation
   • Add custom validation in your flow for complex rules
   • Return clear error messages for invalid inputs

5. Safety:

   • Limit scope of what tools can do
   • Implement authorization checks
   • Validate all inputs thoroughly
   • Use read-only operations when possible
   • Rate limit expensive operations

6. Error Handling:

   • Catch and handle errors gracefully
   • Return structured error messages via Tool Out
   • Log errors for debugging
   • Don't expose sensitive information in errors

7. Performance:

   • Keep tools focused and efficient
   • Set reasonable timeouts
   • Consider async processing for long-running operations
   • Cache results when appropriate

Common Errors and Solutions

Error: "Tool name already exists"

Cause: Two Tool In nodes have the same Tool Name.

Solution:

• Ensure each Tool In node has a unique name
• Check all Tool In nodes connected to the Listen node
• Use descriptive, specific names to avoid conflicts

Error: "Invalid JSON Schema"

Cause: The Tool In Arguments JSON Schema is not valid JSON.

Solution:

• Validate JSON syntax using a JSON validator
• Ensure all quotes are properly escaped
• Check for trailing commas
• Verify schema structure matches JSON Schema specification

Error: "Parameter validation failed"

Cause: Client provided arguments that don't match the schema.

Solution:

• Check that client arguments match schema types
• Verify required parameters are provided
• Ensure enum values are from allowed set
• Check number ranges against min/max constraints

Tips for Effective Use

1. Start Simple - Begin with basic tools, add complexity as needed
2. Test Thoroughly - Test with various valid and invalid inputs
3. Document Well - Clear descriptions help AI systems use tools correctly
4. Version Tools - Use tool names like send_email_v2 for breaking changes
5. Monitor Usage - Log tool calls for debugging and analytics
6. Secure By Default - Implement security checks in your flow
7. Handle Errors - Always return responses, even for errors
8. Keep Focused - Each tool should do one thing well

Schema Examples

Simple String Parameter

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "Message to process"
    }
  },
  "required": ["message"]
}

Number with Constraints

{
  "type": "object",
  "properties": {
    "temperature": {
      "type": "number",
      "minimum": -273.15,
      "maximum": 100,
      "description": "Temperature in Celsius"
    }
  },
  "required": ["temperature"]
}

Enum Selection

{
  "type": "object",
  "properties": {
    "format": {
      "type": "string",
      "enum": ["json", "xml", "csv"],
      "description": "Output format"
    }
  },
  "required": ["format"]
}

Array of Objects

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {"type": "string"},
          "value": {"type": "number"}
        }
      },
      "description": "List of items to process"
    }
  },
  "required": ["items"]
}

Optional Parameters with Defaults

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "Text to analyze"
    },
    "language": {
      "type": "string",
      "description": "Language code (default: en)"
    },
    "detailed": {
      "type": "boolean",
      "description": "Return detailed analysis (default: false)"
    }
  },
  "required": ["text"]
}