Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 53 ยท Tools and Agents

Tool Use and Function Calling

Learn how LLMs call tools: JSON schemas, the call and result message loop, parallel calls, argument validation and error handling, with a live dispatcher.

A language model on its own can only produce text. It cannot check today's weather, query your database, send an email or reliably multiply two big numbers. Tool use (also called function calling) closes that gap: you describe functions to the model, the model replies with a request to call one of them with certain arguments, your code runs it, and you send the result back so the model can continue.

The key point is that the model never executes anything. It only writes a structured request. Everything that happens in the real world is done by your program, which is exactly where you add validation, permissions and limits. This lesson shows the message loop, the schema format, parallel calls and error handling.

Who does what

Model Chooses a tool and writes the arguments.
Your code Validates, runs the tool, returns the result.
Tool An ordinary function, API or query.

The model proposes. Your program decides and executes.

1 / 2

Describing a tool

A tool is described with a name, a description and a parameter schema written in JSON Schema. The model reads these descriptions as part of its input, so they are effectively prompt text: a vague description leads to wrong or missed calls.

The exact field names differ between providers, but the shape is always similar:

JSON
{
  "name": "get_order_status",
  "description": "Look up the shipping status of a customer's order by its order number.",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string", "description": "Order number, like A-1042" },
      "include_history": { "type": "boolean", "description": "Also return past status changes" }
    },
    "required": ["order_id"]
  }
}

Good tool design follows a few rules:

  • Name and describe by purpose. Say what the tool does and when to use it, and when not to.
  • Describe every parameter, with an example value and units.
  • Keep the list short. Models choose better from five clear tools than from fifty overlapping ones.
  • Prefer enums for fixed choices, so the model cannot invent a value.
  • Return compact, useful results. The result goes back into the context window, so a 20,000-token JSON dump costs money and distracts the model (see Context Windows and the KV Cache).

The call and result loop

A tool conversation is an ordinary message list with two extra message types: an assistant message that contains tool calls, and tool result messages that answer them.

sequenceDiagram
    participant U as User
    participant A as Your app
    participant M as Model
    U->>A: "Where is order A-1042?"
    A->>M: messages + tool definitions
    M-->>A: tool call get_order_status(A-1042)
    A->>A: validate and run the function
    A->>M: messages + tool result
    M-->>A: "It shipped yesterday."
    A-->>U: final answer

One round trip: the model asks, your app executes, the model answers using the result.

Here is how that looks in code. This snippet is read-only, because the site cannot call a model API. The structure matches what most provider SDKs do, though names vary.

Python
messages = [{"role": "user", "content": "Where is order A-1042?"}]

while True:
    reply = client.chat(model="your-model", messages=messages, tools=TOOLS)
    messages.append(reply.message)                 # keep the assistant turn in the history

    if not reply.tool_calls:                       # no tool requested: this is the final answer
        print(reply.message.content)
        break

    for call in reply.tool_calls:                  # run every requested tool
        result = run_tool(call.name, call.arguments)
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,               # ties the result to the request
            "content": json.dumps(result),
        })

Three details matter. First, the assistant's tool-call message must stay in the history, because the next request needs the full conversation. Second, each result carries the id of the call it answers. Third, the loop continues until the model replies without a tool call. In a real program, add a maximum number of rounds so a confused model cannot loop forever (see Building an Agent Loop).

Parallel calls

When a request needs several independent lookups ("What is the weather in Oslo and in Lima?"), many models return several tool calls in one turn. Your code can run them concurrently and send back one result message per call id. Results may come back in any order, as long as each carries the right id. Never run dependent calls in parallel: if the second needs the first one's output, the model has to wait for a round trip.

Validate everything

Model-written arguments are untrusted input, exactly like text typed by a stranger. The model may omit a required field, send "two" for a number, use an enum value that does not exist, or (under a prompt injection) be tricked into asking for something harmful. Before running a tool:

  1. Check the tool name is in your registry.
  2. Validate the arguments against the schema (types, required fields, enum values, ranges).
  3. Check permissions: does this user in this session have the right to do this? Authorization belongs in your code, never in the prompt.
  4. For actions with side effects (sending, deleting, paying), require confirmation or a dry run.

Errors are messages, too

When a tool fails, do not crash and do not hide it. Return the error as the tool result, in plain language the model can act on: "Invalid argument: order_id must look like A-1042". Models usually repair a bad call after seeing a clear error, and they can tell the user honestly when a tool is down. Keep error text short and free of secrets such as stack traces or connection strings.

A live dispatcher

The example below implements the host side of the loop. The "model" is a scripted function that returns pre-planned tool calls, so the run is deterministic. The dispatcher validates arguments against a small schema, runs parallel calls, and turns errors into results.

Python A tool dispatcher with validation and a scripted model

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

In round 1 the "model" asks for three things at once. Two succeed. The third passes a number where the schema wants a string, so the dispatcher returns a readable error as the result. In round 2 the model sees that error, repairs the call, and in round 3 it writes the final answer. A real model's behavior varies, but the host code stays the same.

Extra safeguards

Real tool systems add a few more rules:

  • Timeouts and retries for every external call, so a slow API cannot stall the conversation.
  • Idempotency: if a call might run twice (a retry), make sure charging a card twice is impossible, for example with an idempotency key.
  • Logging: record every call, its arguments and its result for debugging and audits.
  • Forcing or forbidding tools: most APIs let you require a specific tool, allow any, or disable tools for a turn. A forced tool call is also a handy way to get structured output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Who actually executes a function when a model 'calls' a tool?

    The model only writes a request with a tool name and arguments. Your program decides whether and how to run it.
  2. 2. What should you do when a tool call fails because of invalid arguments?

    Models usually repair a call when they see an informative error, and they can report real failures honestly.
  3. 3. Why does each tool result message carry the id of the call it answers?

    With parallel calls there are several open requests. The id ties each result to its call.
  4. 4. Where should you check whether the current user may delete a record?

    Authorization must be enforced by code. A prompt can be bypassed by injection or by mistakes.

Summary

  • Function calling lets a model request a function call with JSON arguments; your code validates, executes and returns the result.
  • Tools are described by name, description and a JSON Schema; clear descriptions, few tools and enums improve accuracy.
  • The loop is: send messages and tools, run requested calls, append results with matching ids, repeat until a reply has no tool call.
  • Parallel calls return several results in one round; only independent calls should run in parallel.
  • Treat arguments as untrusted: validate, authorize, confirm side effects, and return errors as readable results.

Next: wrap this loop into an agent in Building an Agent Loop.