Beste praksis for agent tool calling: Derfor velger agenten din feil verktøy

Beste praksis for agent tool calling: Derfor velger agenten din feil verktøy

Beste praksis for agent tool calling er det som skiller en fungerende demo fra en agent som i stillhet kaller feil verktøy i produksjon. Ingeniørteamet til Anthropic målte at én omskrevet beskrivelse kuttet et verktøysvar fra 206 tokens til 72, og Claude Code har nå et hardt tak på 25 000 tokens per verktøysvar, fordi lekkasjen er reell. Agenten din svikter på fire måter: feil verktøy, feil argumenter, løpske løkker og tokenlekkasje, og hver av dem har en fiks du kan shippe denne uken.

Nøkkelpoeng:

• Agent tool calling feiler på nøyaktig fire måter: feil verktøy, feil argumenter, løpske løkker og tokenlekkasje.
• Verktøybeskrivelsene er den eneste instruksen modellen ser når den velger, så de fikser de fleste feil verktøy-valgene.
• Flate, oppgaveformede skjemaer med validerte input fjerner de fleste feil argument-feilene.
• Konsise verktøysvar og en evalueringsløkke på hver endring holder tokenkostnader og regresjoner målbare.

Hvorfor feiler agent tool calling i produksjon?

Agent tool calling feiler på fire måter: modellen velger feil verktøy, skriver feil argumenter, spinner i en løpsk løkke eller lekker tokens gjennom fete svar. Hver feil rammer et ulikt steg i kall-løkken, så rekkefølgen på fiksene betyr noe. Start med valget, fordi et feil verktøyvalg forgifter alle stegene etter det.

Hele kuren på ett brett:

Jobb gjennom dem i denne rekkefølgen. Praksis 1 og 2 tar en ettermiddag og fjerner de fleste feil verktøy- og feil argument-feilene du ser i dag. En verktøybeskrivelse er ikke dokumentasjon. Den er den eneste instruksen modellen får når den velger.

Fase 1: Design verktøy modellen faktisk kan bruke

De billigste pålitelighetsgevinstene i agent tool calling ligger i verktøydefinisjonene dine, ikke i promptene eller modellvalget. Modellen leser aldri API-dokumentasjonen eller README-en din. Den ser et navn, en beskrivelsesstreng og et JSON-skjema, og bestemmer seg ut fra det alene. Få de tre på plass, og valgpresisjonen flytter seg før du rører noe annet.

Praksis 1: Skriv beskrivelser modellen kan handle etter

Skriv verktøybeskrivelser som instruksjoner til modellen, ikke som API-dokumentasjon. En beskrivelse som tilfredsstiller en menneskelig utvikler («REST-wrapper for users-endepunktet»), gir modellen ingenting å bestemme seg ut fra. Både Anthropics ingeniørguide om å skrive verktøy og deres beste praksis for verktøydefinisjoner pusher det samme mønsteret: si når verktøyet skal brukes, hva det returnerer, og når det IKKE skal brukes.

{
  "name": "get_user",
  "description": "Fetches a user profile. Use ONLY when you already have a user_id. Do NOT use to search or list users; call search_users instead. Returns name, email, plan. Errors if user_id is not a valid UUID."
}

mot versjonen de fleste team shipper:

{
  "name": "get_user",
  "description": "Gets a user."
}

To regler gjør det meste av jobben her. For det første: gi parameterne navn som er entydige: user_id, aldri user eller id, fordi user inviterer modellen til å sende et navn eller en e-post der det hører hjemme en UUID. For det andre: stating eksklusjoner eksplisitt. «Do NOT use to search users» forhindrer flere feil verktøy-kall enn enhver mengde positiv beskrivelse, fordi modeller forveksler overlappende verktøy langt oftere enn de misforstår enkeltstående, tydelig avgrensede verktøy. For mekanikken på leverandørnivå rundt hvordan disse definisjonene når OpenAI, Anthropic og Google sine API-er, se vår guide til function calling med flere leverandører.

Praksis 2: Hold skjemaene flate og oppgaveformede

Hold input-skjemaene flate, med alle feltene oppgaven faktisk trenger og ingen den ikke trenger. Nøstede objekter med valgfrie grener er der feil argument-feilene formerer seg: modellen må utlede en struktur den aldri ser eksempler på. OpenAI sin guide til function calling godtar vilkårlig JSON Schema, men tillatende er ikke det samme som pålitelig.

{
  "name": "create_ticket",
  "parameters": {
    "type": "object",
    "properties": {
      "ticket": {
        "type": "object",
        "properties": {
          "details": {
            "type": "object",
            "properties": {
              "title": { "type": "string" },
              "meta": { "type": "object" }
            }
          }
        }
      }
    }
  }
}

Flat det ut til oppgaven:

{
  "name": "create_ticket",
  "parameters": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "priority": { "type": "string", "enum": ["low", "medium", "high"] },
      "assignee_id": { "type": "string" }
    },
    "required": ["title", "priority"]
  }
}

Enum-er slår fri tekst for alle felt med en avgrenset mengde verdier. Required-arrays slår valgfritt alt sammen. Hvis modellen nesten alltid trenger et felt, gjør det required i verktøyskjemaet selv om API-et ditt kaller det valgfritt. Du speiler ikke API-et ditt. Du designer en flate én bestemt modell kan fylle ut korrekt.

Fase 2: Administrer verktøysettet, ikke bare verktøyene

Kvaliteten på enkeltverktøy slutter å være nok så snart en agent bærer mer enn en håndfull verktøy, fordi valgfeilene vokser med størrelsen på listen modellen leser.

Praksis 3: Pakk flerstepers API-sekvenser inn i atomiske verktøy

Kollaps enhver fast sekvens av API-kall til ett atomisk verktøy. Anthropics ingeniørpost bruker schedule_event og get_customer_context som modell: ett kall som gjør hele jobben, slår tre kall som agenten må kjede sammen korrekt hver gang. Hvert ledd i en kjede er enda en tur der modellen kan stoppe opp, prøve igjen feil eller gå i løkke.

# What the agent does WITHOUT an atomic tool: 3 calls, 3 chances to fail
calendar = call_tool("list_calendars", {})
free = call_tool("find_free_slot", {"calendar_id": calendar["items"][0]["id"], "duration": 30})
call_tool("create_event", {"calendar_id": calendar["items"][0]["id"], "start": free["start"]})

# One atomic tool: the sequence lives in your code, not the model's head
call_tool("schedule_event", {"duration": 30, "attendees": ["[email protected]"]})

Tommelfingerregelen: hvis modellen alltid må kalle B etter A, er A og B ett verktøy i to forkledninger.

Praksis 4: Bruk navnerom, luk ut og filtrer verktøy dynamisk

Gi alle verktøynavn et navnerom, og vis hver agent bare delmengden den aktuelle oppgaven trenger. Generiske navn kolliderer i det øyeblikket du kobler til to integrasjoner. Tenk deg en agent koblet til to MCP-servere som begge eksponerer et verktøy kalt search: to identiske verb, ingen måte å skille dem fra hverandre. Anthropic dokumenterer målbare evalueringsgevinster fra prefiks-navnerom:

Utluke betyr like mye som navngiving. En support-agent trenger ikke faktureringsverktøyene sine lastet inn mens den svarer på et passordspørsmål. Planlegger-arbeider-mønsteret, der en planlegger ruter en oppgave til en arbeider som bare laster inn de relevante verktøyene, er standardfiksen; LangGraph sin how-to om dynamisk verktøylasting går gjennom implementasjonen. Hvor mange verktøy er for mange? Behandle 5-10 per agent som et arbeidsintervall, ikke en lov: presisjonen synker etter hvert som listen vokser, og kuren er filtrering, ikke en større modell. Hvis du akkurat nå velger selve rutings- og filtreringslaget, sammenlign alternativene i vår oversikt over de beste function calling-bibliotekene.

Fase 3: Kontroller det som kommer tilbake og det som går ut

Løkken går begge veier, og de fleste team ingeniører bare den utgående halvdelen. Det verktøyene dine returnerer, avgjør hvor mye av kontekstvinduet som overlever til neste tur, og det valideringen din avviser, avgjør om modellen lærer av feilene sine eller gjentar dem.

Praksis 5: Returner konsise svar med høy signalverdi

Returner det minste svaret modellen kan handle på, med menneskelig lesbare identifikatorer i stedet for rå ID-er. Anthropic sin ingeniørpost dokumenterer et verktøy der standardsvaret løp på 206 tokens; en konsis response_format-innstilling kuttet det samme svaret til 72 tokens, omtrent en tredjedel av størrelsen. Gang det med titalls kall per oppgave, og det avgjør om agenten din i det hele tatt kommer i mål.

// Before: 206 tokens (shape per Anthropic's documented example)
{
  "status": "success",
  "data": {
    "id": "8f14e45f-ceea-3f9c-a2f3-90c1b5e0a7d2",
    "object": "task", "created_at": "2026-07-02T09:14:00Z",
    "updated_at": "2026-07-11T16:40:12Z", "completed_at": null,
    "assignee": {"id": "c9a1...f2", "object": "user"},
    "projects": [{"id": "b7d3...91", "object": "project"}],
    "permalink": "https://app.asana.com/0/.../f"
  }
}

// After: 72 tokens
{ "task": "Fix login redirect", "assignee": "Dana Kim", "project": "Web App", "due": "2026-07-20" }

To detaljer til fra samme kilde: Anthropic støtter en response_format-enum (detaljert versus konsis) på verktøydefinisjoner, slik at du kan deklarere formen du vil ha, i stedet for å parse brannslangen. Og Claude Code setter tak på verktøysvar ved 25 000 tokens, et hardt tak som trunkerer oppblåste svar uansett. Anthropic rapporterer også, som sitt eget funn, at det å slå opp UUID-er til semantiske navn målbart reduserte hentingshallusinasjoner, og det er grunnen til at «etter»-nyttelasten over sier «Dana Kim» og ikke c9a1...f2. Fete svar er også et kostnadsproblem; se vår guide til å redusere LLM-API-kostnader for hele bildet.

Praksis 6: Valider hvert kall og la feilene lære modellen

Valider alle verktøykall på serversiden, og returner feilmeldinger som inneholder fiksen. Martin Fowler sitt stykke om function calling formulerer det rett på sak: stol aldri på modellens output. Den sender strenger der det hører hjemme enum-er, og finner opp ID-er som ikke finnes.

def create_ticket(args):
    if args.get("priority") not in {"low", "medium", "high"}:
        return {"error": f"priority must be one of: low, medium, high. Got '{args.get('priority')}'. Pass priority='medium' for normal issues."}
    if not is_valid_uuid(args.get("assignee_id")):
        return {"error": "assignee_id must be a UUID. Call list_team_members to get valid IDs, then retry."}
    return db.create_ticket(**args)

Feilstrengen er hele spillet. Sammenlign:

# Unhelpful: the model retries the same bad call
{"error": "invalid input"}

# Helpful: the model knows exactly what to change
{"error": "priority must be one of: low, medium, high. Got 'urgent'. Use 'high'."}

Hver valideringsfeil verktøyet ditt returnerer, er en prompt du skriver for modellens neste forsøk. Feil som navngir begrensningen og peker på det korrigerende verktøyet, gjør en retry-løkke om til en engangs-gjenoppretting. Dette er også din første sikkerhetslinje; vår guide til LLM-guardrails dekker det i dybden.

Fase 4: Hvordan gjør du det trygt, og deretter målbart?

Sikkerhet og måling er samme fase, fordi en destruktiv handling uten sperre og en regresjon uten måling begge dukker opp som hendelser du ikke kunne se komme. Sett sperre på handlingene som ikke kan angres, og instrumenter deretter alt, slik at den neste verktøyendringen blir en beslutning med bevis bak, ikke et håp.

Praksis 7: Sett destruktive handlinger bak en menneskelig sperre

Skill leseverktøy fra skriveverktøy, og sett en menneskelig bekreftelsessperre på alt som er destruktivt. MCP-spesifikasjonens verktøyannotasjoner finnes nøyaktig for dette: destructiveHint markerer verktøy som utfører destruktive oppdateringer, og openWorldHint flagger verktøy som berører eksterne systemer, slik at klienter kan spørre før de kjører. Bruk dem.

Feilmodusen er ikke hypotetisk. Laurent Kubaski dokumenterte et tilfelle, i sin tool-calling-gjennomgang fra juli 2025 med lenke til den opprinnelige rapporten, der en bruker ba Copilot i Excel om å gjøre noe med rad 4, og agenten handlet på rad 8 i stedet. Ingen bekreftelsessperre sto mellom feil rad og skriveoperasjonen. Fiksen er mønsteret AWS dokumenterer for Bedrock Agents: agenten forbereder handlingen, returnerer den for godkjenning og kjører den først etter at et menneske bekrefter. Cursor gjør det samme for filredigeringer. Begrens credentials til skrivebeskyttet der lesing er alt oppgaven trenger, og behandle bekreftelsessperrer som en del av injeksjonsflaten din, temaet i vår guide til forebygging av prompt-injection.

Praksis 8: Kjør en evalueringsløkke på hver verktøyendring

Kjør en liten evalueringssuite før og etter hver verktøyendring, og les metrikkene i en fast rekkefølge. Paragon sin optimaliseringsguide foreslår et fire-metrikker-rammeverk verdt å adoptere:

Anthropic sin tool evaluation cookbook, bygget på reelle Slack- og Asana-MCP-evalueringer, viser hvordan gode og dårlige evalueringsoppgaver ser ut:

# Weak: vague, many valid paths, impossible to score
"Use the Asana tools to organize some work."

# Strong: one correct tool, checkable arguments, binary outcome
"Create a task titled 'Renew TLS cert' in project 'Infra' assigned to [email protected], due 2026-08-15. Expect exactly one create_task call with those four fields."

Vår tolkning, merket som sådan: de publiserte tallene gir deg rekkefølgen du skal jobbe i. Sjekk verktøykorrekthet først, fordi Anthropics egne målinger viser at beskrivelses- og navngivingsendringer flytter den direkte (206-til-72-token-omskrivingen, UUID-til-navn-hallusinasjonsfunnet), og la oppgaveeffektivitet stå til slutt, siden den stort sett gjenspeiler feil de første tre metrikkene allerede fanget. For startsuiten: design 15-30 oppgaver, to eller tre per verktøy, hver med ett forventet kall og en binær bestått-betingelse. Den størrelsen er nok til å fange en regresjon fra en beskrivelsesomskriving uten en uke med merking, og vi leser cookbook-ens Slack- og Asana-oppsett som bevis på at en suite så liten er det tiltenkte startpunktet, ikke en snarvei. Den dypere mekanikken ligger i vår guide til evaluering av AI-agenter i produksjon, og hvis evalueringsresultatene dine sier at selve verktøyene er fine, men orkestreringen ikke, er det tidspunktet for å revurdere rammeverkvalget ditt opp mot de beste AI-agent-rammeverkene.

Agent tool calling kontra MCP: hva er forskjellen?

MCP er en transport- og registreringsstandard, ikke et pålitelighetslag, så de samme åtte praksisene gjelder enten verktøyene dine kommer over MCP eller er definert inline. Nativ tool calling er kontrakten med modellleverandøren: hvordan modellen utsteder en tool_call og leser et tool_result. MCP standardiserer hvordan verktøy når modellen; den gjør ingenting med om modellen velger det riktige.

En MCP-server som eksponerer et verktøy kalt search med beskrivelsen «searches things», feiler identisk med en inline-funksjon definert på samme måte. Fiks definisjonen først, og bekymre deg for transporten etterpå. Vår Model Context Protocol-guide dekker protokollsiden ende til ende.

Hvordan Techsy bruker disse åtte praksisene

På hvert eneste klient-agent-bygg håndhever vi tre av disse før noe annet shippes: beskrivelser skrevet som instruksjoner (praksis 1), valideringssperrer på alle skriveverktøy (praksis 6) og en evalueringssuite som kjøres før deploy, ikke etter en hendelse (praksis 8). De tre dekker feil verktøy-kall, feil argument-kall og regresjonene som gjeninnfører begge, og det er der hver eneste produksjonsagent-hendelse vi har feilsøkt startet. De fem andre praksisene følger etter hvert som agenten vokser. Hvis agenten din er forbi demostadiet og velger feil verktøy, få en gratis konsultasjon, så forteller vi deg hvilken av de åtte du skal fikse først.

Ofte stilte spørsmål

Hva er agent tool calling?

Agent tool calling er mekanismen der en LLM bestemmer seg for å kalle en ekstern funksjon, utsteder en strukturert tool_call og venter på at koden din returnerer et tool_result den kan resonnere over. Det er dette som gjør en chatmodell om til en agent som kan spørre databaser, kalle API-er og utføre handlinger: modellen velger verktøyet og argumentene, eksekvereren din kjører dem.

Hvordan fungerer agent tool calling-løkken?

Løkken har fem steg: brukerforespørselen når modellen, modellen velger et verktøy og skriver en tool_call, eksekvereren din kjører den, et tool_result returnerer til modellen, og modellen svarer enten eller utsteder et nytt kall. Den syklusen gjentar seg til oppgaven er ferdig. De fire feilmodusene i denne guiden bor hver på ett bestemt steg i denne løkken.

Hvorfor velger agenten min feil verktøy?

Vanligvis fordi to verktøy overlapper, og beskrivelsene deres ikke sier hvilket som er hvilket. Modellen velger ut fra navn og beskrivelser alene, så «gets a user» kontra «finds users» leses som utbyttbare. Fiks det med ekslusjonslinjer («do NOT use to search»), navn med navnerom og færre verktøy i konteksten. Kubaskis fire-modellers test viste at til og med sterke modeller ruter feil på tvetydige lister.

Hvordan tvinger jeg en tool calling-agent til å strukturere output-en sin?

Begrens skjemaet, ikke prompten. Bruk enum-er for avgrensede felt, required-arrays for alt oppgaven trenger, og flate objekter fremfor nøstede. For det endelige svaret i stedet for verktøykallet tvinger leverandørfunksjoner som OpenAI sine strukturerte output-er og Anthropic sine tool-choice-modi en bestemt form. Vår guide til strukturerte utdata dekker begge veier med kode.

Agent tool calling kontra MCP: hva er forskjellen?

Nativ tool calling er kontrakten mellom koden din og én modellleverandør: meldingsformatet tool_call og tool_result. MCP er et protokollag som standardiserer hvordan verktøy oppdages og leveres til enhver kompatibel klient. MCP endrer rørleggerarbeidet, ikke påliteligheten. Et dårlig beskrevet verktøy feiler på samme måte over begge veier, slik vår Model Context Protocol-guide forklarer.

Hvor mange verktøy er for mange for en LLM-agent?

Behandle 5-10 verktøy per agent som et arbeidsintervall, ikke en lov. Valgpresisjonen synker etter hvert som den synlige listen vokser, spesielt når navn eller beskrivelser overlapper. Fiksen er ikke en større modell, men filtrering: last bare inn delmengden den aktuelle oppgaven trenger, med et planlegger-arbeider-skille. Gi alt et navnerom, slik at to integrasjoner aldri begge eksponerer en bar search.

Hva er den beste modellen for tool calling?

Det finnes ikke ett svar, og publiserte benchmarker eldes dårlig i dette feltet. Grensemodeller fra OpenAI, Anthropic og Google klarer alle grunnleggende verktøybruksoppgaver, mens mindre modeller parret med veldesignede verktøy ofte fullfører oppgaver nesten like ofte til en brøkdel av tokenkostnaden. Bygg 15-30-oppgavesuiten fra praksis 8, og test kandidatene mot dine egne verktøy.

Hvordan reduserer jeg tokenkostnadene fra tool calling?

Kutt det som kommer tilbake. Returner konsise svar med høy signalverdi i stedet for rå API-payloads: Anthropic dokumenterte et 206-til-72-token-kutt fra én response_format-endring. Slå opp UUID-er til navn, dropp felt modellen aldri bruker, og husk at hvert verktøysvar går inn i kontekstvinduet igjen på hver påfølgende tur. Færre kall, via atomiske verktøy, fjerner hele svar fra regningen.

Hvordan evaluerer jeg kvaliteten på tool calling?

Skår fire metrikker i rekkefølge: verktøykorrekthet (riktig verktøy?), input-presisjon (gyldige argumenter?), oppgavefullføring (mål oppnådd?) og oppgaveeffektivitet (antall tokens og kall?). Skriv 15-30 oppgaver, der hver forventer ett bestemt kall med kontrollerbare argumenter og en binær bestått-betingelse. Kjør suiten før og etter hver verktøyendring, slik at en beskrivelsesomskriving aldri shippes umålt.

Konklusjon

Diagnostiser før du optimaliserer. Agenten din velger feil verktøy av én av fire grunner, og tre av de åtte praksisene over, beskrivelser, flate skjemaer og filtrering, fikser valgfeilene som driver de fleste produksjonshendelsene. Start der, fordi de koster en ettermiddag, og de er grunnen til at dette problemet i det hele tatt lar seg fikse. Hold valideringsfeil informative, sett alt destruktivt bak en menneskelig sperre, og kjør evalueringsløkken på hver endring, slik at du måler før du bytter modell. Feil verktøy-problemet er ikke et modellproblem. Det er et verktøydesignproblem, og designet eier du.