Claude Architect · Les

Toolbeschrijvingen sturen de selectie

Het model kiest tools op basis van beschrijvingen, niet van namen

Les 1 van 413 stappen

Toolbeschrijvingen sturen de selectie is een gratis Claude Architect-les op CoddyKit. Dit is les 1 van 4. Je kunt 3 lessen uit dit leerpad gratis volledig lezen — daarna ontgrendelt CoddyKit PRO alle lessen, plus praktische oefeningen met een ingebouwde code-editor en een AI-tutor die 24/7 beschikbaar is. Deze les maakt deel uit van het leertraject Claude Architect. Je voortgang wordt gesynchroniseerd op het web en in de CoddyKit-app. De cursus Claude Architect bevat in totaal 4 lessen.

Het model leest; het gokt niet

Wanneer Claude beslist welke tool het moet aanroepen, kiest het niet op basis van de naam van de tool. Het leest de beschrijving van elke tool en redeneert welke bij de taak past.

Dit is het belangrijkste feit bij het ontwerpen van tools: de beschrijving is het primaire selectiemechanisme. Een tool met de naam process_refund en een vage beschrijving is moeilijker correct te selecteren dan een duidelijk beschreven tool met een onhandige naam.

Als je betrouwbaar gedrag wilt, steek je je energie in het schrijven van beschrijvingen — niet in slimme naamgeving.

Een naam is geen specificatie

Namen zijn kort en dubbelzinnig. Denk aan twee tools: search_orders en lookup_order. Welke vindt op basis van een ID een order? Welke filtert een lijst op datum? Dat kun je niet weten, en het model evenmin.

De beschrijving bevat de werkelijke betekenis:

Waar de tool voor dient (doel).
Wat de tool teruggeeft.
Welke invoer de tool verwacht, met voorbeelden.
De randgevallen en grenzen van toepasbaarheid.

Geef de tool een verstandige naam, maar vertrouw nooit op de naam om gedrag ondubbelzinnig te maken.

Anatomie van een goede beschrijving

Een goede beschrijving van een tool beantwoordt alles wat het model nodig heeft om de tool correct te kiezen en aan te roepen. Neem het volgende op:

Doel — de ene taak die deze tool uitvoert.
Retourwaarden — wat er terugkomt en in welke vorm.
Invoerformaten met voorbeelden — concrete voorbeeldargumenten.
Randgevallen — lege resultaten, niet gevonden en ambiguïteit.
Toepassingsgrenzen — wanneer je de tool NIET moet gebruiken.

De grensclausule voorkomt dat vergelijkbare tools verkeerd aan elkaar worden toegewezen.

lookup_order = {
    "name": "lookup_order",
    "description": (
        "Fetch a single order by its exact order_id. "
        "Returns status, items, total, and ship date. "
        "order_id format: 'ORD-' + 8 digits, e.g. 'ORD-10293847'. "
        "Returns an empty result (not an error) if no order matches. "
        "Use this ONLY when you already have a specific order_id; "
        "to find orders by customer or date, use search_orders instead."
    ),
    "input_schema": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"],
    },
}

Vage beschrijvingen leiden tot verkeerde toewijzing

De meest voorkomende fout is een minimale of ambigue beschrijving. Dit is een veelvoorkomend anti-patroon op examens en meestal het verkeerde antwoord wanneer een vraag vraagt waarom de verkeerde tool is geselecteerd.

Let op wat er gebeurt bij beknopte beschrijvingen:

get_data: "Haalt gegevens op."
fetch_info: "Haalt informatie op."

Wanneer de taak is "zoek de nieuwste bestelling van de klant", kan het model deze twee niet van elkaar onderscheiden. Het kan de verkeerde aanroepen of blijven wisselen. Overlappende of ambigue beschrijvingen leiden tot verkeerde toewijzing — de oplossing is scherpere, niet-overlappende formulering, niet een hernoemde tool.

Duidelijke grenzen tussen tools trekken

Wanneer twee tools plausibel van toepassing kunnen zijn, moet elke beschrijving expliciet aangeven wanneer je de andere moet gebruiken. Zo verwijder je de overlap die de selectie verwart.

Let erop hoe elke beschrijving de andere tool noemt en aangeeft wanneer je de keuze daaraan moet overlaten. Die wederzijdse grens zorgt ervoor dat het model de juiste tool gebruikt.

tools = [
    {
        "name": "search_orders",
        "description": (
            "List orders matching a customer_id and/or date range. "
            "Returns an array of order summaries (id, status, total). "
            "Use to DISCOVER orders when you do not know the order_id. "
            "For full details of one known order, use lookup_order."
        ),
    },
    {
        "name": "lookup_order",
        "description": (
            "Fetch full details of ONE order by exact order_id. "
            "Use only when the order_id is already known. "
            "To find orders, use search_orders first."
        ),
    },
]

Randgevallen in de beschrijving vastleggen

Randgevallen horen in de beschrijving omdat ze de verdere redenering van het model beïnvloeden, niet alleen de aanroep zelf.

Twee onderscheidingen zijn het belangrijkst:

Een toegangsprobleem (het systeem was onbereikbaar — misschien opnieuw proberen) tegenover een geldig leeg resultaat (geen overeenkomsten — niet opnieuw proberen, maar gewoon rapporteren).
Wat er gebeurt bij ambigue invoer — bijvoorbeeld meerdere overeenkomende klanten.

Als de beschrijving zegt "geeft een leeg resultaat terug wanneer geen bestelling overeenkomt", behandelt het model 'geen resultaten' niet als een fout die opnieuw moet worden geprobeerd. Als er staat "geeft meerdere overeenkomsten terug wanneer de naam niet uniek is", weet het model dat het om meer identificerende gegevens moet vragen in plaats van te gokken.

De set tools klein houden

Zelfs perfecte beschrijvingen worden minder effectief wanneer er te veel zijn. Selectie is een redeneertaak en meer opties verzwakken die.

4-5 tools per agent is het optimale bereik voor betrouwbare selectie.
Bij 18+ tools neemt de betrouwbaarheid van de selectie merkbaar af.

Goede beschrijvingen en een kleine set tools versterken elkaar dus: beperk de tools van elke agent tot zijn rol en beschrijf die paar tools vervolgens precies. Een te grote set tools kun je niet alleen met formuleringen redden.

Tools op de rol afstemmen

De kwaliteit van beschrijvingen en het principe van minimale rechten wijzen in dezelfde richting. Een onderzoeks-subagent hoort geen restitutietool te hebben; een beoordelaar met alleen-lezenrechten hoort geen Write of Bash te hebben.

Afstemming op de rol doet twee dingen tegelijk:

Verwijdert overlappende kandidaten, zodat de overgebleven beschrijvingen gemakkelijker van elkaar te onderscheiden zijn.
Houdt elke agent rond het ideale aantal van 4-5 tools.

Minder, voor de rol relevante tools leiden tot duidelijkere, niet-overlappende beschrijvingen — en precies dat zorgt voor een nauwkeurige selectie.

support_agent = AgentDefinition(
    name="support",
    description="Resolves customer order and refund requests.",
    system_prompt="Verify identity, then resolve the request.",
    allowed_tools=[
        "get_customer",
        "lookup_order",
        "process_refund",
        "escalate_to_human",
    ],  # 4 role-scoped tools, each clearly described
)

Beschrijvingen selecteren; tool_choice beperkt

Beschrijvingen bepalen welke tool past. De parameter tool_choice is een afzonderlijke knop die beperkt of en hoe een tool wordt aangeroepen:

"auto" — het model kiest tekst of een tool (de selectie wordt nog steeds door beschrijvingen gestuurd).
"any" — het model moet een tool aanroepen; nuttig om gestructureerde uitvoer te garanderen.
{"type":"tool","name":"X"} — dwingt één specifieke tool af.

Een tool afdwingen lost een slechte beschrijving niet op — het verwijdert alleen de keuze. Met "auto" of "any" leest het model nog steeds beschrijvingen om uit kandidaten te kiezen, dus de formulering moet nog steeds duidelijk zijn.

resp = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "auto"},  # model selects by reading descriptions
    messages=messages,
)

Waar tools ophouden en resources beginnen

In MCP hoort niet alles een tool te zijn. De server stelt drie primitieven beschikbaar en door de juiste te kiezen blijven je toolbeschrijvingen gericht:

Tools — acties die iets DOEN (een restitutie uitvoeren, een query uitvoeren).
Resources — alleen-lezengegevens en context, zoals schema's of catalogi.
Prompts — herbruikbare sjablonen.

Door een alleen-lezen schema of catalogus als een Resource te modelleren in plaats van als tool, haal je het volledig uit de pool voor actieselectie. Dat is één ambigue kandidaat minder die met je beschrijvingen concurreert, wat de toolselectie direct helpt.

Ook fouten selecteerbaar maken

De selectie stopt niet na de eerste aanroep — vaak moet het model daarna een hersteltool kiezen. Die keuze hangt af van de fout die het terugkrijgt.

Een algemene fout zoals "Bewerking mislukt" geeft het model niets om op te routeren. Een gestructureerde MCP-fout wel:

isError: true en errorCategory (tijdelijk / validatie / zakelijk / toestemming).
isRetryable, een message, de attempted_query en eventuele partial_results.

Hiermee kan het model intelligent beslissen: een tijdelijke fout opnieuw proberen, een validatieprobleem oplossen of een zakelijk probleem of toestemmingsprobleem escaleren — in plaats van vast te lopen.

{
  "isError": true,
  "errorCategory": "transient",
  "isRetryable": true,
  "message": "Order service timed out",
  "attempted_query": "lookup_order(order_id='ORD-10293847')",
  "partial_results": null
}

Korte controle

Pas wat toolselectie aanstuurt toe op een echte fout waarbij de verkeerde tool wordt gekozen.

Beantwoord dit in de interactieve les

Samenvatting

Belangrijkste lessen over toolselectie:

Claude selecteert tools door hun beschrijvingen te lezen, niet hun namen.
Een goede beschrijving vermeldt het doel, de retourwaarden, invoerformaten met voorbeelden, randgevallen en toepassingsgrenzen.
Overlappende of ambigue beschrijvingen leiden tot verkeerde toewijzing; trek expliciete grenzen die elke tool van de andere tools onderscheiden.
Leg randgevallen vast in de beschrijving — vooral lege resultaten tegenover toegangsproblemen en ambigue overeenkomsten.
Houd het bij 4-5 tools per agent; vanaf 18+ neemt de selectie af. Stem tools af op de rol.
tool_choice (auto / any / geforceerd) beperkt het aanroepen, maar vervangt geen duidelijke beschrijving.
Modelleer alleen-lezengegevens als MCP-Resources en geef gestructureerde fouten terug, zodat het model herstel kan routeren.

Gratis beginnen

Leer Python met een AI-tutor — gratis

Schrijf echte code en voer die uit in je browser, krijg direct hulp van een AI-tutor die 24/7 beschikbaar is en ga verder waar je gebleven bent op het web of in de app.

Cursussen: 26
Lessen: 104

Gratis beginnen met leren Bekijk de volledige cursus

Veelgestelde vragen

Is de les “Toolbeschrijvingen sturen de selectie” gratis?

Ja — je kunt hier op het web alle 3 lessen van het leerpad Claude Architect, waaronder “Toolbeschrijvingen sturen de selectie”, gratis volledig lezen. Daarna ontgrendelt CoddyKit PRO alle lessen, plus interactieve oefeningen met een ingebouwde code-editor en een AI-tutor die 24/7 beschikbaar is. De cursus Claude Architect bevat in totaal 4 lessen.

Wat leer ik in “Toolbeschrijvingen sturen de selectie”?

Het model kiest tools op basis van beschrijvingen, niet van namen Je oefent met Claude Architect door code rechtstreeks in de browser uit te voeren. Een AI-begeleider die 24/7 beschikbaar is beantwoordt je vragen terwijl je de les doorwerkt.

Heb ik ervaring nodig om met Claude Architect te beginnen?

Ervaring vooraf is niet nodig. Claude Architect op CoddyKit is opgebouwd voor beginners tot gevorderden, zodat je hier of bij het begin kunt starten en in je eigen tempo kunt leren. Dit is les 1 van 4.

Hoe lang duurt de les “Toolbeschrijvingen sturen de selectie”?

De meeste lessen van CoddyKit duren ongeveer 5–10 minuten. Elke les is kort en interactief, zodat je gestaag vooruitgaat en op het web en in de app precies verdergaat waar je was gebleven.

Kan ik code schrijven en uitvoeren in deze les over Claude Architect?

Ja. Elke les over Claude Architect bevat een ingebouwde code-editor, zodat je rechtstreeks in je browser echte code kunt schrijven en uitvoeren en direct feedback van AI krijgt — lokale installatie is niet nodig.

Alle lessen in deze cursus

← Terug naar Claude Architect