tool_use voor gegarandeerde structuur

Dit is een extractietool. Let op de drie pijlers van een goede tooldefinitie: een duidelijke name, een beschrijvende description en een nauwkeurig input_schema met beschrijvingen per eigenschap en een lijst required.

Het onderstaande schema extraheert een supportticket. We verplichten alleen de velden die altijd aanwezig zijn — binnenkort meer over die keuze.

De tool declareren is niet genoeg — met de standaardinstelling kan Claude in plaats daarvan tekst antwoorden. De parameter tool_choice bepaalt die keuze:

• {"type": "auto"} — Claude kiest tekst of een tool (de standaardinstelling).
• {"type": "any"} — Claude moet een tool aanroepen. Dit garandeert gestructureerde uitvoer.
• {"type": "tool", "name": "X"} — dwingt één specifieke tool af op naam.

Als je precies één schematool hebt en een gegarandeerde aanroep daarvan wilt, dwing je die op naam af. Daarmee verwijder je de uitweg om volledig in proza te antwoorden.

Wanneer Claude de tool aanroept, bevat het antwoord een inhoudsblok tool_use. De gestructureerde gegevens staan in block.input — al door de SDK verwerkt tot een Python-dict die aan je schema voldoet.

Een discipline uit het factsheet: verwerk altijd het door de SDK verwerkte object en vergelijk nooit ruwe tekenreeksen met de geserialiseerde invoer. Recente modellen kunnen Unicode of schuine strepen op verschillende manieren escapen, dus behandel block.input als gestructureerde gegevens, niet als tekst.

Dit is de belangrijkste beslissing die in deze les wordt getoetst. De regel uit het factsheet is duidelijk:

Markeer een veld ALLEEN als required als het altijd aanwezig is. Maak een veld dat kan ontbreken NOOIT verplicht — het model verzint een waarde om aan het schema te voldoen.

Als customer_id soms niet in de brontekst staat maar je het onder required vermeldt, geeft Claude geen leeg resultaat terug — het verzint een aannemelijk ID om de toolaanroep geldig te maken. Dat is een stille fout in de gegevensintegriteit. Verplicht betekent "door de bron gegarandeerd", niet "mooi meegenomen".

Velden die kunnen ontbreken, laat je simpelweg weg uit de array required. Claude laat ze weg wanneer de bron de gegevens niet bevat, in plaats van te hallucineren.

Hier zijn customer_id en attachments optioneel; alleen summary en priority — die we altijd kunnen afleiden — zijn verplicht.

Enumeraties beperken een veld tot een vaste verzameling waarden — ideaal voor categorieën, labels en prioriteiten. Maar een rigide enumeratie dwingt elke invoer in een van je vooraf bepaalde categorieën, waardoor randgevallen die je niet had voorzien verkeerd worden verwerkt.

Het patroon uit het factsheet voor uitbreidbaarheid: gebruik enumeraties met een waarde "other" plus een veld met vrije tekst voor details. Wanneer Claude iets tegenkomt dat buiten je categorieën valt, kiest het other en legt het dit uit in het detailveld — in plaats van het verkeerd te labelen.

Het schema garandeert de syntactische vorm, maar je valideert nog steeds de semantiek — totalen die kloppen, datums binnen het bereik en consistentie tussen velden. Gebruik een validator in de stijl van Pydantic op block.input.

Wanneer de validatie mislukt door een opmaak-, structurele of rekenfout, gebruik je retry-with-feedback: stuur de oorspronkelijke bron, de onjuiste uitvoer en de exacte validatiefout opnieuw. Belangrijk: het factsheet waarschuwt dat opnieuw proberen NIET helpt wanneer de informatie simpelweg ontbreekt in de bron — opnieuw proberen nodigt dan alleen uit tot verzinnen.

Bij numerieke extractie is het een krachtige truc om Claude met het schema zijn werk te laten tonen, zodat afwijkingen detecteerbaar worden. Volgens het factsheet: extraheer zowel een calculated_total als een stated_total om afwijkingen te detecteren.

Als het document "Totaal: $1,200" vermeldt maar de afzonderlijke regels optellen tot $1,150, maken twee afzonderlijke velden de afwijking zichtbaar — je validator detecteert die in plaats van één getal te vertrouwen. Het schema wordt zo een controle-instrument, niet alleen een container.

Gestructureerde uitvoer is één stap in de grotere agentische lus: verzoek → stop_reason inspecteren → bij tool_use de tool afhandelen → herhalen tot end_turn. Een afgedwongen schema-aanroep retourneert stop_reason: "tool_use"; je leest block.input en gaat verder.

Twee herinneringen op architectniveau: beëindig op basis van de stop_reason, nooit door in tekst te zoeken naar woorden als "klaar". Houd ook de herkomst bij — koppel elke geëxtraheerde bewering terug aan de bron (documentnaam, citaat, datum), zodat downstreamgebruikers het gestructureerde resultaat kunnen vertrouwen en controleren.

Belangrijkste punten voor het examen en voor productie:

• tool_use + JSON Schema elimineert syntaxfouten en dwingt verplichte velden af — veel betrouwbaarder dan JSON in proza verwerken.
• tool_choice: "any" garandeert een toolaanroep; {"type":"tool","name":"X"} dwingt een specifieke schematool af; "auto" laat de keuze optioneel.
• required = altijd aanwezig. Maak een mogelijk ontbrekend veld nooit verplicht — dat veroorzaakt verzinsels. Optionele velden laat je simpelweg weg uit required.
• Enumeraties hebben een "other"- plus detailveld nodig voor uitbreidbaarheid.
• Lees gestructureerde gegevens uit block.input; vergelijk nooit ruwe tekenreeksen met de geserialiseerde toolinvoer.
• Retry-with-feedback herstelt opmaak- en rekenfouten — niet ontbrekende informatie. Gebruik calculated_total tegenover stated_total voor zelfcorrectie en houd de herkomst bij.