Bästa praxis för agent tool calling: Därför väljer din agent fel verktyg

Bästa praxis för agent tool calling: Därför väljer din agent fel verktyg

Bästa praxis för agent tool calling är det som skiljer en fungerande demo från en agent som i tysthet anropar fel verktyg i produktion. Anthropics engineeringteam mätte hur en enda omskriven beskrivning kapade ett verktygssvar från 206 tokens till 72, och Claude Code sätter idag ett hårt tak på 25 000 tokens per verktygssvar eftersom läckaget är verkligt. Din agent kan falla på fyra sätt: fel verktyg, fel argument, skenande loopar och tokenläckage. Varje fel har en åtgärd du kan skeppa den här veckan.

Det viktigaste:

• Agent tool calling fallerar på exakt fyra sätt: fel verktyg, fel argument, skenande loopar och tokenläckage.
• Verktygsbeskrivningarna är den enda instruktion modellen ser vid valtidpunkten, så de löser de flesta felverktygsanrop.
• Platt, uppgiftsformade scheman med validerade indata tar bort de flesta felen med argumenten.
• Koncisa verktygssvar och en utvärderingsloop vid varje ändring håller tokenkostnad och regressioner mätbara.

Varför fallerar agent tool calling i produktion?

Agent tool calling fallerar på fyra sätt: modellen väljer fel verktyg, skriver fel argument, snurrar fast i en skenande loop eller läcker tokens genom överviktiga svar. Varje fel drabbar ett eget steg i anropsloopen, så ordningen på åtgärderna spelar roll. Börja med valet, eftersom ett felaktigt verktygsval förgiftar varje steg som följer.

Hela receptet i korthet:

Arbeta igenom dem i den här ordningen. Praxis 1 och 2 tar en eftermiddag och tar bort de flesta felen med verktygsval och argument som du ser idag. En verktygsbeskrivning är inte dokumentation. Det är den enda instruktion modellen får vid valtidpunkten.

Fas 1: Designa verktyg som modellen faktiskt kan använda

De billigaste tillförlitlighetsvinsterna inom agent tool calling finns i dina verktygsdefinitioner, inte i dina prompter eller ditt modellval. Modellen läser aldrig din API-dokumentation eller din README. Den ser ett namn, en beskrivningssträng och ett JSON-schema, och den bestämmer sig utifrån enbart det. Få de tre delarna rätt så flyttar sig valträffsäkerheten innan du rör något annat.

Praxis 1: Skriv beskrivningar som modellen kan agera på

Skriv verktygsbeskrivningar som instruktioner till modellen, inte som API-dokumentation. En beskrivning som tillfredsställer en mänsklig utvecklare ("REST-wrapper för users-endpointen") ger modellen ingenting att bestämma sig utifrån. Både Anthropics engineeringguide om att skriva verktyg och deras bästa praxis för verktygsdefinitioner driver samma mönster: säg när verktyget ska användas, vad det returnerar och när det INTE ska användas.

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

jämfört med versionen de flesta team skeppar:

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

Två regler gör det mesta av jobbet här. För det första: namnge parametrar så att deras betydelse är entydig: user_id, aldrig user eller id, eftersom user lockar modellen att skicka ett namn eller en e-postadress där ett UUID hör hemma. För det andra: ange undantag uttryckligen. "Använd INTE för att söka användare" förhindrar fler felverktygsanrop än vilken mängd positiv beskrivning som helst, eftersom modeller blandar ihop överlappande verktyg långt oftare än de missförstår enskilda, tydligt avgränsade sådana. För mekaniken på providernivå, hur dessa definitioner når OpenAI:s, Anthropics och Googles API:er, se vår guide om function calling med flera leverantörer.

Praxis 2: Håll scheman platta och uppgiftsformade

Håll indata-scheman platta, med varje fält som uppgiften faktiskt behöver och inga andra. Nästlade objekt med valfria grenar är där felaktiga argument föds: modellen måste gissa en struktur den aldrig sett exempel på. OpenAI:s guide om function calling accepterar godtyckligt JSON Schema, men tillåtande är inte samma sak som tillförlitligt.

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

Platta ut det till uppgiften:

{
  "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 text för varje fält med en begränsad mängd värden. Required-arrayer slår valfrihet överallt. Om modellen nästan alltid behöver ett fält, gör det obligatoriskt i verktygsschemat även om ditt API kallar det valfritt. Du speglar inte ditt API. Du designar en yta som en specifik modell kan fylla i korrekt.

Fas 2: Hantera verktygsmängden, inte bara verktygen

Kvaliteten på enskilda verktyg räcker inte längre när en agent bär på fler än en handfull verktyg, eftersom valfelen växer med storleken på listan som modellen läser.

Praxis 3: Kapsla flerstegssekvenser av API-anrop till atomära verktyg

Slå ihop varje fast sekvens av API-anrop till ett enda atomärt verktyg. Anthropics engineeringinlägg använder schedule_event och get_customer_context som förebilder: ett anrop som gör hela jobbet slår tre anrop som agenten måste kedja ihop korrekt varje gång. Varje länk i kedjan är ytterligare en tur där modellen kan stanna av, försöka igen på fel sätt eller loopa.

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

Tumregeln: om modellen alltid måste anropa B efter A är A och B ett och samma verktyg i två förklädnader.

Praxis 4: Använd namnrymder, rensa och filtrera verktyg dynamiskt

Sätt varje verktygsnamn i en namnrymd och visa varje agent bara den delmängd som dess aktuella uppgift kräver. Generiska namn kolliderar i samma stund som du kopplar in två integrationer. Tänk dig en agent kopplad till två MCP-servrar som båda exponerar ett verktyg som heter search: två identiska verb utan något sätt att skilja dem åt. Anthropic dokumenterar mätbara eval-vinster från prefixbaserade namnrymder:

Att rensa bort verktyg är lika viktigt som namngivningen. En supportagent behöver inte ha sina faktureringsverktyg inlästa medan den svarar på en lösenordsfråga. Planner-worker-mönstret, där en planerare routar en uppgift till en arbetare som bara läser in de relevanta verktygen, är standardlösningen; LangGraph:s guide om dynamisk verktygsinläsning går igenom implementationen. Hur många verktyg är för många? Behandla 5-10 per agent som ett riktvärde, inte en lag: träffsäkerheten sjunker när listan växer, och botemedlet är filtrering, inte en större modell. Om du håller på att välja själva routing- och filtreringslagret, jämför alternativen i vår genomgång av de bästa function calling-biblioteken.

Fas 3: Styr vad som kommer tillbaka och vad som går ut

Loopen löper åt båda hållen, och de flesta team ingenjörsarbetar bara med den utgående halvan. Vad dina verktyg returnerar avgör hur mycket av kontextfönstret som överlever till nästa tur, och vad din validering avvisar avgör om modellen lär sig av sina misstag eller upprepar dem.

Praxis 5: Returnera koncisa, signalrika svar

Returnera det minsta svar modellen kan agera på, med mänskligt läsbara identifierare i stället för råa ID:n. Anthropics engineeringinlägg dokumenterar ett verktyg vars standardsvar landade på 206 tokens; en koncis response_format-inställning kapade samma svar till 72 tokens, ungefär en tredjedel av storleken. Multiplicera det med dussintals anrop per uppgift så avgör det om din agent överhuvudtaget blir klar.

// 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" }

Ytterligare två detaljer från samma källa: Anthropic stödjer en response_format-enum (detaljerad kontra koncis) på verktygsdefinitioner, så att du kan deklarera den form du vill ha i stället för att parsa hela flödet. Och Claude Code takar verktygssvar vid 25 000 tokens, ett hårt tak som trunkerar uppblåsta svar hur som helst. Anthropic rapporterar också, som sitt eget fynd, att uppslagning av UUID:n till semantiska namn mätbart minskade hämtningshallucinationer, vilket är varför "efter"-payloaden ovan säger "Dana Kim" och inte c9a1...f2. Överviktiga svar är också ett kostnadsproblem; se vår guide om att minska LLM API-kostnader för helhetsbilden.

Praxis 6: Validera varje anrop och låt felen lära modellen

Validera varje verktygsanrop på serversidan och returnera felmeddelanden som innehåller lösningen. Martin Fowlers artikel om function calling formulerar det rakt på sak: lita aldrig på modellens utdata. Den skickar strängar där enums hör hemma och hittar på ID:n som inte existerar.

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)

Felsträngen är hela spelet. Jämför:

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

Varje valideringsfel ditt verktyg returnerar är en prompt du skriver för modellens nästa försök. Fel som namnger begränsningen och pekar på det korrigerande verktyget förvandlar en retry-loop till en engångsåterställning. Det här är också din första försvarslinje för säkerheten; vår LLM guardrails-guide täcker det på djupet.

Fas 4: Hur gör du det säkert, och sedan mätbart?

Säkerhet och mätning är samma fas, eftersom en ospärrad destruktiv åtgärd och en omätt regression båda visar sig som incidenter du inte kunde se komma. Spärra av de åtgärder som inte kan göras ogjorda, instrumentera sedan allt så att nästa verktygsändring blir ett beslut med bevis bakom sig, inte ett hopp.

Praxis 7: Sätt destruktiva åtgärder bakom en mänsklig spärr

Separera läsverktyg från skrivverktyg och sätt en mänsklig bekräftelsespärr på allt som är destruktivt. MCP-specifikationens verktygsannoteringar finns till för exakt detta: destructiveHint markerar verktyg som utför destruktiva uppdateringar, och openWorldHint flaggar verktyg som rör externa system, så att klienter kan fråga innan de kör. Använd dem.

Felkällan är inte hypotetisk. Laurent Kubaski dokumenterade ett fall i sin tool calling-genomgång från juli 2025, med den ursprungliga rapporten länkad, där en användare bad Copilot i Excel att agera på rad 4 och agenten i stället agerade på rad 8. Ingen bekräftelsespärr stod mellan den felaktiga raden och skrivningen. Lösningen är mönstret som AWS dokumenterar för Bedrock Agents: agenten förbereder åtgärden, returnerar den för godkännande och kör först efter att en människa bekräftat. Cursor gör samma sak för filredigeringar. Begränsa behörigheter till skrivskyddat där läsning är allt uppgiften kräver, och behandla bekräftelsespärrar som en del av din injektionsyta, ämnet för vår guide om förhindrande av prompt injection.

Praxis 8: Kör en utvärderingsloop vid varje verktygsändring

Kör en liten utvärderingssvit före och efter varje verktygsändring, och läs mätvärdena i en fast ordning. Paragons optimeringsguide föreslår ett ramverk med fyra mätvärden som är värt att ta efter:

Anthropics tool evaluation cookbook, byggd på riktiga Slack- och Asana-MCP-evals, visar hur bra och dåliga eval-uppgifter 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, markerad som sådan: de publicerade siffrorna ger dig ordningen att arbeta i. Kontrollera verktygskorrekthet först, eftersom Anthropics egna mätningar visar att ändringar av beskrivningar och namn flyttar den direkt (omskrivningen från 206 till 72 tokens, fyndet om UUID-till-namn-hallucinationer), och lämna uppgiftseffektivitet till sist, eftersom den mestadels speglar fel som de första tre mätvärdena redan fångat. Designa 15-30 uppgifter för startsviten, två eller tre per verktyg, var och en med ett enda förväntat anrop och ett binärt godkänningsvillkor. Den storleken räcker för att fånga en regression från en omskriven beskrivning utan en veckas etikettering, och vi läser cookbookens Slack- och Asana-upplägg som ett belägg för att en så här liten svit är den avsedda startpunkten, inte en genväg. Den djupare mekaniken finns i vår guide om att utvärdera AI-agenter i produktion, och om dina eval-resultat säger att själva verktygen är okej men orkestreringen inte, då är det dags att ompröva ditt ramverksval mot de bästa AI-agent-ramverken.

Agent tool calling kontra MCP: vad är skillnaden?

MCP är en transport- och registerstandard, inte ett tillförlitlighetslager, så samma åtta praxis gäller oavsett om dina verktyg anländer via MCP eller definieras inline. Native tool calling är kontraktet mellan modellen och providern: hur modellen avger en tool_call och läser en tool_result. MCP standardiserar hur verktyg når modellen; det gör ingenting åt om modellen väljer rätt.

En MCP-server som exponerar ett verktyg med namnet search och beskrivningen "searches things" fallerar identiskt med en inline-funktion definierad på samma sätt. Fixa definitionen först, oroa dig sedan för transporten. Vår Model Context Protocol-guide täcker protokollsidan från början till slut.

Så här tillämpar Techsy de åtta praxisarna

I varje agentbygge för en kund tvingar vi igenom tre av dessa innan något annat skeppas: beskrivningar skrivna som instruktioner (praxis 1), valideringsspärrar på varje skrivverktyg (praxis 6) och en eval-svit som körs före deploy, inte efter en incident (praxis 8). De tre täcker felverktygsanrop, felaktiga argument och de regressioner som återinför båda, vilket är där varje produktionsagentincident vi har felsökt började. De övriga fem praxisarna följer efter när agenten växer. Om din agent är förbi demostadiet och väljer fel verktyg, boka en kostnadsfri konsultation så berättar vi vilken av de åtta du ska fixa först.

Vanliga frågor

Vad är agent tool calling?

Agent tool calling är mekanismen där en LLM bestämmer sig för att anropa en extern funktion, avger en strukturerad tool_call och väntar på att din kod ska returnera en tool_result som den kan resonera kring. Det är det som förvandlar en chattmodell till en agent som kan fråga databaser, anropa API:er och vidta åtgärder: modellen väljer verktyg och argument, din executor kör dem.

Hur fungerar agent tool calling-loopen?

Loopen har fem steg: användarens begäran når modellen, modellen väljer ett verktyg och skriver en tool_call, din executor kör den, en tool_result återvänder till modellen och modellen antingen svarar eller skickar ytterligare ett anrop. Den cykeln upprepas tills uppgiften är klar. De fyra felkällorna i den här guiden bor var och en på ett specifikt steg i loopen.

Varför väljer min agent fel verktyg?

Oftast för att två verktyg överlappar och deras beskrivningar inte säger vilket som är vilket. Modellen väljer enbart utifrån namn och beskrivningar, så "gets a user" kontra "finds users" läses som utbytbara. Lös det med undantagsrader ("använd INTE för att söka"), namn i namnrymder och färre verktyg i kontexten. Kubaskis test med fyra modeller visade att även starka modeller väljer fel på tvetydiga listor.

Hur tvingar jag en tool calling-agent att strukturera sina utdata?

Begränsa schemat, inte prompten. Använd enums för avgränsade fält, required-arrayer för allt uppgiften behöver och platta objekt framför nästlade. För det slutgiltiga svaret snarare än verktygsanropet tvingar providerfunktioner som OpenAI:s structured outputs och Anthropics tool-choice-lägen fram en specifik form. Vår guide om strukturerade utdata täcker båda vägarna med kod.

Agent tool calling kontra MCP: vad är skillnaden?

Native tool calling är kontraktet mellan din kod och en modellprovider: meddelandeformatet för tool_call och tool_result. MCP är ett protokollager som standardiserar hur verktyg upptäcks och levereras till valfri kompatibel klient. MCP ändrar rörmokeriet, inte tillförlitligheten. Ett dåligt beskrivet verktyg fallerar på samma sätt via båda vägarna, vilket vår Model Context Protocol-guide förklarar.

Hur många verktyg är för många för en LLM-agent?

Behandla 5-10 verktyg per agent som ett riktvärde, inte en lag. Valträffsäkerheten sjunker när den synliga listan växer, särskilt när namn eller beskrivningar överlappar. Lösningen är inte en större modell utan filtrering: läs bara in den delmängd den aktuella uppgiften behöver, med en planner-worker-uppdelning. Sätt allt i namnrymder så att två integrationer aldrig båda exponerar ett naket search.

Vilken är den bästa modellen för tool calling?

Det finns inget enskilt svar, och publicerade benchmarks åldras dåligt på det här området. De ledande modellerna från OpenAI, Anthropic och Google klarar alla grundläggande tool use-uppgifter, medan mindre modeller parade med väldesignade verktyg ofta slutför uppgifter nästan lika ofta till en bråkdel av tokenkostnaden. Bygg eval-sviten med 15-30 uppgifter från praxis 8 och testa kandidaterna mot dina egna verktyg.

Hur minskar jag tokenkostnaden från tool calling?

Kapa det som kommer tillbaka. Returnera koncisa, signalrika svar i stället för råa API-payloads: Anthropic dokumenterade en kapning från 206 till 72 tokens från en enda response_format-ändring. Slå upp UUID:n till namn, ta bort fält modellen aldrig använder och kom ihåg att varje verktygssvar återinträder i kontextfönstret på varje följande tur. Färre anrop, via atomära verktyg, tar bort hela svar från notan.

Hur utvärderar jag kvaliteten på tool calling?

Sätt poäng på fyra mätvärden i ordning: verktygskorrekthet (rätt verktyg?), indataträffsäkerhet (giltiga argument?), uppgiftsslutförande (mål uppnått?) och uppgiftseffektivitet (antal tokens och anrop?). Skriv 15-30 uppgifter, där varje uppgift förväntar sig ett specifikt anrop med kontrollerbara argument och ett binärt godkänningsvillkor. Kör sviten före och efter varje verktygsändring så att en omskrivning av en beskrivning aldrig skeppas omätt.

Slutsats

Diagnosticera innan du optimerar. Din agent väljer fel verktyg av en av fyra anledningar, och tre av de åtta praxisarna ovan, beskrivningar, platta scheman och filtrering, löser de valfel som driver de flesta produktionsincidenter. Börja där, eftersom de kostar en eftermiddag och är anledningen till att problemet överhuvudtaget går att lösa. Håll valideringsfel informativa, sätt allt destruktivt bakom en mänsklig spärr och kör eval-loopen vid varje ändring så att du mäter innan du byter modell. Fel verktyg-problemet är inte ett modellproblem. Det är ett verktygsdesignproblem, och designen äger du.