Skip to content

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

PythonPython not started

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’s description is 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.

PythonPython not started

Two rules in that loop are not optional:

  • The assistant turn is appended whole, tool_use blocks included. Drop them and the next request has results referring to a call the conversation no longer contains.
  • Each tool_result carries the tool_use_id of 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:

PythonPython not started

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:

PythonPython not started

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

PythonPython not started

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

Exercise 1

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.

Your turnPython not started
Exercise 2

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.

Your turnPython not started

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, a description and an input_schema — and the description is where the model’s behaviour is actually decided.
  • The loop: call, append the whole assistant turn, execute every tool_use block, send the results, repeat until stop_reason is no longer "tool_use".
  • Every tool_result needs the matching tool_use_id, and all results go in one user message.
  • Report failures with is_error: true rather than dropping them or raising.
  • Always bound the loop — an unbounded one is an unbounded bill.
  • Read block.input as a dictionary; never match on its serialised text.