Il paradosso del tool use
Quando un agente AI ha tre tool a disposizione, funziona bene. Quando ne ha dodici, inizia a fare scelte strane. Quando ne ha trenta, diventa imprevedibile.
Non è un problema del modello. È un problema di superficie di decisione.
Ogni tool che aggiungi non è solo una capacità in più — è un'opzione in più che il modello deve valutare a ogni turno. E come in qualunque sistema di decisione, più opzioni hai, più errori di selezione commetti.
La prima regola: ogni tool deve avere una ragione per esistere
Un pattern che vedo spesso: il team aggiunge tool mano a mano che emergono casi d'uso, senza mai consolidare. Dopo sei mesi, hai get_customer_info, fetch_customer_data, lookup_customer, customer_details — tutti che fanno cose leggermente diverse che nessuno ricorda.
Il modello, a quel punto, sceglie a caso.
Prima di aggiungere un tool, rispondi a tre domande:
- Esiste già un tool che fa qualcosa di simile?
- Se sì, posso estendere quello invece di crearne uno nuovo?
- Un utente umano che legge solo i nomi dei tool capirebbe quando usare questo e non un altro?
Se il tuo team non riesce a distinguere get_user da fetch_user guardando solo i nomi, il modello non ce la farà mai.
Tool name e description sono prompt, non documentazione
Il nome e la descrizione di un tool non sono metadati passivi. Sono il prompt che il modello legge per decidere se usarlo. Trattali di conseguenza.
Tool name: deve essere un verbo + oggetto specifico. get_order_status batte orders senza storia. send_approval_reminder batte remind.
Description: in 1-3 frasi, devi coprire tre cose:
- Cosa fa il tool (la meccanica)
- Quando usarlo (il trigger operativo)
- Quando NON usarlo (l'antitrigger)
Un esempio di descrizione debole:
"Questo tool permette di ottenere informazioni sull'ordine."
Un esempio di descrizione utile:
"Restituisce lo stato, le date di spedizione e i prodotti di un ordine. Usare quando l'utente chiede dello stato di un ordine specifico o menziona un ID ordine. Non usare per query generiche sul catalogo o sul profilo cliente."
La differenza, misurata in produzione, è sostanziale: la seconda versione riduce drasticamente i falsi positivi in cui l'agente chiama il tool quando non serve.
Input schema come contratto, non come placeholder
Gli schema degli input tool sono un altro prompt implicito. Ogni parametro dovrebbe avere:
- Un nome che comunica il contenuto (
customer_idnonid) - Un tipo preciso (
stringcon formatemailnon solostring) - Una descrizione che copre i casi limite ("Lasciare vuoto se il cliente non è ancora registrato")
- Una gestione esplicita di required vs optional
Un pattern utile: rendi required solo i campi che il modello può davvero inferire dalla conversazione. Tutto il resto optional, con default espliciti. Un tool con sei required field che il modello non può riempire da solo diventa inusabile.
Il problema del ritorno non controllato
I tool ritornano dati. Quei dati finiscono nel contesto. Se un tool restituisce un JSON di 40KB ogni volta che viene chiamato, stai iniettando rumore nel contesto futuro.
Tre pratiche che salvano molto contesto:
Pagination o limit di default. Se un tool potrebbe restituire 1000 record, restituiscine 10 di default con un flag per chiedere di più.
Filtering at tool level. Invece di far restituire al tool tutti i campi del record, accetta un parametro fields e restituisci solo quelli richiesti.
Sommari invece di dump. Per tool che ritornano strutture complesse, affianca una summary in linguaggio naturale alla struttura completa. Il modello spesso userà la summary e risparmierà token.
Quando l'agente si blocca: gli errori sono tool come gli altri
Una fonte di crash silenti nei sistemi agentici è la gestione degli errori dei tool. Se un tool fallisce, cosa riceve il modello?
Se riceve uno stack trace Python, la risposta sarà confusa. Se riceve un null silenzioso, proverà a continuare come se nulla fosse. Se riceve un errore strutturato e interpretabile, può decidere cosa fare.
Un tool error ben progettato ha:
- Un
status("error") - Un
error_codestabile ("NOT_FOUND", "PERMISSION_DENIED", "RATE_LIMITED") - Un
messagein linguaggio naturale che il modello può parafrasare all'utente - Un suggerimento esplicito ("Prova a chiedere all'utente l'ID ordine corretto")
{
"status": "error",
"error_code": "ORDER_NOT_FOUND",
"message": "Nessun ordine trovato con ID ORD-12345 per questo cliente",
"suggested_action": "Chiedi all'utente di verificare l'ID ordine o di fornire data e prodotto"
}Con questa struttura, l'agente può recuperare senza bisogno di hard-coded fallback. Senza, ogni errore è una potenziale conversazione rotta.
Il pattern del tool selector
Quando il numero di tool supera una soglia (nella mia esperienza, intorno ai 10-15), smette di funzionare bene tenerli tutti visibili al modello allo stesso tempo. Due pattern architettonici aiutano.
Tool namespace: raggruppare i tool per dominio (orders.get_status, orders.cancel, billing.get_invoice, billing.send_reminder). Il modello ragiona prima sul dominio, poi sul tool specifico.
Tool search dinamico: il modello prima chiede quali tool sono disponibili per un certo task, poi sceglie. È un passo in più, ma diventa essenziale quando il catalogo supera le decine. OpenAI ha introdotto questo pattern a livello di API con GPT-5.4; Anthropic e altri stanno andando nella stessa direzione.
La disciplina che paga: riduci prima di aggiungere
Ogni due-tre mesi, qualcuno nel team dovrebbe fare un audit dei tool: quali vengono usati davvero in produzione? Quali non sono mai chiamati? Quali vengono chiamati ma con accuratezza bassa?
I tool dimenticati sono il problema più insidioso. Non creano valore, ma occupano spazio nella superficie di decisione del modello. Rimuoverli è quasi sempre un win puro.
La regola pratica: se un tool non viene usato da più di un mese in produzione, è candidato alla deprecazione. Mantenerlo "perché magari serve" è un costo pagato a ogni chiamata da tutti gli altri tool.
La domanda strutturale
La domanda che merita di essere fatta quando un agente inizia a comportarsi male non è "come miglioro il prompt?". È:
"L'agente ha il set di tool giusto per rispondere a questa categoria di richieste, presentato in modo che possa scegliere bene?"
Spesso la risposta è no, e la soluzione non è un prompt migliore — è un set di tool più piccolo, più coerente, meglio documentato. Gli agenti che funzionano bene non sono quelli che possono fare tutto. Sono quelli che sanno esattamente cosa possono fare e cosa no.