Docstring efficace per tool: guida pratica per Agent AI

Gli agenti di intelligenza artificiale sono davvero “intelligenti” nel senso ontologico del termine? La risposta è no: piuttosto, possono essere visti come programmi che, invece di essere costruiti tramite lunghe sequenze di istruzioni del tipo if a > b then…, vengono guidati attraverso il linguaggio naturale. I comandi, espressi in forma dialogica, vengono poi tradotti in azioni eseguibili.

Ma come si indica a un agente AI quale strumento utilizzare per svolgere un determinato compito?

Quando si progettano tool destinati a essere utilizzati da un modello di linguaggio (LLM), la docstring rappresenta l’unico canale attraverso cui l’agente comprende cosa fa una funzione e in quali situazioni usarla.

Per questo motivo, una docstring ben scritta è essenziale: evita ambiguità e impedisce che l’agente interpreti male — o addirittura ignori — il tool. Qui trovi linee guida pratiche, pattern consigliati ed errori da evitare.

Struttura ideale di una docstring

Per un LLM, la forma più efficace è:

VERBO + OGGETTO + (CONTESTO / QUANDO)

Questa struttura rende immediatamente chiaro cosa fa la funzione e quando deve essere utilizzata.

Scelta del verbo

Preferisci verbi concreti e operativi, evitando termini vaghi.

Buoni verbi	Cattivi verbi
Cerca	Gestisce
Calcola	Fa
Recupera	Opera
Converte	Lavora con
Valida

Definizione dell’oggetto

L’oggetto deve essere preciso e non ambiguo.

• Buono: informazioni aggiornate, numeri interi, contenuti web

• Cattivo: dati, valori, cose

Aggiungere il contesto

Il contesto chiarisce quando usare il tool, ad esempio:

• “sul web”

• “da un database locale”

• “quando è richiesto un calcolo matematico”

Esempi buoni e cattivi...

Cattivo:"""Fa una ricerca"""

Buono:"""Cerca informazioni aggiornate sul web."""

Cattivo:"""Gestisce le richieste dell’utente"""

Buono:"""Risponde a domande generiche di conoscenza."""

Pattern consigliato

@tool
def nome_tool(...) -> ...:
    """
    VERBO OGGETTO CONTESTO.
    Usa questo tool quando CONDIZIONE.
    """

Esempio pratico

@tool
def web_search(query: str) -> str:
    """
    Cerca informazioni aggiornate sul web.
    Usa questo tool quando la risposta potrebbe non essere nella conoscenza del tuo modello.
    """

La seconda frase è particolarmente potente perché introduce una sorta di “if semantico”: il modello associa parole chiave dell’input (come “oggi”, “attuale”, “cerca”) al contesto d’uso del tool.

Errori da evitare

• Frasi troppo lunghe o stile da manuale

• Gergo aziendale o interno

• Ironia o sarcasmo

• Sinonimi inutili che creano ambiguità

• Docstring che coprono più responsabilità

Regola d’oro

Scrivi la docstring come se dovessi spiegare la funzione a un collega in 5 secondi. Se non è immediata, probabilmente l’agente non la userà correttamente.

Prompt consigliato

Ti descrivo una funzione in modo dettagliato.Scrivi UNA docstring di massimo 2 frasi, come se stessi spiegando a un collega cosa fa la funzione in 5 secondi.Usa la forma: VERBO + OGGETTO + CONTESTO.Non essere generico.

Esempi

Input:Funzione che riceve una query, interroga un servizio esterno e restituisce dati aggiornati, usata solo quando le informazioni possono cambiare.

Output:"""Cerca informazioni aggiornate tramite un servizio esterno.Usa questo tool quando i dati potrebbero cambiare nel tempo."""

Input:Funzione che somma due numeri interi, con validazione, usata solo per calcoli espliciti.

Output:"""Somma due numeri interi.Usa questo tool quando è richiesto un calcolo matematico esplicito."""

Tips ? Fai scrivere una docstring a un LLM...

Puoi usare direttamente questo prompt:

Scrivi una docstring di massimo 2 frasi con forma VERBO + OGGETTO + CONTESTO per spiegare a un collega cosa fa la funzione in 5 secondi.

Questo approccio è sufficiente nella maggior parte dei casi (circa il 90%).

Conclusioni

Checklist rapida

• Nome del tool parlante: deve suggerire chiaramente l’azione svolta.

• Docstring chiara e concreta: usa la formula VERBO + OGGETTO + (CONTESTO).

• Type hint semplici: esplicita input e output.

• Input ben definito: descrivi il formato atteso.

• Istruzione per l’agente: inserisci una condizione d’uso (“usa questo tool quando…”).