Quanti strumenti per agente

Quando si fornisce a un agente un insieme di tools, il modello deve svolgere un'operazione delicata a ogni turno: leggere tutte le descrizioni degli strumenti e scegliere quello giusto per il passaggio corrente.

Si tratta di un'attività di selezione. Più opzioni si aggiungono, più questa scelta diventa difficile. Un insieme di strumenti mirato mantiene la selezione precisa; uno sovraccarico porta il modello a esitare, instradare la richiesta in modo errato o utilizzare lo strumento sbagliato.

Questa lezione risponde a una domanda apparentemente semplice: quanti strumenti dovrebbe avere un singolo agente?

Il punto di equilibrio pratico è di 4-5 strumenti per agente. Con queste dimensioni, il modello riesce a valutare in modo affidabile quale strumento sia adatto a ogni passaggio.

All'aumentare del numero, l'affidabilità della selezione diminuisce. Quando un singolo agente dispone di circa 18 o più strumenti, il modello inizia a confondere le opzioni simili e a effettuare scelte inadeguate. Più strumenti NON significano più capacità: oltre una certa soglia, significano una capacità meno affidabile.

• 4-5 strumenti → selezione ottimale
• 18 o più strumenti → affidabilità della selezione ridotta

Ecco un agente di supporto con un insieme di strumenti ristretto e definito in base al ruolo. Quattro strumenti, ciascuno con una funzione chiara: verificare il cliente, cercare il suo ordine, elaborare un rimborso e inoltrare la richiesta a un operatore umano.

Il modello non deve mai chiedersi quale dei venti strumenti quasi identici utilizzare. Ognuno corrisponde a un intento distinto.

È importante precisare che il modello seleziona gli strumenti principalmente in base alle loro descrizioni, non ai loro nomi. Una buona descrizione indica lo scopo dello strumento, i valori restituiti, i formati degli input con esempi, i casi limite e i confini di applicabilità.

Per questo il numero e la qualità degli strumenti interagiscono tra loro. Anche 5 strumenti possono essere instradati in modo errato se le loro descrizioni si sovrappongono o sono ambigue. Più strumenti si aggiungono, più è probabile che due di essi sembrino simili e più aumentano gli errori di selezione.

Immagini di concentrare un intero reparto in un unico agente: strumenti per i clienti, per gli ordini, per la fatturazione, per l'inventario, per le spedizioni, per l'analisi... oltre venti voci in un unico array tools.

Ora immagini che diversi strumenti abbiano nomi simili — lookup_order, find_orders, get_order_history, search_purchases. Il modello deve disambiguarli a ogni turno e la sua accuratezza diminuisce. Avere troppi strumenti per agente è un anti-pattern riconosciuto, al pari delle descrizioni ambigue.

La soluzione non consiste nel rendere le descrizioni sempre più lunghe, ma nel definire gli strumenti in base al ruolo. Si chieda: qual è il compito di QUESTO agente e qual è il numero minimo di strumenti necessari per svolgerlo?

Un agente che gestisce i rimborsi ha bisogno di strumenti per l'identità, gli ordini, i rimborsi e l'escalation. Non ha bisogno di previsioni sull'inventario o di analisi di marketing. Eliminare gli strumenti irrilevanti rimuove le distrazioni e rende più precisa ogni selezione rimanente.

Quando un'attività richiede realmente molte capacità, non le si assegnano tutte a un unico agente. Si utilizza una progettazione multi-agente hub-and-spoke: un coordinatore scompone il lavoro e lo delega a sottoagenti specializzati, ciascuno con il proprio insieme ristretto di strumenti.

Venti strumenti distribuiti su quattro sottoagenti (5 ciascuno) vengono selezionati in modo molto più affidabile rispetto a venti strumenti assegnati a un singolo agente. Ricordi: i sottoagenti NON ereditano la cronologia del coordinatore, quindi il prompt di ogni sottoagente deve contenere esplicitamente il proprio contesto.

Suddividere gli strumenti tra i sottoagenti offre un ulteriore vantaggio: il privilegio minimo. Ogni AgentDefinition dichiara solo gli allowed_tools di cui ha effettivamente bisogno.

Un sottoagente di ricerca con accesso in sola lettura non riceve mai uno strumento process_refund o delete, quindi non può utilizzarlo per errore. Insiemi di strumenti più piccoli e definiti in base al ruolo sono sia più affidabili (selezione migliore) sia più sicuri (raggio d'azione più limitato). Una regola da ricordare per il coordinatore: il suo allowedTools deve includere "Task" per poter delegare.

Non tutto ciò di cui un agente ha bisogno deve essere uno strumento. In MCP, le primitive del server si dividono in tre categorie:

• Strumenti — azioni invocate dal modello
• Risorse — dati o contesto in sola lettura, come schemi o cataloghi
• Prompt — modelli riutilizzabili

Se il modello deve soltanto leggere uno schema o un catalogo di prodotti, lo si esponga come risorsa, non come strumento. In questo modo l'array tools rimane essenziale e riservato alle azioni vere e proprie: un ulteriore accorgimento per mantenere il numero di strumenti azionabili vicino a 4-5.

L'insieme di strumenti integrati di Claude Code è un buon esempio di definizione disciplinata dell'ambito. Ogni strumento ha una funzione precisa:

• Glob — trovare file in base a un pattern (ad esempio **/*.test.tsx)
• Grep — cercare nei contenuti dei file
• Read / Write / Edit — caricare, creare e modificare con precisione i file
• Bash — eseguire comandi shell

Nessuno di essi si sovrappone agli altri. Il modello li combina in un flusso incrementale — Grep per i punti di ingresso, Read per i file, Grep per gli utilizzi, Read per i consumer — invece di scegliere tra opzioni ridondanti.

Prima di distribuire un agente, esegua questa verifica:

• L'insieme comprende circa 4-5 strumenti ed è ben al di sotto di 18?
• Ogni strumento corrisponde a un intento distinto e ha una descrizione non sovrapposta alle altre?
• Le esigenze di sola lettura sono modellate come Risorse, non come strumenti?
• Se servono più capacità, è possibile suddividere il lavoro in sottoagenti con insiemi di strumenti basati sul privilegio minimo?

Se si sta portando un singolo agente oltre una dozzina di strumenti, questo è il segnale per scomporre il lavoro, non per scrivere descrizioni più lunghe.

Punti chiave:

• 4-5 strumenti per agente sono il numero ottimale; l'affidabilità diminuisce all'aumentare del numero e 18 o più strumenti compromettono sensibilmente la selezione.
• Il modello seleziona in base alle descrizioni, quindi strumenti sovrapposti o ambigui causano errori di instradamento anche con numeri ridotti.
• Definisca gli strumenti in base al ruolo: elimini le distrazioni invece di scrivere descrizioni più lunghe.
• Servono più capacità? Suddivida il lavoro in sottoagenti (hub-and-spoke) con insiemi di strumenti basati sul privilegio minimo; trasmetta esplicitamente il contesto, poiché i sottoagenti non ereditano la cronologia.
• Modelli le esigenze di sola lettura come Risorse MCP, non come strumenti, per mantenere essenziale l'array tools.