> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://poly-ai.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://poly-ai.ferndocs.com/_mcp/server.

# Tutorial: Using tools

> PolyAcademy Level 2 – How the LLM calls Python functions (tools) to integrate with external systems.

**Level 2 – Lesson 2 of 8** – This lesson explains what [tools](/agent-studio/tools/overview) 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.

> **Note**
>
> In Agent Studio, tools are defined as Python `function`s – "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.

```mermaid
sequenceDiagram
    actor User
    participant LLM
    participant Fn as Python Function

    User->>LLM: "What are your opening hours?"
    Note over LLM: Request 1 – decides to call a tool
    LLM->>Fn: call get_store_hours()
    Fn-->>LLM: "Open Mon–Fri, 9am–6pm"
    Note over LLM: Request 2 – formulates response
    LLM->>User: "We're open Monday to Friday, 9am to 6pm."
```

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

```python
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)

> **Warning**
>
> 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.

> **Warning**
>
> 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](/agent-studio/conversations/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](/agent-studio/conversations/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](/agent-studio/conversations/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](/academy/poly-academy/poly-academy-level-2/add-complex-topics)

Lesson 1 of 8

#### [Next: Return values →](/academy/poly-academy/poly-academy-level-2/tool-return-values)

Lesson 3 of 8