Tool calling - Writer AI Studio

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 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. The definition has the following structure:

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.

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. For a complete walkthrough of building an agent with tool calling, see the Tool calling with external APIs tutorial.

Fields

End states

Below are the possible end states of the block call.