Un tool è un’API il cui unico consumatore è un modello, e questo cambia tutto ciò che conta nel progettarla. Un endpoint REST vive di contratto e di documentazione esterna; un tool porta la propria documentazione dentro il prompt a ogni richiesta, la paga in token, e viene scelto o scartato in base a quel testo. La documentazione è netta su dove sia la leva: «Provide extremely detailed descriptions. This is by far the most important factor in tool performance».

Il contratto minimo

Una definizione di tool utente ha tre campi obbligatori e uno opzionale che vale la pena conoscere.

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol...",
  "input_schema": { "type": "object", "properties": {}, "required": [] },
  "input_examples": []
}

Il nome è vincolato da un’espressione regolare, quindi niente punti, spazi o due punti:

^[a-zA-Z0-9_-]{1,64}$

description è definita come «a detailed plaintext description of what the tool does, when it should be used, and how it behaves». input_examples è opzionale e serve ai tool con input annidati o sensibili al formato: ogni esempio deve essere valido rispetto allo schema — uno non valido restituisce un 400 — e costa circa 20-50 token se semplice, 100-200 se complesso. Non è supportato sui tool server-side.

La descrizione è il vero codice

Le linee guida elencano che cosa deve contenerci dentro: che cosa fa il tool, quando va usato e quando no, che cosa significa ogni parametro e come influenza il comportamento, e i limiti importanti — in particolare «what information the tool does not return». La lunghezza indicata è di almeno tre o quattro frasi per descrizione, «more if the tool is complex».

Il confronto fra la descrizione buona e quella cattiva nella documentazione è istruttivo perché la differenza non è di stile. «Gets the stock price for a ticker» è sintatticamente completa e operativamente inutile: non dice quali borse, non dice in quale valuta arriva il risultato, non dice che il tool non restituisce nient’altro sull’azienda. La versione buona dice tutte e tre le cose, e la terza è quella che gli architetti dimenticano: dichiarare che cosa il tool NON fa evita il giro di chiamate in cui l’agente lo prova comunque. Il ritorno sull’investimento è dichiarato: «even small refinements to tool descriptions can yield dramatic improvements». Il criterio pratico suggerito è scriverle come se stessi formando una persona appena entrata nel team, rendendo esplicito il contesto implicito su formati di query, terminologia e relazioni fra risorse.

Confini: consolidare invece di moltiplicare

L’errore ricorrente è mappare un tool per ogni endpoint dell’API sottostante. La raccomandazione è l’opposto: «consolidate related operations into fewer tools». Invece di create_pr, review_pr e merge_pr, un solo tool con un parametro action. Invece di list_users, list_events e create_event, un solo schedule_event che gestisce il flusso al proprio interno, perché «tools can consolidate functionality, handling potentially multiple discrete operations (or API calls) under the hood».

La ragione non è estetica ed è misurabile. «More tools don’t always lead to better outcomes», e soprattutto: «too many tools or overlapping tools can also distract agents from pursuing efficient strategies». Due tool che si sovrappongono parzialmente producono una scelta ambigua a ogni turno, e l’ambiguità si paga in chiamate sbagliate, latenza e giri inutili.

Il secondo strumento di confine è il namespacing: un prefisso per servizio o risorsa, github_list_prs e slack_send_message, asana_search e jira_search. Rende la selezione non ambigua mentre la libreria cresce, «and is especially important when using tool search».

Il confine vale anche sulla risposta

Un tool ben descritto che restituisce quaranta kilobyte di JSON grezzo resta un tool mal progettato: «design tool responses to return only high-signal information», perché «bloated responses waste context and make it harder for Claude to extract what matters». Le leve concrete sono due.

La prima è la forma dei dati. La guida di ingegneria suggerisce di privilegiare la rilevanza contestuale sulla flessibilità, quindi nomi e campi leggibili invece di identificatori tecnici di basso livello; la pagina di riferimento chiede identificatori semantici e stabili invece di riferimenti interni opachi. Le due indicazioni si riconciliano con il pattern che la stessa guida propone: un parametro response_format che accetta concise e detailed, così l’agente chiede la forma compatta quando gli basta leggere e quella estesa quando gli servono gli identificatori tecnici per la chiamata successiva.

La seconda leva è il volume: «implement some combination of pagination, range selection, filtering, and/or truncation with sensible default parameter values». E una risposta troncata non deve limitarsi a troncare: deve indirizzare l’agente verso una ricerca più mirata, invece di lasciarlo ripetere l’ennesima query larga.

Quando la libreria cresce

Superata una certa soglia il problema smette di essere la singola descrizione e diventa il monte token delle definizioni caricate a ogni richiesta. La raccomandazione operativa è introdurre il tool search «once your toolset grows past roughly 20 tools or your baseline context usage becomes noticeable»: le definizioni restano fuori dalla finestra di contesto finché Claude non le chiede. Il compromesso è dichiarato — si paga un turno in più di latenza per la ricerca, si recupera molto contesto di base — ed è esattamente il momento in cui il namespacing smette di essere igiene e diventa il meccanismo con cui la ricerca funziona.