Tutorial: Tool return values

Level 2 – Lesson 3 of 8 – This lesson covers the different values a tool can return and when to use each one. Understanding return values gives you precise control over what the agent says and when.

Choosing a return type

The two valid return types

Functions called by the LLM can only return a string or a dictionary. Any other type – integer, list, boolean – will cause an error. The LLM will retry up to three times before giving up and producing an error response.

Always return a string or dictionary from functions called by the LLM. If your value is a number, wrap it: return str(count) or return f"There are {count} items.".

Returning a string

The simplest and most common pattern. Return a string and the LLM reads it, considers it alongside the conversation history, and formulates its own response.

def check_banana_stock(conv) -> str:
    return "There are 3 bananas left."

The string is inserted into conversation history under the function role. The LLM then produces a natural response based on it. Trade-off: The LLM has flexibility to express the result conversationally – but you do not control the exact phrasing.

Returning a dictionary

Dictionaries give you more specific control. The following keys are supported individually or in combination:

`content`

Equivalent to returning a string. The value is shown to the LLM to inform its next response.

return {"content": "There are 3 bananas left."}

`utterance`

A hard-coded response that bypasses the LLM entirely. The text is spoken directly to the user without any further LLM request.

return {"utterance": "There are 3 bananas left. Would you like to buy some?"}

Trade-off: You get full control over phrasing and only one LLM request (lower latency). But you must manually handle all variations – zero stock, one item, multiple items, and so on.

Return string (LLM generates response)
Return utterance (bypasses LLM)

# Function returns:
return "There are 0 bananas left."

# LLM produces:
# "I'm sorry, we don't have any bananas available right now.
#  Would you like to check back later?"

The LLM adds empathy, context, and a follow-up offer.

# Function returns:
return {"utterance": "There are 0 bananas left."}

# User hears exactly:
# "There are 0 bananas left."

Grammatically correct but blunt – no conversational framing.To improve it, you must write the logic yourself:

if bananas == 0:
    return {"utterance": "I'm sorry, we're out of bananas right now."}
elif bananas == 1:
    return {"utterance": "Good news – we have one banana left. Would you like it?"}
else:
    return {"utterance": f"Good news – we have {bananas} bananas left."}

`content` + `utterance` together

When both keys are returned, the utterance is played immediately to the user, and the content is stored in conversation history to inform the LLM’s response on the next turn.

return {
    "utterance": "Let me check that for you – just one moment.",
    "content": "The user asked about banana stock. There are 3 available."
}

Use this pattern when you want to:

play a hard-coded holding phrase while the agent processes something
give the LLM context for how to handle the follow-up

`end_turn: False`

By default, returning an utterance ends the turn. Setting end_turn to False plays the utterance but then immediately triggers another LLM request in the same turn.

return {
    "utterance": "Just one second while I look that up.",
    "end_turn": False
}

This is useful for latency optimization – play a filler phrase while the LLM decides on its next action (such as calling another function). It is a power-user pattern and not needed in most flows.

`hangup: True`

Ends the call after the function executes.

return {
    "utterance": "Thanks for calling. Have a great day. Goodbye.",
    "hangup": True
}

Always include an utterance when hanging up – otherwise the call ends silently, which feels like a dropped call to the user.

`handoff: True`

Transfers the call to a live agent after the function executes. Like hangup, always pair it with an utterance so the user hears a proper transition message before the transfer.

return {
    "utterance": "Let me connect you with someone who can help with that.",
    "handoff": True
}

This is commonly used in flows when a user fails validation repeatedly or requests a live agent. See Flow patterns for examples.

Fill in the blank

Returning an empty dictionary

An empty dictionary {} means the function returns no output. The LLM calls the function, receives nothing, and has no new information to work with. It will typically produce a filler response (“One moment, please”) and then hallucinate the rest of the conversation. Avoid this in production. Always return something meaningful.

Passing the utterance as a function argument

When using Raven (PolyAI’s in-house LLM), the model returns either a tool call or text – not both in the same response. This means you cannot rely on the LLM to generate a goodbye message at the same time as calling a hangup function. A useful pattern for this situation: pass the utterance as a parameter of the function.

# Function signature includes an utterance argument:
def hang_up(conv, utterance: str) -> dict:
    return {"utterance": utterance, "hangup": True}

Parameter: utterance – The goodbye message to say to the user before ending the call The LLM generates the utterance value and passes it as an argument, so the response is contextually appropriate. The function then plays it as a hard-coded utterance. The LLM generates the phrasing; the function controls execution.

This pattern also works for handoff functions, where you want the LLM to generate a context-appropriate transfer message rather than using a fixed phrase.

Quick reference

Return value	LLM reads it?	User hears it directly?	LLM requests
`"string"`	Yes	No – LLM generates response	2
`{"content": "..."}`	Yes	No – LLM generates response	2
`{"utterance": "..."}`	No	Yes	1
`{"content": "...", "utterance": "..."}`	Yes (on next turn)	Yes (immediately)	1 + next turn
`{"utterance": "...", "end_turn": False}`	No	Yes, then LLM continues	1 + immediate follow-up
`{"utterance": "...", "hangup": True}`	No	Yes, then call ends	1
`{"utterance": "...", "handoff": True}`	No	Yes, then call transfers	1
`{}`	No	No	– (LLM gets no feedback)

PolyAcademy

Recipes

Maintain

Glossary

FAQs

Tutorial: Tool return values

Choosing a return type

The two valid return types

Returning a string

Returning a dictionary

`content`

`utterance`

`content` + `utterance` together

`end_turn: False`

`hangup: True`

`handoff: True`

Fill in the blank

Returning an empty dictionary

Passing the utterance as a function argument

Quick reference

Check your understanding

← Previous: Using tools

Next: Response Control →

​Choosing a return type

​The two valid return types

​Returning a string

​Returning a dictionary

​content

​utterance

​content + utterance together

​end_turn: False

​hangup: True

​handoff: True

​Fill in the blank

​Returning an empty dictionary

​Passing the utterance as a function argument

​Quick reference

​Check your understanding

← Previous: Using tools

Next: Response Control →

Choosing a return type

The two valid return types

Returning a string

Returning a dictionary

`content`

`utterance`

`content` + `utterance` together

`end_turn: False`

`hangup: True`

`handoff: True`

Fill in the blank

Returning an empty dictionary

Passing the utterance as a function argument

Quick reference

Check your understanding