OpenAI Tool Eval - Synthreo Builder

---

Overview

The OpenAI Tool Eval node is a downstream companion to the OpenAI GPT node. When the OpenAI GPT node is configured with tool schemas and returns a tool call response, the Tool Eval node intercepts that response, matches the function name, and extracts the parameters passed by the model - making them available to subsequent nodes in your workflow.

The Tool Eval node itself does not call any external service and does not make any decisions. It is purely a parameter extraction and routing container. The OpenAI GPT node does the reasoning and decides which function to call; the Tool Eval node captures and exposes the result of that decision.

---

How Tool Calling Works

1. The OpenAI GPT node is configured with one or more tool schemas in its Tools section. Each schema defines a function name, a description, and the parameters the function accepts.
2. Omit is disabled in the OpenAI GPT node’s Output settings so the full raw API response - including the tool_calls array - is preserved.
3. The model evaluates the user prompt and decides whether to call a tool. If it does, the response contains a tool_calls object with the chosen function name and parameter values rather than a plain text reply.
4. A Tool Eval node downstream is configured with the Match Function Name matching the function name defined in the tool schema.
5. When the workflow reaches the Tool Eval node, it checks whether the OpenAI response contains a tool call matching its configured function name. If the names match, the node captures the parameters and exposes them as output variables.
6. If the model called a different function (or no function at all), this Tool Eval node does not activate. Multiple Tool Eval nodes can be placed in parallel branches - one per possible function - to handle all routing cases.

---

Inputs

The Tool Eval node receives its data from the OpenAI GPT node via the Full Response Property Name field. This must point to the Output Property Name of the upstream OpenAI GPT node (default: gpt_response). The node reads the tool_calls array from that property to find a matching function call.

---

Outputs

The Tool Eval node exposes the extracted tool call parameters as a single JSON object. The name of that object is set by the Output Column Name field.

Downstream nodes reference individual parameters using the syntax:

{{outColumnName.paramName}}

Note that Tool Eval outputs use outColumnName.paramName directly - there is no Out. prefix for Tool Eval node references.

For example, if Output Column Name is weatherTool and the tool schema defines a parameter named city, downstream nodes reference it as {{weatherTool.city}}.

---

Configuration Parameters

Setting	Description	Required	Default
Match Function Name	The function name this node listens for. Must exactly match the function name defined in the OpenAI GPT node’s tool schema. Case-sensitive.	Yes	None
Full Response Property Name	The Output Property Name of the upstream OpenAI GPT node that holds the raw API response (the one with tool_calls). Default is gpt_response.	Yes	None
Output Column Name (outColumnName)	The variable name for this node’s output object. Must be unique across all nodes in the workflow. Individual parameters are referenced as {{outColumnName.paramName}}.	Yes	None

---

Defining Tool Schemas in the OpenAI GPT Node

A tool schema describes the function signature to the model. Each schema includes:

• A function name - this must match the Match Function Name in the Tool Eval node exactly.
• A description - helps the model understand when to call this function.
• A parameters block - a JSON Schema object describing the expected parameters, their types, and which are required.

The model uses these descriptions to decide which tool to call and what values to supply for each parameter. Writing clear, specific descriptions significantly improves reliability.

---

Example Usage

Single Tool - Weather Lookup

Scenario: A user asks “What’s the weather in Paris?” and the workflow should call a weather API.

Setup:

1. In the OpenAI GPT node, define a tool named getWeather with a city string parameter.
2. Disable Omit in the OpenAI GPT node Output settings.
3. Add a Tool Eval node with Match Function Name = getWeather, Full Response Property Name = gpt_response, Output Column Name = weatherTool.
4. Connect a downstream HTTP Client node and reference {{weatherTool.city}} in the request URL.

Flow:

• User asks: “What’s the weather in Paris?”
• OpenAI GPT node calls getWeather with { "city": "Paris" }.
• The Tool Eval node captures city = "Paris".
• The HTTP Client node makes the API call using {{weatherTool.city}}.

Multiple Tools - Branching Workflow

Scenario: The workflow handles multiple user intents - weather lookups and flight bookings.

Setup:

1. Define both getWeather and bookFlight tools in the OpenAI GPT node.
2. Add a getWeather Tool Eval node and a bookFlight Tool Eval node as parallel branches.
3. Each branch proceeds independently based on which function the model called.

Only the Tool Eval node whose Match Function Name matches the model’s chosen function will activate. The other branch remains dormant for that run.

---

Error Handling

• Missing Match Function Name - If this field is blank or does not match the function name in the tool schema exactly, the node will never activate regardless of what the model returns.
• Duplicate Output Column Name - If two nodes in the workflow share the same Output Column Name, variable references will be ambiguous and downstream nodes may receive unexpected values. Every Output Column Name must be unique across the entire workflow.
• Omit still enabled on OpenAI GPT node - If Omit is left on, the raw tool_calls data is stripped from the response and the Tool Eval node has nothing to read. Always disable Omit when using tool calling.
• Parameter type mismatches - If the model returns a parameter as a string but the downstream node expects a number, the workflow may behave unexpectedly. Use strict JSON schemas in the tool definition and validate parameter types in downstream nodes.

---

Best Practices

• Use clear, specific function names that accurately describe the operation. Avoid generic names like doAction or process.
• Write detailed descriptions in tool schemas. The model relies on these to decide when and how to call each function.
• Keep Output Column Names concise, descriptive, and unique across the workflow.
• When the model might call any of several tools, add one Tool Eval node per tool and connect each to its own processing branch.
• Test tool calling with varied user inputs to ensure the model selects the correct function reliably. Adjust descriptions if the model calls the wrong tool or fails to call any tool.
• Use the Custom Script or Transform node after a Tool Eval node if parameter values need type conversion or validation before being used downstream.