Formati di input ed esempi

La descrizione di uno strumento è il meccanismo principale che Claude utilizza per decidere quando e come chiamarlo. I soli nomi non forniscono un segnale sufficiente. Una descrizione efficace comprende lo scopo, i valori restituiti, i casi limite, i limiti di applicabilità e, soprattutto, i formati di input.

Questa lezione si concentra su una tecnica molto efficace: mostrare esempi concreti di input, così il modello non deve mai indovinare l'aspetto che dovrebbe avere un parametro.

Immagini uno strumento con un parametro chiamato date. Deve essere 2026-06-10? 06/10/2026? June 10? Un timestamp Unix? Senza un esempio, Claude deve dedurre il formato, ed è proprio nell'inferenza in condizioni ambigue che nascono le chiamate agli strumenti con formato errato.

Uno schema ambiguo non genera un errore evidente. Fallisce silenziosamente, producendo input che il backend rifiuta. Gli esempi concreti eliminano l'ambiguità alla fonte.

Può inserire esempi di input in due punti complementari:

• Nel testo della descrizione dello strumento (esempi di utilizzo complessivi).
• Nella description di ogni parametro all'interno dello JSON Schema (formato del singolo campo).

Entrambi alimentano lo stesso motore di selezione e formattazione. Inserisca le indicazioni sul formato il più vicino possibile al campo a cui si applicano e aggiunga un esempio completo della chiamata.

Le confronti. La versione debole costringe a indovinare; quella efficace mostra esattamente quale aspetto debba avere un input valido.

• Debole: "Cerca un cliente."
• Efficace: scopo + formato di input + esempio + valori restituiti + casi limite.

Le descrizioni minime e ambigue sono un classico anti-pattern che causa errori di instradamento degli strumenti e argomenti con formato errato.

Quando un parametro è un oggetto o un array, un singolo esempio vale più di un paragrafo di prosa. Mostri al modello la struttura letterale che deve produrre.

Questo è particolarmente utile per i filtri annidati, gli elementi di una lista o qualsiasi campo la cui struttura non sia evidente dal solo tipo.

Quando un campo ha un insieme noto e finito di valori validi, li codifichi come enum invece di descriverli in prosa. In questo modo lo schema vincola direttamente il modello.

Per garantire l'estensibilità, aggiunga un valore enum "other" e un campo di dettaglio a testo libero, così i nuovi casi non costringeranno il modello a inventare un valore non valido.

Gli esempi few-shot sono uno degli strumenti di prompting più affidabili. Con 2–4 esempi mirati per ogni ambiguità, il modello generalizza lo schema invece di limitarsi a ripeterlo.

Applicati agli input degli strumenti, gli esempi sono ideali per garantire coerenza, gestire i casi limite, definire il formato dell'output e ridurre le allucinazioni: esattamente i casi di errore che producono argomenti non validi per gli strumenti.

Gli esempi indicano al modello l'aspetto di un input valido; l'array required gli indica cosa deve comparire. Una regola fondamentale: contrassegni un campo come obbligatorio solo se è sempre presente.

Se rende obbligatorio un campo che potrebbe mancare nella fonte, il modello inventerà un valore per soddisfare lo schema. Un campo facoltativo ma ben esemplificato è preferibile a uno obbligatorio ma talvolta assente.

Le buone descrizioni specificano i limiti di applicabilità: cosa fa lo strumento e cosa NON gestisce. Incorpori questi limiti negli esempi, così il modello riconoscerà quando un input è fuori ambito.

In questo modo si evita di instradare erroneamente gli strumenti sovrapposti, perché l'esempio chiarisce a quale strumento appartenga ogni forma di input.

Anche con ottimi esempi, alcuni input saranno non validi. Il contratto degli errori dello strumento deve essere altrettanto esplicito, affinché il modello possa recuperare.

Restituisca errori strutturati: un flag isError, oltre a errorCategory (transient / validation / business / permission), isRetryable, un messaggio e attempted_query. Un generico "Operation failed" impedisce il recupero; gli errori strutturati consentono un instradamento intelligente e un nuovo tentativo corretto.

Quando l'input di uno strumento restituisce un formato non valido, utilizzi retry-with-feedback: invii al modello la richiesta originale, l'output errato e l'errore di convalida esatto. È proprio questo il tipo di problema che questa tecnica risolve.

Noti il limite: il retry è utile quando l'input è formattato in modo errato, non quando l'informazione necessaria è semplicemente assente nella fonte. Gli esempi prevengono il primo tipo di errore; nulla può inventare i dati mancanti.

Punti chiave:

• Le descrizioni degli strumenti guidano la selezione e la formattazione, quindi investa su di esse, non solo sui nomi.
• Mostri esempi concreti di input a livello di campo e un esempio di chiamata completa nella descrizione.
• Utilizzi gli enum (con un campo 'other' + dettaglio) per gli insiemi fissi; mostri la struttura letterale di oggetti e array.
• Contrassegni un campo come obbligatorio solo se è sempre presente; altrimenti il modello inventa dati.
• Supporti gli esempi con errori strutturati (errorCategory, isRetryable, attempted_query), in modo che retry-with-feedback possa correggere gli errori di formato, anche se non può fornire dati assenti.

Gli esempi concreti sono il modo più economico e incisivo per impedire chiamate agli strumenti malformate prima che si verifichino.