Esempi e schemi risolvono due problemi diversi che si confondono spesso. Gli esempi insegnano che cosa mettere nei campi; lo schema garantisce che i campi ci siano e siano del tipo giusto. Un sistema in produzione ne ha bisogno di entrambi, e sbagliare quale leva tirare costa token o incidenti.

Gli esempi sono la leva sulla forma, non sulla correttezza

La documentazione è esplicita sull’efficacia: «Examples are one of the most reliable ways to steer Claude’s output format, tone, and structure». Il termine tecnico è few-shot o multishot prompting, e le tre proprietà richieste agli esempi sono operative, non estetiche: rilevanti (devono rispecchiare da vicino il caso d’uso reale), diversi e strutturati.

Il criterio sulla diversità è quello che si sbaglia più spesso: «Diverse: Cover edge cases and vary enough that Claude doesn’t pick up unintended patterns». Tre esempi che condividono un tratto accidentale — tutti brevi, tutti con esito positivo, tutti dello stesso cliente — insegnano quel tratto insieme al formato. È il modo di rompersi caratteristico del few-shot: non produce output malformati, produce output uniformemente sbagliati, che passano ogni validazione sintattica.

Sulla quantità la doc dà un numero: «Include 3–5 examples for best results». Sulla struttura chiede di isolare gli esempi dalle istruzioni con tag dedicati, perché altrimenti il modello non distingue una dimostrazione da un ordine:

<examples>
  <example>
    <input>...</input>
    <output>...</output>
  </example>
</examples>

La guida alla consistenza aggiunge la formulazione più utile per una decisione di design: «Provide examples of your desired output. This is more effective than abstract instructions». Prima di scrivere il decimo paragrafo di istruzioni su come deve apparire l’output, mostralo.

Quando gli esempi non bastano: la grammatica vincolata

Un esempio è una pressione statistica, non una garanzia. Se il tuo parser a valle si rompe su un JSON malformato una volta ogni mille chiamate, nessun numero di esempi chiude il problema. Serve un meccanismo diverso: «Structured outputs constrain Claude’s responses to follow a specific schema, ensuring valid, parseable output for downstream processing».

Le due facce sono complementari: l’output JSON della risposta, configurato con output_config.format di tipo json_schema, e la validazione degli input dei tool. Si usano indipendentemente o insieme nella stessa richiesta.

"output_config": {
  "format": {
    "type": "json_schema",
    "schema": {
      "type": "object",
      "properties": { },
      "required": [ ],
      "additionalProperties": false
    }
  }
}

Nota che additionalProperties deve essere impostato a false sugli oggetti: non è una convenzione, è un requisito del sottoinsieme di JSON Schema supportato. Un dettaglio che sposta architetture: gli schemi ricorsivi non sono supportati, quindi un albero di profondità arbitraria non si modella così. E i vincoli numerici (minimum, maximum, multipleOf) e di lunghezza delle stringhe non sono supportati: lo schema ti garantisce che il campo sia un intero, non che sia un intero nell’intervallo giusto. La validazione semantica resta tua.

Lo stesso motore applicato ai tool

Sui tool la leva è strict: true nella definizione, e il meccanismo è lo stesso: campionamento vincolato dalla grammatica. La documentazione descrive il fallimento che evita con un esempio concreto — un sistema di prenotazione che si aspetta passengers come intero e riceve la stringa «two» o «2». Con la modalità strict la risposta contiene sempre passengers: 2. Le garanzie dichiarate sono due: l’input del tool segue rigorosamente input_schema, e il nome del tool è sempre valido.

Distinguila dal forzare la chiamata, che è un parametro diverso. Con tool_choice hai quattro opzioni: auto (il default quando ci sono tool), any (deve usarne uno, non importa quale), tool (ne forza uno specifico), none. Due avvertenze da architetto. La prima: con any o tool l’API prefila il messaggio dell’assistente, quindi il modello non emette testo in linguaggio naturale prima dei blocchi tool_use, nemmeno se glielo chiedi. La seconda è una vera incompatibilità da verificare sul modello che userai: su Claude Fable 5.1 e Claude Mythos 5.1, any e tool restituiscono un errore 400, e la strada indicata è auto con strict tool use, oppure gli structured outputs quando serve una forma JSON fissa.

Vale anche l’inverso: il vecchio trucco di prefillare il turno dell’assistente per imporre il formato non è più disponibile — non è supportato dai modelli 4.6 e successivi. Se il tuo codice lo usa ancora, è debito tecnico da migrare verso gli structured outputs.

Il conto: latenza, cache e token

La garanzia non è gratuita, ma il costo è prevedibile. Alla prima richiesta con un dato schema c’è latenza in più mentre la grammatica compila; le grammatiche compilate sono poi in cache per 24 ore dall’ultimo uso, il che rende molto più veloci le richieste successive. La cache si invalida se cambi la struttura dello schema o l’insieme dei tool nella richiesta — mentre cambiare solo i campi name o description non la invalida.

Sui token: attivando gli structured outputs il modello riceve automaticamente un system prompt aggiuntivo che spiega il formato atteso, quindi l’input cresce un po’, e modificare il parametro di formato invalida la cache dei prompt per quel thread. Progetta gli schemi come artefatti stabili, versionati, non come stringhe costruite a runtime per ogni richiesta: uno schema che cambia a ogni chiamata paga la compilazione ogni volta e non entra mai in cache.