Tutorial: Using tools | PolyAI Platform

Level 2 – Lesson 2 of 8 – This lesson explains what tools are, why they exist, and how the LLM uses them.

Lesson

Level 2 · Intermediate · 20 min

By the end you will understand the full request-response loop and be able to create and reference a tool correctly.

In Agent Studio, tools are defined as Python functions – “tool” is the UI name and “function” is the code identifier. This lesson uses both interchangeably.

Why tools exist

The Agent tab (personality, role, rules) only gets you so far. Without tools, the agent can’t retrieve user data, execute actions, save state, or integrate with external systems.

Prompt engineering also doesn’t scale – putting dozens of user journeys into one rules box gives the LLM too much context and makes it harder to reason about any single scenario.

Tools solve both problems: external integration and fine-grained control over what the LLM knows and does at each step.

How LLMs use tools

Before looking at Agent Studio specifically, it helps to understand how LLMs use tools in general – because this pattern is the same across all modern AI systems.

An LLM can produce two kinds of output:

Text output

The model speaks to the user using natural language.

“The weather in Paris is usually mild in October.”

Tool call

The model communicates with a system – a function, API, or piece of code – to fetch data or trigger an action.

call: get_weather with {city: "Paris"}

The LLM mediates between the user and the system. It takes a user request, decides whether it needs to call a tool to answer it, calls that tool, receives a result, and then reports the result back to the user as text.

This is the core loop that powers almost everything beyond basic FAQ responses.

Check your understanding

What is the difference between a text output and a tool call from an LLM?

Text outputs go to the user; tool calls go to a system
Tool calls are more reliable than text outputs
Text outputs are only used for greetings
There is no practical difference

Answer: Text outputs go to the user; tool calls go to a system

Text outputs are user-facing – the agent speaking. Tool calls are system-facing – the agent communicating with Python code or an external API to fetch data or trigger an action.

Creating a function in Agent Studio

In Agent Studio, tools are called functions. You write them in Python and they are available for the LLM to call during a conversation.

To create a function, go to Tools and click the + button.

Every function has:

Name – how the function is identified (used by the LLM to decide when to call it)
Description – what the function does (also read by the LLM when deciding whether to call it)
Parameters – the inputs the function needs, each with a name, description, and type
Python code – what the function actually does when called

The LLM reads the function name, description, and parameter descriptions when deciding whether to call the function and what to pass as arguments. Name and describe everything clearly — this directly affects whether the LLM uses your function correctly.

Example: a simple addition function

def add_two_numbers(conv, first_number: float, second_number: float) -> str:
    total = first_number + second_number
    return f"The total is {total}"

Parameters:

first_number – The first number the user wants to add (type: number)
second_number – The second number the user wants to add (type: number)

Functions called by the LLM must return either a string or a dictionary with specific keys. Returning an integer, list, or other type will cause an error that the LLM will encounter and retry up to three times before giving up.

Making a function visible to the LLM

Creating a function is not enough. The LLM will not call a function it does not know exists.

To make a function available to the LLM, you must reference it somewhere – in a topic action, a flow step, or directly in the Behavior field using the @function_name syntax.

When you reference a function, Agent Studio highlights it and registers it in the LLM request. The LLM will then see the function’s full definition (name, description, parameters) and can choose to call it.

A common mistake is creating a function and testing the agent, only to find the LLM never calls it. If the function was not triggered, confirm you have referenced it with @function_name in a topic action, a flow step, or the Behavior field. Use the Tool calls layer in Conversation Diagnosis to verify what the agent actually did.

What the LLM actually sees

When you reference a function, it is added to the prompt sent to the LLM. The prompt is structured roughly like this:

Section	What it contains
Base system prompt – intro	Your Personality and Role fields concatenated
Base system prompt – behavior	Everything in the Behavior field
Context information	Knowledge content retrieved for this turn (empty if no relevant topic matched)
Conversation history	The full transcript so far, alternating `assistant` / `user` roles
Functions	Definitions of any functions that have been referenced

The LLM does not see the Python code inside the function. It only sees the function’s name, description, and parameters.

The Greeting is different – it is hard-coded text played at the start of every call and is not generated by the LLM. It does appear in conversation history so the LLM knows how the call opened, but no LLM request is made to produce it.

This means your function name, description, and parameter descriptions are all part of the prompt. Write them with the same care as any other prompt text.

Check your understanding

You create a function called check_order_status but the LLM never calls it. What is the most likely cause?

The function has a bug in the Python code
The function has not been referenced anywhere in a topic, flow, or behavior
The LLM does not support functions
The function name contains underscores

Answer: The function has not been referenced anywhere in a topic, flow, or behavior

Creating a function does not make it visible to the LLM. You must reference it – in a topic action, a flow step, or the Behavior field. If the function does not appear in the LLM request’s functions list, it has not been registered.

Try it

To make a function visible to the LLM, you reference it in a topic, flow, or Behavior field using the syntax: @________

Answer: function_name, @function_name

The two-request pattern

When the LLM calls a function, it takes two LLM requests to produce the final response to the user.

Request 1: the LLM decides to call a function

The LLM receives the user input, sees the available function definitions, and outputs a tool call rather than text.

The response content is empty. The tool call object contains the function name and the parameter values the LLM extracted from the conversation.

The function runs

Agent Studio executes the Python function with the provided parameters and gets back a result.

Request 2: the LLM reports the result

The function result is inserted into the conversation history under a function role. The LLM sees this result and produces a text response to communicate the result to the user.

Enable the Tool calls toggle in Conversation Diagnosis to see what parameters the agent passed to the function and what was returned. The function call and its result both appear in the turn timeline.

What the conversation history looks like after a tool call

assistant: "Hi, thanks for calling. How can I help?"
user: "What's 2 plus 3?"
assistant: [calls add_two_numbers with first_number=2, second_number=3]
function: "The total is 5"
assistant: "2 plus 3 equals 5."

The function role is the third role alongside user and assistant. This is how function results are fed back into the LLM’s context.

Check your understanding

Why are there two LLM requests when a function is called?

The first request checks permissions, the second runs the function
The first request produces the tool call, the second reads the function result and generates the user response
Both requests are identical – it is a retry mechanism
The first request is for voice, the second for chat

Answer: The first request produces the tool call, the second reads the function result and generates the user response

Request 1 produces the tool call (the LLM’s decision to call the function). After the function runs, its result is inserted into conversation history. Request 2 lets the LLM read that result and produce the text response for the user.

Try it yourself

Create a function

In Tools, create a function called get_store_hours with no parameters. Return a string like "The store is open Monday–Friday, 9am to 6pm.".

Reference it

In Behavior > General > Rules, add a reference to @get_store_hours. Confirm it highlights.

Test it

Open Chat and ask “What are your opening hours?” Enable the Tool calls layer in Conversation Diagnosis to confirm:

The get_store_hours tool call appears with its parameters
The returned value is shown in the turn timeline
The agent’s spoken response incorporates the returned value

← Previous: Complex topics

Lesson 1 of 8

Next: Return values →

Lesson 3 of 8