Function calling e tool schema

Il function calling trasforma il modello da generatore di testo a coordinatore di azioni. Non gli chiedi solo di rispondere: gli chiedi di scegliere uno strumento, compilare parametri e interpretare il risultato.

Questa capacità è potente, ma sposta il problema. Il prompt non vive più da solo: vive insieme a un catalogo di tool. Se gli schema sono ambigui, sovrapposti o troppo permissivi, l’agente farà scelte fragili anche con un buon modello.

Perché questa lezione conta

Molti errori agentici non sono “allucinazioni” nel senso classico. Sono errori di interfaccia: tool descritti male, parametri vaghi, valori enum mancanti, side effect non dichiarati, risultati difficili da interpretare.

Per uno sviluppatore, progettare tool schema è simile a progettare API pubbliche. Il modello è un client probabilistico: legge nomi, descrizioni e tipi per decidere cosa chiamare. Se l’API comunica male, il client sbaglia.

Obiettivo operativo

Alla fine della lezione devi saper progettare uno schema di tool che dica al modello cosa può fare, quando usarlo, quando non usarlo, quali parametri sono validi e come interpretare errori e risultati.

Anatomia di un tool

Uno schema utile contiene almeno:

1. nome breve e specifico;
2. descrizione orientata all’uso;
3. parametri con tipi e vincoli;
4. valori ammessi per campi categorici;
5. comportamento in caso di errore;
6. eventuali effetti collaterali;
7. costo o latenza se rilevanti;
8. esempi di uso e non uso, quando possibile.

Esempio:

{
  "name": "search_project_docs",
  "description": "Cerca nella documentazione tecnica interna. Usalo solo per domande su decisioni, convenzioni o API del progetto; non usarlo per cercare codice sorgente.",
  "parameters": {
    "query": {
      "type": "string",
      "description": "Domanda o frase da cercare, massimo 200 caratteri."
    },
    "area": {
      "type": "string",
      "enum": ["frontend", "backend", "deploy", "security", "unknown"]
    }
  }
}

La descrizione non dice solo “cerca documenti”. Dice anche quando usarlo e quando no. Questa parte riduce chiamate sbagliate più di molti tentativi nel prompt principale.

Nomi e granularità

Un nome come getData è inutile. Il modello deve inferire troppo. Un nome come get_customer_invoice_by_id comunica molto di più.

La granularità richiede equilibrio:

Tool troppo generico. execute_sql(query) dà libertà enorme e rischio alto. Il modello deve costruire query corrette, sicure e autorizzate.

Tool troppo specifico. Venti tool quasi identici confondono la scelta e aumentano collisioni semantiche.

Una buona regola: crea tool attorno a capability del dominio, non attorno a dettagli tecnici interni. find_available_rooms è più chiaro di query_rooms_table.

Parametri vincolati

Ogni parametro libero aumenta ambiguità. Quando puoi, usa enum, range, pattern e campi obbligatori.

Esempio fragile:

{ "priority": "string" }

Esempio migliore:

{ "priority": { "type": "string", "enum": ["low", "normal", "high", "urgent"] } }

Se il modello deve scegliere tra valori definiti, puoi validare e rifiutare. Se scrive testo libero, devi interpretare.

Risultati leggibili dal modello

Anche l’output del tool è parte del prompt successivo. Un risultato utile è compatto, strutturato e privo di rumore.

{
  "status": "not_found",
  "message": "Nessun documento trovato per la query.",
  "suggested_next_step": "Chiedere all'utente un'area tecnica piu specifica."
}

Meglio di un errore grezzo da stack trace. Il modello deve capire cosa può fare dopo.

Side effect dichiarati

Se un tool modifica stato, la descrizione deve dirlo:

Crea un ticket visibile al team. Ha effetto collaterale persistente. Non chiamare senza conferma esplicita dell'utente.

Questa informazione deve esistere anche nel codice: policy, permessi e conferme. Ma dichiararla nello schema aiuta il modello a pianificare meglio.

Laboratorio guidato

Scegli un dominio piccolo: gestione ticket, archivio documenti, calendario, repo, CRM demo. Definisci 3-5 tool.

Per ciascuno scrivi:

1. nome;
2. scopo;
3. quando usarlo;
4. quando non usarlo;
5. parametri;
6. risultato;
7. rischio;
8. esempio di chiamata valida.

Poi crea 10 richieste utente e verifica se l’agente sceglie il tool corretto o se risponde senza tool quando non serve.

Output atteso

Devi produrre un catalogo tool versionato:

tools/
  README.md
  search_project_docs.schema.json
  create_ticket.schema.json
  get_build_status.schema.json
  eval-tool-selection.md

Il catalogo deve essere leggibile da un umano e abbastanza preciso da essere usato da un modello.

Errori comuni

Descrivere il tool dal punto di vista implementativo. Il modello non deve sapere che usi Postgres o REST se la scelta del tool dipende dal dominio.

Non dichiarare effetti collaterali. Un tool che scrive, invia o cancella deve essere riconoscibile come rischioso.

Accettare testo libero ovunque. Parametri non vincolati rendono difficile validare e riprodurre.

Duplicare tool simili. Se due tool sembrano fare la stessa cosa, il modello sceglierà in modo instabile.

Checklist di verifica

• ogni tool ha nome specifico e descrizione operativa;
• i parametri sono vincolati quando possibile;
• i side effect sono dichiarati;
• l’output del tool è strutturato e comprensibile;
• esiste un piccolo eval set per verificare la scelta del tool.

Collegamenti

• Modulo: Agenti, tool use, integrazione — questa lezione è la numero 31 del corso.
• Prepara il loop agentico della lezione successiva.