Agent Tool Calling-bedste praksis: Derfor vælger din agent det forkerte værktøj

Agent Tool Calling-bedste praksis: Derfor vælger din agent det forkerte værktøj

Bedste praksis for agent tool calling er det, der står mellem en velfungerende demo og en agent, der i stilhed kalder det forkerte værktøj i produktion. Anthropics ingeniørteam målte, at én omskrevet beskrivelse skar et enkelt værktøjsresultat fra 206 tokens til 72, og Claude Code sætter nu et hårdt loft på 25.000 tokens for hvert værktøjssvar, fordi spildet er reelt. Din agent fejler på fire måder: forkert værktøj, forkerte argumenter, løbske løkker og tokenspild, og hver af dem har en løsning, du kan sende afsted i denne uge.

Nøglepointer:

• Agent tool calling fejler på præcis fire måder: forkert værktøj, forkerte argumenter, løbske løkker og tokenspild.
• Værktøjsbeskrivelser er den eneste instruktion, modellen ser i valgøjeblikket, så de løser de fleste forkerte værktøjskald.
• Flade, opgaveformede skemaer med validerede input fjerner de fleste fejl med forkerte argumenter.
• Korte værktøjssvar og en evalueringsløkke ved hver ændring holder tokenomkostninger og regressioner målbare.

Hvorfor fejler agent tool calling i produktion?

Agent tool calling fejler på fire måder: modellen vælger det forkerte værktøj, skriver forkerte argumenter, kører rundt i en løbsk løkke eller spilder tokens gennem oppustede svar. Hver fejl rammer et forskelligt trin i kaldsløkken, så rækkefølgen på løsningerne betyder noget. Start med valget, for et forkert værktøjsvalg forgifter alle efterfølgende trin.

Den samlede opskrift i ét overblik:

Gå dem igennem i denne rækkefølge. Praksis 1 og 2 tager en eftermiddag og fjerner de fleste af de fejl med forkert værktøj og forkerte argumenter, du ser i dag. En værktøjsbeskrivelse er ikke dokumentation. Det er den eneste instruktion, modellen får i valgøjeblikket.

Fase 1: Design værktøjer, modellen faktisk kan bruge

De billigste stabilitetsgevinster i agent tool calling ligger i dine værktøjsdefinitioner, ikke i dine prompts eller dit modelvalg. Modellen læser aldrig dine API-dokumenter eller din README. Den ser et navn, en beskrivelsesstreng og et JSON-skema, og den beslutter sig udelukkende ud fra dem. Få de tre ting på plads, og valgpræcisionen flytter sig, før du rører noget som helst andet.

Praksis 1: Skriv beskrivelser, modellen kan handle på

Skriv værktøjsbeskrivelser som instruktioner til modellen, ikke som API-dokumentation. En beskrivelse, der tilfredsstiller en menneskelig udvikler ("REST-wrapper for users-endepunktet"), giver modellen intet at beslutte ud fra. Anthropics engineering-guide om at skrive værktøjer og deres bedste praksis for værktøjsdefinitioner peger begge på det samme mønster: sig, hvornår værktøjet skal bruges, hvad det returnerer, og hvornår det IKKE skal bruges.

{
  "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."
}

modsat den version, de fleste teams sender afsted:

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

To regler gør det meste af arbejdet her. For det første: navngiv parametre, så deres betydning er entydig: user_id, aldrig user eller id, fordi user inviterer modellen til at sende et navn eller en e-mail, hvor der hører en UUID til. For det andet: angiv undtagelser eksplicit. "Do NOT use to search users" forhindrer flere forkerte værktøjskald end nok så meget positiv beskrivelse, fordi modeller forveksler overlappende værktøjer langt oftere, end de misforstår enkelte, klart afgrænsede værktøjer. For de udbyderspecifikke mekanikker bag, hvordan definitionerne når OpenAI-, Anthropic- og Google-API'er, se vores multi-provider function calling-guide.

Praksis 2: Hold skemaer flade og opgaveformede

Hold inputskemaer flade, med alle de felter opgaven faktisk har brug for, og ingen den ikke har. Nestede objekter med valgfrie grene er dér, fejlene med forkerte argumenter trives: modellen skal udlede en struktur, den aldrig ser eksempler på. OpenAIs function calling-guide accepterer vilkårlige JSON-skemaer, men tilladende er ikke det samme som pålidelig.

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

Flad den ud til opgaven:

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

Enums slår fri tekst for alle felter med en afgrænset mængde værdier. Required-arrays slår valgfri alt-muligt. Hvis modellen næsten altid har brug for et felt, så gør det required i værktøjsskemaet, selvom dit API kalder det valgfrit. Du spejler ikke dit API. Du designer en flade, som én bestemt model kan udfylde korrekt.

Fase 2: Administrér værktøjssættet, ikke kun værktøjerne

Individuel værktøjskvalitet holder op med at være nok, så snart en agent bærer mere end en håndfuld værktøjer, fordi valgfejlene vokser med størrelsen på den liste, modellen læser.

Praksis 3: Pak flertrins API-sekvenser ind i atomiske værktøjer

Kollaps enhver fast sekvens af API-kald til ét atomisk værktøj. Anthropics engineering-opslag bruger schedule_event og get_customer_context som forbillede: ét kald, der udfører hele jobbet, slår tre kald, som agenten skal kæde korrekt sammen hver gang. Hvert led i en kæde er endnu en tur, hvor modellen kan gå i stå, lave et forkert retry eller køre i ring.

# 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]"]})

Tommelfingerreglen: hvis modellen altid skal kalde B efter A, er A og B ét værktøj i to forklædninger.

Praksis 4: Namespace, beskær og filtrér værktøjer dynamisk

Giv alle værktøjsnavne et namespace, og vis hver agent kun det udsnit, dens aktuelle opgave har brug for. Generiske navne kolliderer i det øjeblik, du forbinder to integrationer. Forestil dig en agent koblet til to MCP-servere, der begge eksponerer et værktøj kaldet search: to identiske udsagnsord, ingen måde at skelne dem ad. Anthropic dokumenterer målbare eval-gevinster ved præfiks-namespacing:

Beskæring betyder lige så meget som navngivning. En supportagent har ikke brug for at have sine faktureringsværktøjer indlæst, mens den besvarer et spørgsmål om en adgangskode. Planner-worker-mønstret, hvor en planner dirigerer en opgave videre til en worker, der kun indlæser de relevante værktøjer, er standardløsningen; LangGraphs how-to om dynamisk værktøjsindlæsning gennemgår implementeringen. Hvor mange værktøjer er for mange? Behandl 5-10 pr. agent som et arbejdsinterval, ikke en lov: præcisionen falder, efterhånden som listen vokser, og kuren er filtrering, ikke en større model. Hvis du er i gang med at vælge selve routing- og filtreringslaget, så sammenlign mulighederne i vores oversigt over de bedste function calling-biblioteker.

Fase 3: Kontrollér, hvad der kommer tilbage, og hvad der sendes ud

Løkken kører begge veje, og de fleste teams designer kun den udgående halvdel. Hvad dine værktøjer returnerer, afgør, hvor stor en del af kontekstvinduet der overlever til næste tur, og hvad din validering afviser, afgør, om modellen lærer af sine fejl eller gentager dem.

Praksis 5: Returnér korte resultater med høj signalværdi

Returnér det mindste resultat, modellen kan handle på, med menneskeligt læsbare identifikatorer i stedet for rå ID'er. Anthropics engineering-opslag dokumenterer et værktøj, hvis standardresultat løb op i 206 tokens; en kort response_format-indstilling skar det samme resultat ned til 72 tokens, omtrent en tredjedel af størrelsen. Gang det med snesevis af kald pr. opgave, og det afgør, om din agent overhovedet bliver færdig.

// 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 mere fra samme kilde: Anthropic understøtter en response_format-enum (detailed kontra concise) i værktøjsdefinitioner, så du kan erklære den form, du vil have, i stedet for at parse hele strømmen. Og Claude Code sætter loft over værktøjssvar ved 25.000 tokens, et hårdt loft der under alle omstændigheder beskærer oppustede resultater. Anthropic rapporterer desuden, som deres eget fund, at opløsning af UUID'er til semantiske navne målbart reducerede retrieval-hallucinationer, hvilket er grunden til, at "efter"-payloaden ovenover siger "Dana Kim" og ikke c9a1...f2. Oppustede svar er også et omkostningsproblem; se vores guide til at reducere LLM API-omkostninger for det fulde billede.

Praksis 6: Validér hvert kald, og gør fejl til læring for modellen

Validér alle værktøjskald på serversiden, og returnér fejl, der indeholder løsningen. Martin Fowler om function calling formulerer det kontant: stol aldrig på modellens output. Den sender strenge, hvor der hører enums til, og opfinder ID'er, der ikke findes.

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)

Fejlstrengen 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 valideringsfejl, dit værktøj returnerer, er en prompt, du skriver til modellens næste forsøg. Fejl, der navngiver begrænsningen og peger på det korrigerende værktøj, forvandler en retry-løkke til en engangsreparation. Det er også din første sikkerhedslinje; vores LLM guardrails-guide dækker det i dybden.

Fase 4: Hvordan gør du det sikkert og derefter målbart?

Sikkerhed og måling er samme fase, fordi en destruktiv handling uden gate og en regression uden måling begge overflader som hændelser, du ikke så komme. Sæt en gate foran de handlinger, der ikke kan fortrydes, og instrumentér derefter alt, så den næste værktøjsændring bliver en beslutning med evidens bag sig, ikke et håb.

Praksis 7: Sæt destruktive handlinger bag en menneskelig gate

Adskil læseværktøjer fra skriveværktøjer, og sæt en menneskelig bekræftelsesgate foran alt destruktivt. MCP-specifikationens værktøjsannotationer findes præcis til dette: destructiveHint markerer værktøjer, der udfører destruktive opdateringer, og openWorldHint markerer værktøjer, der rører eksterne systemer, så klienter kan spørge før eksekvering. Brug dem.

Fejltypen er ikke hypotetisk. Laurent Kubaski dokumenterede en sag i sit tool-calling-opslag fra juli 2025 med link til den oprindelige rapport, hvor en bruger bad Copilot i Excel om at handle på række 4, og agenten handlede på række 8 i stedet. Ingen bekræftelsesgate stod mellem den forkerte række og skrivningen. Løsningen er det mønster, AWS dokumenterer for Bedrock Agents: agenten forbereder handlingen, returnerer den til godkendelse og eksekverer først, efter at et menneske har bekræftet. Cursor gør det samme for filredigeringer. Begræns credentials til read-only, når læsning er alt, opgaven kræver, og behandl bekræftelsesgates som en del af din injektionsoverflade, emnet i vores guide til forebyggelse af prompt injection.

Praksis 8: Kør en evalueringsløkke ved hver værktøjsændring

Kør en lille evalueringssuite før og efter hver værktøjsændring, og læs måltallene i en fast rækkefølge. Paragons optimeringsguide foreslår en ramme med fire måltal, der er værd at overtage:

Anthropics tool evaluation cookbook, bygget på rigtige Slack- og Asana-MCP-evals, viser, hvordan gode og dårlige eval-opgaver ser ud:

# 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."

Vores fortolkning, markeret som sådan: de publicerede tal giver dig rækkefølgen at arbejde i. Tjek værktøjskorrekthed først, fordi Anthropics egne målinger viser, at ændringer i beskrivelser og navngivning flytter den direkte (206-til-72-token-omskrivningen, UUID-til-navn-hallucinationsfundet), og gem opgaveeffektivitet til sidst, da den for det meste afspejler fejl, de første tre måltal allerede har fanget. Til startsuiten: design 15-30 opgaver, to-tre pr. værktøj, hver med ét forventet kald og en binær beståelsesbetingelse. Den størrelse er nok til at fange en regression fra en beskrivelsesomskrivning uden en hel uges labelarbejde, og vi læser cookbookens Slack- og Asana-opsætning som evidens for, at en suite i denne størrelse er det tilsigtede udgangspunkt, ikke en genvej. De dybere mekanikker ligger i vores guide til evaluering af AI-agenter i produktion, og hvis dine eval-resultater siger, at selve værktøjerne er fine, men orkestreringen ikke er, så er det tidspunktet, hvor du bør genoverveje dit frameworkvalg op imod de bedste AI-agent-frameworks.

Agent tool calling vs. MCP: hvad er forskellen?

MCP er en transport- og registreringsstandard, ikke et stabilitetslag, så de samme otte praksisser gælder, uanset om dine værktøjer ankommer via MCP eller er defineret inline. Native tool calling er kontrakten mellem modellen og udbyderen: hvordan modellen udsender et tool_call og læser et tool_result. MCP standardiserer, hvordan værktøjer når modellen; den gør intet ved, om modellen vælger det rigtige.

En MCP-server, der eksponerer et værktøj kaldet search med beskrivelsen "searches things", fejler identisk med en inline-funktion defineret på samme måde. Fiks definitionen først, og bekymr dig om transporten bagefter. Vores Model Context Protocol-guide dækker protokolsiden fra ende til anden.

Hvordan Techsy anvender disse otte praksisser

På alle klientagentprojekter håndhæver vi tre af disse, før noget som helst andet sendes afsted: beskrivelser skrevet som instruktioner (praksis 1), valideringsgates på alle skriveværktøjer (praksis 6) og en eval-suite, der kører før deploy, ikke efter en hændelse (praksis 8). De tre dækker forkerte værktøjskald, kald med forkerte argumenter og de regressioner, der genindfører begge dele, hvilket er dér, hver eneste produktionshændelse med agenter, vi har fejlsøgt, startede. De øvrige fem praksisser følger efter, som agenten vokser. Hvis din agent er forbi demostadiet og vælger de forkerte værktøjer, så få en gratis konsultation, og vi fortæller dig, hvilken af de otte du skal fikse først.

Ofte stillede spørgsmål

Hvad er agent tool calling?

Agent tool calling er den mekanisme, hvor en LLM beslutter sig for at kalde en ekstern funktion, udsender et struktureret tool_call og venter på, at din kode returnerer et tool_result, den kan ræsonnere over. Det er det, der forvandler en chatmodel til en agent, der kan forespørge i databaser, kalde API'er og udføre handlinger: modellen vælger værktøjet og argumenterne, din executor kører dem.

Hvordan fungerer agent tool calling-løkken?

Løkken har fem trin: brugerforespørgslen når modellen, modellen vælger et værktøj og skriver et tool_call, din executor kører det, et tool_result vender tilbage til modellen, og modellen svarer enten eller udsteder endnu et kald. Den cyklus gentages, indtil opgaven er løst. De fire fejltyper i denne guide bor hver især på et bestemt trin i denne løkke.

Hvorfor vælger min agent det forkerte værktøj?

Som regel fordi to værktøjer overlapper, og deres beskrivelser ikke siger, hvilket der er hvilket. Modellen vælger udelukkende ud fra navne og beskrivelser, så "gets a user" kontra "finds users" læses som udskiftelige. Fiks det med undtagelseslinjer ("do NOT use to search"), navne med namespace og færre værktøjer i konteksten. Kubaskis fire-model-test viste, at selv stærke modeller vælger forkert på tvetydige lister.

Hvordan tvinger jeg en tool calling-agent til at strukturere sit output?

Begræns skemaet, ikke prompten. Brug enums til afgrænsede felter, required-arrays til alt, opgaven har brug for, og flade objekter frem for nestede. Til det endelige svar frem for værktøjskaldet tvinger udbyderfunktioner som OpenAIs structured outputs og Anthropics tool-choice-tilstande en bestemt form igennem. Vores guide til structured outputs dækker begge veje med kode.

Agent tool calling vs. MCP: hvad er forskellen?

Native tool calling er kontrakten mellem din kode og én modeludbyder: messageformatet for tool_call og tool_result. MCP er et protokollag, der standardiserer, hvordan værktøjer opdages og leveres til enhver kompatibel klient. MCP ændrer VVS'en, ikke stabiliteten. Et dårligt beskrevet værktøj fejler på samme måde ad begge veje, som vores Model Context Protocol-guide forklarer.

Hvor mange værktøjer er for mange for en LLM-agent?

Behandl 5-10 værktøjer pr. agent som et arbejdsinterval, ikke en lov. Valgpræcisionen falder, efterhånden som den synlige liste vokser, især når navne eller beskrivelser overlapper. Løsningen er ikke en større model, men filtrering: indlæs kun det udsnit, den aktuelle opgave har brug for, med et planner-worker-split. Sæt namespace på alt, så to integrationer aldrig begge eksponerer et bart search.

Hvad er den bedste model til tool calling?

Der findes ikke ét svar, og publicerede benchmarks ældes dårligt på dette område. Frontier-modeller fra OpenAI, Anthropic og Google klarer alle basale tool-use-opgaver, mens mindre modeller parret med veldesignede værktøjer ofte gennemfører opgaver næsten lige så ofte til en brøkdel af tokenomkostningerne. Byg den 15-30 opgaver store eval-suite fra praksis 8, og test kandidaterne mod dine egne værktøjer.

Hvordan reducerer jeg tokenomkostninger fra tool calling?

Skær i det, der kommer tilbage. Returnér korte resultater med høj signalværdi i stedet for rå API-payloads: Anthropic dokumenterede en reduktion fra 206 til 72 tokens fra én response_format-ændring. Opløs UUID'er til navne, drop felter, modellen aldrig bruger, og husk, at hvert værktøjsresultat genindtræder i kontekstvinduet på hver efterfølgende tur. Færre kald via atomiske værktøjer fjerner hele resultater fra regningen.

Hvordan evaluerer jeg kvaliteten af tool calling?

Scor fire måltal i rækkefølge: værktøjskorrekthed (rigtigt værktøj?), inputpræcision (gyldige argumenter?), opgavegennemførelse (mål nået?) og opgaveeffektivitet (antal tokens og kald?). Skriv 15-30 opgaver, hvor hver forventer ét bestemt kald med kontrollerbare argumenter og en binær beståelsesbetingelse. Kør suiten før og efter hver værktøjsændring, så en beskrivelsesomskrivning aldrig sendes afsted umålt.

Konklusion

Diagnosticér, før du optimerer. Din agent vælger det forkerte værktøj af én af fire årsager, og tre af de otte praksisser ovenfor, beskrivelser, flade skemaer og filtrering, løser de valgfejl, der driver de fleste produktionshændelser. Start dér, for de koster en eftermiddag, og de er grunden til, at problemet overhovedet kan løses. Hold valideringsfejl informative, sæt alt destruktivt bag en menneskelig gate, og kør evalueringsløkken ved hver ændring, så du måler, før du skifter model. Problemet med det forkerte værktøj er ikke et modelproblem. Det er et værktøjsdesignproblem, og designet ejer du.