LLM Engineering·Lesson 48 of 67·advanced
Tool use and the function-calling loop
Give the model hands — define tools, run the request/execute/return loop, handle parallel calls and failures, and write descriptions the model can actually act on.
In this lesson · 22 min
- →Define a tool with a name, description and input schema
- →Run the loop until the model stops asking for tools
- →Return every tool result in one user message, with matching ids
- →Report a failed tool as a result rather than dropping it
- →Write tool descriptions that change the model's behaviour
A model cannot look anything up or change anything. Tool use is the protocol that fixes that: you describe what is available, the model asks for a call, your code runs it, and you send the result back. The model never executes anything.
A tool definition
Three fields matter, and the second matters most:
name— how the model refers to it, and how you dispatch.description— when to use it, when not to, and what it returns. This is prompt engineering, and it is where most tool bugs actually live.input_schema— JSON Schema. Every property’sdescriptionis read by the model too.
The loop
The model replies with stop_reason: "tool_use" and one or more tool_use blocks. You run them,
append the results, and call again — until it stops asking.
Two rules in that loop are not optional:
- The assistant turn is appended whole,
tool_useblocks included. Drop them and the next request has results referring to a call the conversation no longer contains. - Each
tool_resultcarries thetool_use_idof the call it answers. The model matches on that id, not on order.
Parallel calls
One assistant message can contain several tool_use blocks. Run them, and return all the
results in one user message:
When a tool fails
Return the failure as a result with is_error: true. Do not drop it, and do not let the exception
escape the loop:
An error result is information: the model can correct the argument and try again. A dropped result is a conversation the model cannot continue, and a raised exception is an outage.
A complete runner
Note max_rounds. A loop with no ceiling is an unbounded bill, and a model that misunderstands a
tool can ask for it repeatedly.
Letting the SDK drive
For an ordinary custom-tool agent the SDK will run the loop. Tools become decorated functions and the schema is derived from the signature and docstring:
import anthropic
from anthropic import beta_tool
client = anthropic.Anthropic()
@beta_tool
def search_documents(query: str, top_k: int = 3) -> str:
"""Search the internal documentation index.
Args:
query: The search terms, in the user's own words.
top_k: How many passages to return.
"""
return "\n".join(find(query)[:top_k])
runner = client.beta.messages.tool_runner(
model="claude-opus-5",
max_tokens=16000,
tools=[search_documents],
messages=[{"role": "user", "content": "What overlap should I use when chunking?"}],
)
for message in runner:
print(message.stop_reason)
The runner is a beta helper. Write the manual loop when you need control it does not expose — a custom transport, or a termination policy of your own — and the runner otherwise.
Try it yourself
Write execute_tools(blocks, registry): one tool_result per tool_use block, with is_error set when the call fails or the tool is unknown.
Write run_loop(client, registry, question, max_rounds=5): call, append the whole assistant turn, execute tools into one user message, and stop when stop_reason is not tool_use. Return the final text.
Check yourself
Why must every tool_result carry the tool_use_id of the call it answers?
Check yourself
A tool raises an exception. What should the loop send back?
Recap
- A tool is a
name, adescriptionand aninput_schema— and the description is where the model’s behaviour is actually decided. - The loop: call, append the whole assistant turn, execute every
tool_useblock, send the results, repeat untilstop_reasonis no longer"tool_use". - Every
tool_resultneeds the matchingtool_use_id, and all results go in one user message. - Report failures with
is_error: truerather than dropping them or raising. - Always bound the loop — an unbounded one is an unbounded bill.
- Read
block.inputas a dictionary; never match on its serialised text.