Best practice per il tool calling degli agenti AI: perché il tuo agente sceglie il tool sbagliato

Best practice per il tool calling degli agenti AI: perché il tuo agente sceglie il tool sbagliato

Le best practice per il tool calling degli agenti sono ciò che separa una demo funzionante da un agente che, in produzione, chiama silenziosamente il tool sbagliato. Il team di ingegneria di Anthropic ha misurato che una singola descrizione riscritta ha ridotto il risultato di un tool da 206 a 72 token, e Claude Code oggi impone un tetto rigido di 25.000 token a ogni risposta dei tool, perché l'emorragia è reale. Il tuo agente fallisce in quattro modi: tool sbagliato, argomenti sbagliati, loop fuori controllo, spreco di token. E ognuno ha una soluzione che puoi rilasciare questa settimana.

Punti chiave:

• Il tool calling degli agenti fallisce in esattamente quattro modi: tool sbagliato, argomenti sbagliati, loop fuori controllo e spreco di token.
• Le descrizioni dei tool sono l'unica istruzione che il modello vede al momento della selezione, quindi risolvono la maggior parte delle chiamate al tool sbagliato.
• Schemi flat, modellati sul compito e con input validati eliminano quasi tutti i fallimenti per argomenti errati.
• Risposte dei tool concise e un ciclo di valutazione a ogni modifica mantengono misurabili costi dei token e regressioni.

Perché il tool calling degli agenti fallisce in produzione?

Il tool calling degli agenti fallisce in quattro modi: il modello sceglie il tool sbagliato, scrive argomenti sbagliati, gira a vuoto in un loop fuori controllo oppure brucia token con risposte troppo grasse. Ogni guasto colpisce un punto diverso del loop di chiamata, quindi l'ordine delle correzioni conta. Parti dalla selezione, perché una scelta sbagliata del tool avvelena tutti i passi successivi.

La prescrizione completa in sintesi:

Segui questo ordine. Le pratiche 1 e 2 richiedono un pomeriggio ed eliminano la maggior parte dei guasti da tool sbagliato e argomenti sbagliati che vedi oggi. Una descrizione di tool non è documentazione: è l'unica istruzione che il modello riceve al momento della selezione.

Fase 1: Progetta tool che il modello può usare davvero

I guadagni di affidabilità più economici nel tool calling degli agenti stanno nelle definizioni dei tool, non nei prompt o nella scelta del modello. Il modello non legge mai la documentazione delle tue API né il tuo README. Vede un nome, una stringa di descrizione e uno schema JSON, e decide solo in base a quelli. Azzecca quei tre elementi e la precisione della selezione migliora prima ancora di toccare qualsiasi altra cosa.

Pratica 1: Scrivi descrizioni su cui il modello può agire

Scrivi le descrizioni dei tool come istruzioni per il modello, non come documentazione API. Una descrizione che soddisfa uno sviluppatore umano ("wrapper REST per l'endpoint users") non dà al modello nulla su cui decidere. La guida di ingegneria di Anthropic sulla scrittura dei tool e le loro best practice per le definizioni dei tool spingono entrambe sullo stesso schema: dici quando usare il tool, cosa restituisce e quando NON usarlo.

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

contro la versione che la maggior parte dei team rilascia:

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

Due regole fanno gran parte del lavoro. Primo, dai ai parametri nomi dal significato inequivocabile: user_id, mai user o id, perché user invita il modello a passare un nome o un'email laddove serve un UUID. Secondo, dichiara le esclusioni in modo esplicito. "Do NOT use to search users" previene più chiamate al tool sbagliato di qualsiasi quantità di descrizione positiva, perché i modelli confondono i tool sovrapposti molto più spesso di quanto fraintendano tool singoli e dai confini chiari. Per la meccanica a livello di provider su come queste definizioni raggiungono le API di OpenAI, Anthropic e Google, vedi la nostra guida al function calling multi-provider.

Pratica 2: Mantieni gli schemi flat e modellati sul compito

Tieni flat gli schemi di input, con tutti i campi che il compito richiede davvero e nessuno di quelli che non servono. Gli oggetti annidati con rami opzionali sono il terreno di coltura dei fallimenti per argomenti errati: il modello deve dedurre una struttura di cui non vede mai esempi. La guida al function calling di OpenAI accetta JSON Schema arbitrari, ma permissivo non è sinonimo di affidabile.

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

Appiattiscilo sul compito:

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

Gli enum battono il testo libero per qualsiasi campo con un insieme finito di valori. Gli array required battono l'opzionalità diffusa. Se il modello ha quasi sempre bisogno di un campo, rendilo obbligatorio nello schema del tool anche quando la tua API lo definisce opzionale. Non stai specchiando la tua API: stai progettando una superficie che un modello specifico possa compilare correttamente.

Fase 2: Gestisci l'insieme dei tool, non solo i singoli tool

La qualità del singolo tool smette di bastare appena un agente porta con sé più di una manciata di tool, perché gli errori di selezione crescono con la dimensione della lista che il modello legge.

Pratica 3: Racchiudi le sequenze API multi-step in tool atomici

Comprimi ogni sequenza fissa di chiamate API in un unico tool atomico. L'articolo di ingegneria di Anthropic usa schedule_event e get_customer_context come modello: una sola chiamata che fa tutto il lavoro batte tre chiamate che l'agente deve concatenare correttamente ogni volta. Ogni anello di una catena è un turno in più in cui il modello può bloccarsi, ritentare in modo errato o entrare in loop.

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

La regola pratica: se il modello deve sempre chiamare B dopo A, allora A e B sono un solo tool con due costumi addosso.

Pratica 4: Usa namespace, potatura e filtro dinamico dei tool

Metti un namespace a ogni nome di tool e mostra a ciascun agente solo il sottoinsieme che il suo compito attuale richiede. I nomi generici collidono nel momento in cui colleghi due integrazioni. Immagina un agente collegato a due server MCP che espongono entrambi un tool chiamato search: due verbi identici, nessun modo di distinguerli. Anthropic documenta guadagni misurabili nelle evaluation grazie al namespace con prefisso:

La potatura conta quanto la nomenclatura. Un agente di supporto non ha bisogno dei tool di fatturazione caricati mentre risponde a una domanda sulla password. Il pattern planner-worker, in cui un planner instrada il compito verso un worker che carica solo i tool rilevanti, è la soluzione standard; la how-to di LangGraph sul caricamento dinamico dei tool ne percorre l'implementazione. Quanti tool sono troppi? Tratta 5-10 per agente come un intervallo di lavoro, non come una legge: la precisione degrada al crescere della lista e la cura è il filtro, non un modello più grande. Se stai scegliendo proprio lo strato di instradamento e filtro, confronta le opzioni nella nostra rassegna delle migliori librerie di function calling.

Fase 3: Controlla ciò che torna indietro e ciò che esce

Il loop viaggia in entrambe le direzioni e la maggior parte dei team progetta solo la metà in uscita. Ciò che i tuoi tool restituiscono determina quanta parte della finestra di contesto sopravvive fino al turno successivo, e ciò che la tua validazione respinge determina se il modello impara dai propri errori o li ripete.

Pratica 5: Restituisci risultati concisi e ad alto segnale

Restituisci il risultato più piccolo su cui il modello può agire, con identificativi leggibili da un umano al posto degli ID grezzi. L'articolo di ingegneria di Anthropic documenta un tool il cui risultato predefinito arrivava a 206 token; un'impostazione concisa di response_format ha tagliato lo stesso risultato a 72 token, circa un terzo della dimensione. Moltiplicalo per decine di chiamate per compito e ottieni ciò che decide se il tuo agente arriva mai a finire il lavoro.

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

Altri due dettagli dalla stessa fonte: Anthropic supporta un enum response_format (detailed contro concise) nelle definizioni dei tool, così puoi dichiarare la forma che vuoi invece di parsare l'idrante. E Claude Code limita le risposte dei tool a 25.000 token, un tetto rigido che tronca comunque i risultati gonfiati. Anthropic riporta inoltre, come proprio risultato, che risolvere gli UUID in nomi semantici ha ridotto in modo misurabile le allucinazioni di recupero: ecco perché il payload "dopo" qui sopra dice "Dana Kim" e non c9a1...f2. Le risposte grasse sono anche un problema di costi; vedi la nostra guida su come ridurre i costi delle API LLM per il quadro completo.

Pratica 6: Valida ogni chiamata e fai in modo che gli errori insegnino al modello

Valida ogni chiamata ai tool lato server e restituisci errori che contengano la soluzione. L'articolo di Martin Fowler sul function calling la mette giù dura: non fidarti mai dell'output del modello. Passerà stringhe dove servono enum e inventerà ID che non esistono.

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)

La stringa di errore è tutta la partita. Confronta:

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

Ogni errore di validazione che il tuo tool restituisce è un prompt che stai scrivendo per il prossimo tentativo del modello. Errori che nominano il vincolo e indicano il tool correttivo trasformano un loop di tentativi in un recupero al primo colpo. Questa è anche la tua prima linea di difesa in fatto di sicurezza; la nostra guida ai guardrail per LLM la copre in profondità.

Fase 4: come lo rendi sicuro, e poi misurabile?

Sicurezza e misurazione sono la stessa fase, perché un'azione distruttiva senza protezioni e una regressione non misurata si manifestano entrambe come incidenti che non potevi vedere arrivare. Proteggi le azioni che non si possono annullare, poi strumenta tutto affinché la prossima modifica ai tool sia una decisione con prove a supporto, non una speranza.

Pratica 7: Proteggi le azioni distruttive con una conferma umana

Separa i tool di lettura dai tool di scrittura e metti un gate di conferma umana su tutto ciò che è distruttivo. Le annotazioni dei tool nella specifica MCP esistono esattamente per questo: destructiveHint marca i tool che eseguono aggiornamenti distruttivi e openWorldHint segnala i tool che toccano sistemi esterni, così i client possono chiedere conferma prima di eseguire. Usale.

La modalità di guasto non è ipotetica. Laurent Kubaski ha documentato un caso, nel suo articolo sul tool calling di luglio 2025 con link al report originale, in cui un utente ha chiesto a Copilot in Excel di agire sulla riga 4 e l'agente ha invece agito sulla riga 8. Nessun gate di conferma si frapponeva tra la riga sbagliata e la scrittura. La soluzione è il pattern che AWS documenta per Bedrock Agents: l'agente prepara l'azione, la restituisce per l'approvazione ed esegue solo dopo la conferma di un umano. Cursor fa lo stesso per le modifiche ai file. Limita le credenziali in sola lettura quando la lettura è tutto ciò che il compito richiede, e tratta i gate di conferma come parte della tua superficie di injection: l'argomento della nostra guida sulla prevenzione del prompt injection.

Pratica 8: Esegui un ciclo di evaluation a ogni modifica dei tool

Esegui una piccola suite di valutazione prima e dopo ogni modifica ai tool, e leggi le metriche in un ordine fisso. La guida all'ottimizzazione di Paragon propone una cornice a quattro metriche che vale la pena adottare:

Il cookbook di valutazione dei tool di Anthropic, costruito su evaluation MCP reali di Slack e Asana, mostra che aspetto hanno task di evaluation buoni e cattivi:

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

La nostra interpretazione, dichiarata come tale: i numeri pubblicati ti danno l'ordine di lavoro. Controlla prima la correttezza del tool, perché le misurazioni stesse di Anthropic mostrano che le modifiche a descrizioni e nomi la muovono direttamente (la riscrittura da 206 a 72 token, il risultato sulle allucinazioni da UUID-a-nome), e lascia per ultima l'efficienza del compito, dato che riflette per lo più fallimenti che le prime tre metriche hanno già intercettato. Per la suite iniziale, progetta 15-30 task, due o tre per tool, ciascuno con una singola chiamata attesa e una condizione di superamento binaria. Quella dimensione basta a intercettare una regressione da riscrittura di una descrizione senza una settimana di etichettatura, e leggiamo il setup Slack e Asana del cookbook come la prova che una suite così piccola è il punto di partenza previsto, non una scorciatoia. La meccanica più profonda sta nella nostra guida su come valutare gli agenti AI in produzione, e se i risultati delle evaluation dicono che i tool in sé sono a posto ma l'orchestrazione no, quello è il momento di rivedere la scelta del framework confrontandola con i migliori framework per agenti AI.

Tool calling degli agenti vs MCP: che differenza c'è?

MCP è uno standard di trasporto e di registro, non uno strato di affidabilità, quindi le stesse otto pratiche si applicano sia che i tuoi tool arrivino via MCP sia che siano definiti inline. Il tool calling nativo è il contratto del provider del modello: come il modello emette un tool_call e legge un tool_result. MCP standardizza il modo in cui i tool raggiungono il modello; non fa nulla riguardo al fatto che il modello scelga quello giusto.

Un server MCP che espone un tool chiamato search con la descrizione "searches things" fallisce in modo identico a una funzione inline definita nella stessa maniera. Sistema la definizione, poi preoccupati del trasporto. La nostra guida al Model Context Protocol copre il lato del protocollo da cima a fondo.

Come Techsy applica queste otto pratiche

Su ogni build di agenti per clienti, imponiamo tre di queste pratiche prima che qualsiasi altra cosa venga rilasciata: descrizioni scritte come istruzioni (Pratica 1), gate di validazione su ogni tool di scrittura (Pratica 6) e una suite di evaluation che gira prima del deploy, non dopo un incidente (Pratica 8). Quelle tre coprono le chiamate al tool sbagliato, le chiamate con argomenti sbagliati e le regressioni che le reintroducono entrambe: è lì che è iniziato ogni incidente su agenti in produzione su cui abbiamo fatto debugging. Le altre cinque pratiche arrivano man mano che l'agente cresce. Se il tuo agente ha superato la fase di demo e sceglie i tool sbagliati, richiedi una consulenza gratuita e ti diremo quale delle otto sistemare per prima.

Domande frequenti

Cos'è il tool calling degli agenti?

Il tool calling degli agenti è il meccanismo con cui un LLM decide di invocare una funzione esterna, emette un tool_call strutturato e aspetta che il tuo codice restituisca un tool_result su cui ragionare. È ciò che trasforma un modello chat in un agente capace di interrogare database, chiamare API e compiere azioni: il modello sceglie tool e argomenti, il tuo esecutore li esegue.

Come funziona il loop del tool calling degli agenti?

Il loop ha cinque passi: la richiesta dell'utente raggiunge il modello, il modello seleziona un tool e scrive un tool_call, il tuo esecutore lo esegue, un tool_result torna al modello e il modello risponde oppure emette un'altra chiamata. Quel ciclo si ripete finché il compito non è completato. Le quattro modalità di guasto di questa guida vivono ciascuna in un passo specifico di questo loop.

Perché il mio agente sceglie il tool sbagliato?

Di solito perché due tool si sovrappongono e le loro descrizioni non dicono quale sia quale. Il modello sceglie solo in base a nomi e descrizioni, quindi "gets a user" contro "finds users" risulta intercambiabile. Risolvilo con righe di esclusione ("do NOT use to search"), nomi con namespace e meno tool nel contesto. Il test di Kubaski su quattro modelli ha mostrato che anche modelli forti sbagliano instradamento su liste ambigue.

Come obbligo un agente con tool calling a strutturare il proprio output?

Vincola lo schema, non il prompt. Usa enum per i campi con valori finiti, array required per tutto ciò che il compito richiede e oggetti flat invece di oggetti annidati. Per la risposta finale anziché per la chiamata al tool, funzionalità del provider come gli structured output di OpenAI e le modalità tool-choice di Anthropic impongono una forma specifica. La nostra guida agli output strutturati copre entrambe le strade con codice.

Tool calling degli agenti vs MCP: che differenza c'è?

Il tool calling nativo è il contratto tra il tuo codice e un singolo provider di modelli: il formato dei messaggi tool_call e tool_result. MCP è uno strato di protocollo che standardizza il modo in cui i tool vengono scoperti e consegnati a qualsiasi client compatibile. MCP cambia le tubature, non l'affidabilità. Un tool descritto male fallisce nello stesso modo su entrambi i percorsi, come spiega la nostra guida al Model Context Protocol.

Quanti tool sono troppi per un agente LLM?

Tratta 5-10 tool per agente come un intervallo di lavoro, non come una legge. La precisione della selezione degrada al crescere della lista visibile, soprattutto quando nomi o descrizioni si sovrappongono. La soluzione non è un modello più grande ma il filtro: carica solo il sottoinsieme che il compito attuale richiede, usando una divisione planner-worker. Metti un namespace a tutto, così due integrazioni non esporranno mai entrambe un search nudo.

Qual è il modello migliore per il tool calling?

Non esiste una risposta unica, e i benchmark pubblicati invecchiano male in questo ambito. I modelli frontier di OpenAI, Anthropic e Google superano tutti i compiti di base di tool use, mentre modelli più piccoli abbinati a tool ben progettati completano i compiti quasi con la stessa frequenza a una frazione del costo in token. Costruisci la suite di evaluation da 15-30 task della Pratica 8 e testa i candidati contro i tuoi tool.

Come riduco il costo in token del tool calling?

Taglia ciò che torna indietro. Restituisci risultati concisi e ad alto segnale invece di payload API grezzi: Anthropic ha documentato un taglio da 206 a 72 token ottenuto con una sola modifica a response_format. Risolvi gli UUID in nomi, elimina i campi che il modello non usa mai e ricorda che ogni risultato dei tool rientra nella finestra di contesto a ogni turno successivo. Meno chiamate, tramite tool atomici, toglie interi risultati dal conto.

Come valuto la qualità del tool calling?

Punteggia quattro metriche in ordine: correttezza del tool (tool giusto?), accuratezza dell'input (argomenti validi?), completamento del compito (obiettivo raggiunto?) ed efficienza del compito (numero di token e di chiamate?). Scrivi 15-30 task, ciascuno con l'attesa di una specifica chiamata con argomenti verificabili e una condizione di superamento binaria. Esegui la suite prima e dopo ogni modifica ai tool, così una riscrittura di descrizione non viene mai rilasciata senza misurazione.

Conclusione

Diagnostica prima di ottimizzare. Il tuo agente sceglie il tool sbagliato per una di quattro ragioni, e tre delle otto pratiche qui sopra (descrizioni, schemi flat e filtro) sistemano i guasti di selezione che causano la maggior parte degli incidenti in produzione. Parti da lì, perché costano un pomeriggio e sono il motivo per cui questo problema è risolvibile. Mantieni gli errori di validazione informativi, proteggi tutto ciò che è distruttivo con una conferma umana ed esegui il ciclo di evaluation a ogni modifica, così misurerai prima di cambiare modello. Il problema del tool sbagliato non è un problema del modello: è un problema di progettazione dei tool, e la progettazione è tua.