Deel B · Module 02

Tool use

Hoe “doet” een model iets?

Zone: machine ± 15 min kern

Leerdoelen

Na deze module kun je:

  • de volledige ronde van één tool call navertellen (definitie, tool_use, uitvoeren, tool_result, antwoord) en aanwijzen waar het model werkt en waar jouw code;
  • een tool-definitie schrijven waarvan de description en het input_schema het model naar de juiste keuze en de juiste input sturen;
  • fouten van een tool terugmelden met is_error en uitleggen waarom de input van het model gevalideerd moet worden voordat je iets uitvoert.

Voorkennis-check

Twee vragen over eerdere modules. Fout? Lees B1 De Messages-API of A4 Inferentie & sampling eerst terug.

Waar zitten we?

Laag 2 van de stack: de API. Tool use is het deel van de API-contracten waarmee een model dat alleen tekst genereert toch acties kan aanvragen.

De stof in drie lagen

Kern ± 5 min

Een taalmodel genereert tekst. Het kan geen bestand lezen, geen database bevragen en geen API aanroepen. Tool use is de afspraak waarmee het toch “iets doet”: het model schrijft een gestructureerd verzoek, jouw code voert dat uit, en het resultaat gaat als tekst terug naar het model.

Eén ronde heeft vijf onderdelen:

  1. Definitie. Je stuurt bij het request een lijst tools mee. Elke tool heeft een name, een description en een input_schema (JSON Schema).
  2. Keuze. Het model besluit, per beurt, of het een tool nodig heeft. Dat besluit het op basis van jouw description: die is de enige uitleg die het krijgt.
  3. Verzoek. Het model antwoordt met een tool_use-blok (id, name, input) en stop_reason: "tool_use". Er is op dat moment niets uitgevoerd.
  4. Uitvoeren. Jouw code valideert de input, draait de functie en stuurt een tool_result terug in een user-bericht, met het tool_use_id van het verzoek. Ging er iets mis, dan zet je is_error: true.
  5. Antwoord. Het model leest het resultaat als gewone tekst in zijn context en formuleert het antwoord (end_turn), of vraagt nog een tool.

Klik hieronder door de ronde. Zet daarna “Tool faalt” aan en kijk hoe het model met een foutmelding kan bijsturen. Onderaan de visual kun je zelf de description en het schema aanpassen en zien welke keuzes dat oplevert.

Waarom dit voor een agent-bouwer telt: de description is je enige middel om het gedrag van het model te sturen, de input is onbetrouwbaar en alles wat een tool teruggeeft kost context. Zet je dit in een lus, dan heb je een agent: dat is B3.

This is by far the most important factor in tool performance.

Verdieping tool_choice, parallel, server tools, veiligheid

Hoe het model de tools “ziet”

De API zet je tool-definities om in een system prompt die het model instrueert om de tools te gebruiken. Een tool is dus geen aparte API-aanroep naast de tekst: het is extra tekst in de context, en elke tool die je meestuurt kost tokens in elk request.

the API constructs a special system prompt from the tool definitions, tool configuration, and any user-specified system prompt.

Dat verklaart waarom de description zo zwaar weegt, en waarom een grote toolset met lange schema's de context vult (module B4).

Een goede description

De docs vragen om beschrijvingen die uitleggen wat de tool doet, wanneer je hem wel en niet gebruikt, wat elke parameter betekent en wat de tool niet teruggeeft, en noemen als richtlijn minstens 3 tot 4 zinnen per tool. Verder: liever weinig, brede tools (bijvoorbeeld één tool met een action-parameter) dan veel kleine die op elkaar lijken, en namen met een prefix voor de dienst (github_list_prs). Geef tool-resultaten alleen terug wat het model nodig heeft; opgeblazen resultaten verspillen context.

tool_choice: wie beslist of er een tool komt?

Standaard bepaalt het model zelf (auto). Je kunt dat sturen met tool_choice:

  • auto: het model kiest, geen tool is ook goed (standaard als er tools zijn).
  • any: het model moet een van je tools gebruiken.
  • tool: het model moet deze tool gebruiken ({"type": "tool", "name": "get_weather"}).
  • none: geen tools.

Let op: niet elk model ondersteunt forceren. Volgens de docs (opgehaald 2026-11-17) geven any en tool bij onder meer Claude Sonnet 5.5 en Opus 5.5 een 400-fout; gebruik daar auto met strict tool use, of structured outputs als je een vaste JSON-vorm wilt. Bij geforceerd gebruik schrijft het model bovendien geen uitleg vóór het tool_use-blok. Het wisselen van tool_choice maakt gecachte berichtblokken ongeldig (prompt caching).

Parallelle tool calls

Een antwoord kan meer dan één tool_use-blok bevatten (“one or more” in de docs). Je voert ze uit en antwoordt in één user-bericht met een tool_result per tool_use_id. Wil je maximaal één aanroep per beurt, dan zet je disable_parallel_tool_use: true in tool_choice.

Client tools en server tools

Het onderscheid is waar de code draait. Client tools (jouw eigen tools, maar ook Anthropic-gedefinieerde zoals bash en text_editor) draaien in jouw applicatie: jij voert ze uit. Server tools (zoals web_search, web_fetch, code_execution) draaien op Anthropic's infrastructuur: je ziet het resultaat in het antwoord en hoeft niets uit te voeren, en ook geen is_error af te handelen. Hier gaat deze module verder over client tools, omdat dáár jouw code de poortwachter is.

Strikte schema's

Met strict: true op een tool-definitie garandeert de API dat de input exact aan je schema voldoet (geen ontbrekende velden, geen verkeerde types). Dat lost vorm op. Het zegt niets over of de waarde verstandig of veilig is: {"path": "../../.ssh/id_rsa"} is een geldige string.

Fouten: is_error en instructieve meldingen

Een mislukte uitvoering stuur je terug als tool_result met is_error: true. Het model leest de melding en kan bijsturen. De docs geven daarbij een praktische regel:

include what went wrong and what Claude should try next

Dus niet "failed", maar "Rate limit exceeded. Retry after 60 seconds.". Mist het model een verplichte parameter, dan is de eerste remedie een betere description; de docs noemen dat het model bij zulke fouten 2 tot 3 keer opnieuw probeert voordat het zich verontschuldigt. Zet in je eigen code toch altijd een maximum aantal pogingen.

Veiligheid: de input is onbetrouwbaar

Het model genereert de input door tekst te voorspellen, op basis van een context waar mogelijk ook onbetrouwbare tekst in staat. Twee gevolgen:

  • Valideer vóór uitvoeren: schema, maar ook je eigen regels (toegestane paden, maximumbedragen, alleen-lezen queries). Dit is precies de plek waar een PreToolUse-hook ingrijpt (module C2), en waar MCP-servers (module C3) tools aanbieden die dezelfde definitie- en resultaatvorm hebben.
  • Resultaten zijn ook niet te vertrouwen: een webpagina of e-mail die je als tool_result teruggeeft kan instructies bevatten (prompt injection).

Treat that content as untrusted: an attacker who can influence it might embed instructions that try to redirect Claude (indirect prompt injection).

Hou onbetrouwbare inhoud daarom binnen tool_result-blokken, en niet in je system prompt.

Onder de motorkap één ronde in Python, mock-run

Eerst de vorm met de echte SDK. Dit fragment is ingekort en hier niet uitgevoerd (het vraagt een API-key); het volgt het voorbeeld uit de docs.

ronde_sdk.py (niet gedraaid)

import anthropic
client = anthropic.Anthropic()
tools = [{"name": "get_weather",
          "description": "Geeft het actuele weer voor één plaats. ...",
          "input_schema": {"type": "object",
              "properties": {"location": {"type": "string"}},
              "required": ["location"]}}]
messages = [{"role": "user", "content": "Wat is het weer in Den Bosch?"}]

resp = client.messages.create(model="claude-sonnet-5-5", max_tokens=1024,
                              tools=tools, messages=messages)
if resp.stop_reason == "tool_use":
    block = next(b for b in resp.content if b.type == "tool_use")
    result = {"type": "tool_result", "tool_use_id": block.id}
    try:
        result["content"] = get_weather(**block.input)   # jouw code
    except Exception as e:
        result.update(content=f"{type(e).__name__}: {e}", is_error=True)
    messages += [{"role": "assistant", "content": resp.content},
                 {"role": "user", "content": [result]}]
    resp = client.messages.create(model="claude-sonnet-5-5", max_tokens=1024,
                                  tools=tools, messages=messages)
print(resp.content[0].text)

Om de JSON-vormen te zien zonder API-key is hieronder een mock: een nepmodel dat altijd dezelfde tool_use teruggeeft. Het draait wel echt: de validatie, de uitvoering, het foutpad en de berichtenlijst zijn gewone code. Alleen het “model” is gescript.

mock_tool.py (gedraaid met python3)

import json

TOOLS = [{
    "name": "get_weather",
    "description": "Geeft het huidige weer voor een plaats. Gebruik dit voor vragen over actueel weer; niet voor klimaat of voorspellingen.",
    "input_schema": {
        "type": "object",
        "properties": {
            "location": {"type": "string", "description": "Plaats, bv. Utrecht"},
            "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
        },
        "required": ["location"],
    },
}]

def mock_model(messages):
    """Speelt het model: eerst een tool_use, daarna een eindantwoord."""
    last = messages[-1]
    if isinstance(last["content"], str):
        city = "Atlantis" if "Atlantis" in last["content"] else "Utrecht"
        return {"stop_reason": "tool_use", "content": [
            {"type": "tool_use", "id": "toolu_mock01", "name": "get_weather",
             "input": {"location": city, "unit": "celsius"}}]}
    res = last["content"][0]
    tekst = ("Die plaats ken ik niet; geef een bestaande plaats." if res.get("is_error")
             else f"Het is nu {res['content']}.")
    return {"stop_reason": "end_turn", "content": [{"type": "text", "text": tekst}]}

def validate(inp, schema):
    for key in schema.get("required", []):
        if key not in inp:
            raise ValueError(f"ontbrekend veld: {key}")
    for key, val in inp.items():
        prop = schema["properties"].get(key)
        if prop is None:
            raise ValueError(f"onbekend veld: {key}")
        if prop["type"] == "string" and not isinstance(val, str):
            raise ValueError(f"{key} moet een string zijn")
        if "enum" in prop and val not in prop["enum"]:
            raise ValueError(f"{key} moet een van {prop['enum']} zijn")

def get_weather(location, unit="celsius"):
    if location != "Utrecht":
        raise LookupError(f"onbekende plaats: {location}")
    return "14 graden, bewolkt"

def one_round(vraag):
    messages = [{"role": "user", "content": vraag}]
    resp = mock_model(messages)
    print("stop_reason:", resp["stop_reason"])
    blok = next(b for b in resp["content"] if b["type"] == "tool_use")
    print("tool_use   :", json.dumps(blok))
    resultaat = {"type": "tool_result", "tool_use_id": blok["id"]}
    try:
        validate(blok["input"], TOOLS[0]["input_schema"])
        resultaat["content"] = get_weather(**blok["input"])
    except Exception as e:
        resultaat["content"] = f"{type(e).__name__}: {e}"
        resultaat["is_error"] = True
    print("tool_result:", json.dumps(resultaat))
    messages += [{"role": "assistant", "content": resp["content"]},
                 {"role": "user", "content": [resultaat]}]
    eind = mock_model(messages)
    print("antwoord   :", eind["content"][0]["text"], f"({len(messages)} berichten)")

one_round("Wat is het weer in Utrecht?")
print()
one_round("Wat is het weer in Atlantis?")
  1. Handgeschreven minimale validatie (required, type, enum, onbekende velden). In echte code gebruik je een JSON Schema-validator, plus eigen regels die een schema niet kan uitdrukken.
  2. Het id uit het tool_use-blok, letterlijk overgenomen. Zonder deze koppeling weet het model niet welke aanroep dit resultaat beantwoordt.
  3. Eén exception wordt een tool_result met is_error, geen crash van je programma.
  4. Na de ronde zijn er 3 berichten: de vraag, het assistant-bericht met tool_use en het user-bericht met tool_result.

Uitvoer van deze run (dit is wat het script daadwerkelijk print):

uitvoer

stop_reason: tool_use
tool_use   : {"type": "tool_use", "id": "toolu_mock01", "name": "get_weather", "input": {"location": "Utrecht", "unit": "celsius"}}
tool_result: {"type": "tool_result", "tool_use_id": "toolu_mock01", "content": "14 graden, bewolkt"}
antwoord   : Het is nu 14 graden, bewolkt. (3 berichten)

stop_reason: tool_use
tool_use   : {"type": "tool_use", "id": "toolu_mock01", "name": "get_weather", "input": {"location": "Atlantis", "unit": "celsius"}}
tool_result: {"type": "tool_result", "tool_use_id": "toolu_mock01", "content": "LookupError: onbekende plaats: Atlantis", "is_error": true}
antwoord   : Die plaats ken ik niet; geef een bestaande plaats. (3 berichten)

Formatteringsregels die vaak fout gaan

  • Het tool_result-bericht moet direct op het bericht met het tool_use volgen; er mag geen ander bericht tussen.
  • In dat user-bericht staan de tool_result-blokken vooraan; tekst komt erna. Tekst ervoor geeft een 400-fout.
  • Een tool_result hoort in een bericht met role: "user". Anders dan bij sommige andere API's is er geen aparte tool-rol.
  • De content van een resultaat is een string, of een lijst blokken (tekst, afbeelding, document).

Uitgewerkt voorbeeld: een eigen tool, drie JSON-blokken

Stel je bouwt een tool read_file. Dit is wat je definieert, wat het model teruggeeft en wat jij terugstuurt voor de vraag “Wat staat er in config.json?”.

1. Tool-definitie (in tools van het request)

{
  "name": "read_file",
  "description": "Leest een tekstbestand uit de projectmap en geeft de inhoud terug. Gebruik dit als de gebruiker naar de inhoud van een bestand vraagt. Niet voor mappen, niet voor binaire bestanden. Geeft maximaal 200 regels.",
  "input_schema": {
    "type": "object",
    "properties": {
      "path": { "type": "string",
                "description": "Relatief pad vanaf de projectroot, bv. src/main.py" }
    },
    "required": ["path"]
  }
}

2. Response van het model

{
  "stop_reason": "tool_use",
  "content": [
    { "type": "text", "text": "Ik lees het bestand." },
    { "type": "tool_use", "id": "toolu_01B",
      "name": "read_file",
      "input": { "path": "config.json" } }
  ]
}

3. Jouw volgende bericht

{ "role": "user", "content": [
  { "type": "tool_result",
    "tool_use_id": "toolu_01B",
    "is_error": true,
    "content": "FileNotFoundError: config.json bestaat niet. Bestanden in de root: app.toml, README.md." }
] }
  1. De naam: kort, specifiek, en uniek binnen je toolset.
  2. De description vertelt wat, wanneer, wanneer niet en wat de beperkingen zijn. Elke zin sluit een foute keuze uit.
  3. De veldomschrijving stuurt de waarde: relatief pad, met een voorbeeld. Dat voorkomt dat het model een absoluut pad verzint.
  4. De input komt van het model. Voor het openen: check dat dit pad binnen de projectmap blijft.
  5. Het bestand ontbreekt, dus is_error: true in plaats van een gewone string die als data wordt gelezen.
  6. De melding zegt wat er mis was en welke opties er zijn. Daarmee kan het model in de volgende beurt app.toml proberen.
Doe-opdracht

Definieer een eigen tool en draai één ronde

Opdracht

  1. Kies een kleine tool die je zelf nuttig vindt, bijvoorbeeld word_count(path), convert_currency(amount, from, to) of list_todos(dir). Schrijf de Python-functie.
  2. Schrijf de tool-definitie: name, een description van minimaal drie zinnen (wat, wanneer, wanneer niet) en een input_schema met een omschrijving per veld en required.
  3. Implementeer één ronde: request, het tool_use-blok uitlezen, valideren, uitvoeren, tool_result teruggeven en het antwoord printen. Heb je een API-key, gebruik dan de SDK (claude-sonnet-5-5); zonder key kun je het script uit “Onder de motorkap” als startpunt nemen en mock_model laten teruggeven wat jouw tool nodig heeft.
  4. Voeg het foutpad toe: laat de tool een exception gooien (bestand bestaat niet, onbekende valuta) en geef die terug met is_error: true en een melding die zegt wat het model kan proberen.
  5. Schrijf de validatie zo dat één zelfgekozen ongeldige input wordt geweigerd (bijvoorbeeld een pad met ..) en dat ook als is_error teruggaat. Print aan het eind de volledige messages-lijst.
Verwacht resultaat

Succespad: stop_reason: tool_use, een tool_use-blok met jouw toolnaam en een input die aan je schema voldoet, daarna een eindantwoord. messages bevat 3 berichten (user, assistant met tool_use, user met tool_result). Foutpad: dezelfde 3 berichten, maar het tool_result heeft is_error: true en je instructieve melding; met de echte API stuurt het model bij of legt de fout uit, met de mock zie je jouw gescripte antwoord. Een geweigerde input komt nooit in je tool-functie terecht.

Als het niet werkt, kijk naar …
  • 400-fout “tool_use ids were found without tool_result blocks immediately after”: je tool_result mist, heeft een ander tool_use_id, of er zit een bericht tussen. Neem block.id letterlijk over.
  • 400-fout over tekst vóór het resultaat: zet de tool_result-blokken vooraan in content.
  • Het model roept de tool niet aan: je description past niet bij de vraag. Maak hem concreter, of voeg een lichte instructie aan je system prompt toe. Forceren met tool_choice any/tool werkt niet op elk model (zie Verdieping).
  • Het model verzint een parameter: zet in de veldomschrijving wat het moet doen als de waarde ontbreekt, of overweeg strict: true.
  • Je programma crasht bij een fout in de tool: vang de exception rond de uitvoering en de validatie, niet alleen rond de API-call.

Zelftoets