Tools definiëren voor een AI agent: zo doe je dat

Wat is een tool voor een AI agent?

Een tool is een functie die het taalmodel mag laten uitvoeren. Anthropic noemt dit tool use, ook bekend als function calling. Claude bepaalt zelf wanneer het een tool aanroept, op basis van de vraag van de gebruiker en de omschrijving van de tool.

Het model voert de tool zelf niet uit. Het geeft een gestructureerde aanroep terug en jouw applicatie voert die uit. Anthropic noemt dat client tools. Daarnaast zijn er server tools, zoals web search, die Anthropic op de eigen servers uitvoert. Dit artikel gaat over tools die je zelf schrijft. Hoe de loop rond die tools werkt, lees je in Hoe werkt een AI agent?.

De drie velden van een tool-definitie

Je geeft tools mee in de parameter tools van je API-request. Elke tool die je zelf definieert, heeft deze velden:

• name: de naam van de tool. Toegestaan zijn letters, cijfers, underscores en streepjes, maximaal 128 tekens.
• description: een uitgebreide omschrijving in gewone tekst van wat de tool doet, wanneer je hem gebruikt en hoe hij zich gedraagt.
• input_schema: een JSON Schema-object met de parameters die de tool verwacht.

Optioneel voeg je input_examples toe: voorbeelden van geldige invoer. Elk voorbeeld moet aan je schema voldoen, anders krijg je een 400-fout.

Voorbeeld: een tool die een klant opzoekt

{
  "name": "crm_zoek_klant",
  "description": "Zoekt een klant op in het CRM op basis van e-mailadres. Gebruik deze tool als de gebruiker vraagt naar gegevens of de status van een bestaande klant. De tool geeft naam, klantnummer en de datum van het laatste contact terug. Facturen en betaalgegevens geeft hij niet terug. Bestaat het e-mailadres niet, dan krijg je een lege lijst.",
  "input_schema": {
    "type": "object",
    "properties": {
      "email": {
        "type": "string",
        "description": "Het e-mailadres van de klant, bijvoorbeeld jan@voorbeeld.nl"
      },
      "max_resultaten": {
        "type": "integer",
        "description": "Maximum aantal resultaten. Standaard 5."
      }
    },
    "required": ["email"]
  }
}

De parameter email is verplicht, max_resultaten is optioneel. Het voorvoegsel crm_ in de naam laat zien bij welke dienst de tool hoort. Dat helpt het model kiezen zodra je meer tools hebt.

De tool_use/tool_result-cyclus

1. Je stuurt een request met je tools en het bericht van de gebruiker.
2. Wil Claude een tool gebruiken, dan heeft het antwoord stop_reason: "tool_use" en een of meer tool_use-blokken. Elk blok bevat een id, de name van de tool en de input.
3. Jouw code leest de naam en de invoer en voert de bijbehorende functie uit.
4. Je stuurt een nieuw bericht met de rol user. Daarin staat een tool_result-blok met het tool_use_id en het resultaat.
5. Claude leest het resultaat en kiest de volgende stap: nog een tool, of een antwoord.

Zo ziet het resultaat eruit dat je terugstuurt:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Jan de Vries, klantnummer 1042, laatste contact 12 september 2026"
    }
  ]
}

Twee regels waar het vaak misgaat

• Het bericht met tool_result moet direct volgen op het bericht met tool_use. Er mag geen ander bericht tussen zitten.
• In dat bericht staan de tool_result-blokken vooraan. Wil je tekst toevoegen, zet die er dan achter. Tekst ervoor geeft een 400-fout.

Fouten teruggeven

Mislukt een tool, stuur dan de foutmelding terug in content met "is_error": true. Anthropic raadt aan om foutmeldingen te schrijven die uitleggen wat er misging en wat Claude nu kan proberen, zoals "Rate limit bereikt, probeer het over 60 seconden opnieuw". Ontbreekt er een verplichte parameter, dan probeert Claude het volgens de documentatie 2 tot 3 keer opnieuw met correcties, en biedt daarna excuses aan de gebruiker aan.

Goede tool-omschrijvingen schrijven

Volgens Anthropic is een uitgebreide omschrijving veruit de belangrijkste factor voor hoe goed een model met tools werkt. Mik op minstens 3 tot 4 zinnen per tool, meer als de tool complex is. Beschrijf daarin:

• wat de tool doet;
• wanneer het model hem wel en juist niet gebruikt;
• wat elke parameter betekent en wat die doet;
• beperkingen, zoals welke informatie de tool niet teruggeeft.

De documentatie geeft nog meer tips. Voeg verwante acties samen in één tool met een parameter action, zodat het model minder hoeft te kiezen. Zet de naam van de dienst voor de toolnaam, zoals github_list_prs. Laat een tool alleen teruggeven wat het model nodig heeft voor de volgende stap, met vaste id's zoals een slug of UUID. Te veel data in een resultaat vult de context en maakt het lastiger om de kern te vinden.

Kijk door de ogen van het model

In de appendix van Building effective agents schrijft Anthropic dat tool-definities evenveel aandacht verdienen als je prompts. Vraag jezelf af of het op basis van de omschrijving en parameters duidelijk is hoe je de tool gebruikt. Schrijf de omschrijving zoals je een goede docstring schrijft voor een junior developer. Test daarna met veel voorbeeldinvoer en kijk welke fouten het model maakt.

Maak fouten ook moeilijker. Anthropic geeft een voorbeeld uit eigen werk: hun agent maakte fouten met relatieve bestandspaden zodra hij uit de hoofdmap was gegaan. De oplossing was de tool zo aan te passen dat hij altijd een absoluut pad vroeg. Daarna ging het goed.

Zelf tools leren bouwen

Tools zijn stap 3 en 4 in Een AI agent bouwen in 6 stappen. Wil je je agent laten werken met je eigen documenten, lees dan RAG uitgelegd. In de 1-op-1 training AI agent bouwen schrijf je in 3 uur samen met Tarik de tools voor je eigen case, op locatie in Amsterdam-Zuid of digitaal via Microsoft Teams.