Tool calling

Connects the Agent to external tools to complete tasks it cannot handle directly. Tool calling blocks

Overview

The Tool calling block enables your agent to interact with external systems, APIs, and custom functions to gather information, perform actions, or execute complex workflows that extend beyond the model’s built-in capabilities. When the tool calling block executes, the AI model analyzes the prompt and automatically determines which tools to use, when to use them, and how to combine the results to complete the requested task. The model can make multiple tool calls in sequence and use the results from one tool to inform subsequent tool calls.

How tool calling works

Tool selection: The model analyzes your prompt and determines which available tools are needed
Parameter extraction: The model extracts the necessary parameters from the prompt and context to call each tool
Sequential execution: Tools are called in the optimal order, with results from previous tools informing subsequent calls
Result synthesis: The model combines all tool results with its own knowledge to generate the final response

To learn more about how tool calling works, see the Tool calling introduction documentation.

Tool types

The tool calling block supports two types of tools:

Function tools: Custom workflows you build within the blueprint using other blocks
Built-in tools: Pre-configured integrations with external services. Currently only Knowledge Graphs are supported.

Function tools

Function tools allow you to define custom logic using other blueprint blocks. Each function tool requires:

Tool name: A unique identifier for the tool
Description: Clear explanation of what the tool does and when to use it
Parameters: Input fields the model should provide when calling the tool
Implementation: The workflow of blocks that execute when the tool is called

When you implement the chain of blocks that make up a function tool, you must use include a Return value block at the end of the chain to return a value to back to the model.

The model uses the tool name and description to determine when to call the tool, and uses the parameter definitions to extract the correct values from the prompt context.

Tool definitions

The tool definition for a Function tool follows the JSON Schema format. You provide the definition when adding the tool to the Tool calling block. Add function tool

The definition has the following structure:

Parameter	Type	Description
`name`	string	The name of the tool
`description`	string	A description of what the tool does and when the model should use it
`parameters`	object	An object containing the tool’s input parameters
`parameters.type`	string	The type of the parameter, which is `object` for a JSON schema
`parameters.properties`	object	An object containing the tool’s parameters in the form of a JSON schema. See below for more details.
`parameters.required`	array	An array of the tool’s required parameters

Example tool definition

Below is an example of a tool definition that gets the details of a package’s shipping status. It takes a tracking number and a carrier name as input parameters and returns the shipping status of the package.

{
  "name": "check_shipping_status",
  "description": "Gets real-time shipping and tracking information for a package",
  "parameters": {
    "type": "object",
    "properties": {
      "tracking_number": {
        "type": "string",
        "description": "The shipping carrier's tracking number"
      },
      "carrier": {
        "type": "string",
        "enum": ["fedex", "ups", "usps", "dhl"],
        "description": "Shipping carrier name"
      }
    },
    "required": ["tracking_number", "carrier"]
  }
}

Knowledge Graph tools

Knowledge Graph tools allow you to connect to one or more Knowledge Graph to get information about a specific topic. To add a Knowledge Graph tool, select the Knowledge Graph(s) you want to use from the dropdown of available Knowledge Graphs. Add knowledge graph tool

Prompt engineering for tool calling

While AI models are highly intelligent and can reason about complex tasks, a well-structured prompt is essential for effective tool calling. The prompt serves as a blueprint that clearly defines what tools are available, guides the model through the decision-making workflow, and specifies the expected output format. Without this guidance, the model might miss important steps, use tools inefficiently, or produce results that don’t match your requirements.

Key elements of effective tool calling prompts:

Clear tool descriptions: Explain what each tool does and when to use it
Decision logic: Provide step-by-step workflow guidance
Output format: Specify the structure and format of the expected response
Context handling: Include relevant background information and constraints

Example

Below is an example of a Tool calling block that is connected to multiple tools that run Python code or call external APIs. Tool calling block example

For a complete walkthrough of building an agent with tool calling, see the Tool calling with external APIs tutorial.

Fields

Name	Type	Control	Default	Description	Options	Validation
Prompt	Text	Textarea	-	The task that needs to be carried out.	-	-
Model	Model Id	-	`palmyra-x5`	-	-	-
Max iterations	Number	-	`10`	-	-	-
Tools	Tools	-	-	-	-

End states

Below are the possible end states of the block call.

Name	Field	Type	Description
Tools	tools	dynamic	Run associated tools.
Success	-	success	If the function doesn’t raise an Exception.
Error	-	error	If the function raises an Exception.

The dynamic end state means that the exact values of this end state change based on how you define the block.

Getting started

Tutorials

Core concepts

User interface

Blueprints

Custom code

Interface block reference

Blueprint block reference

Overview

How tool calling works