Claude Tool Use: Come Do Capacità Reali ai Miei Agenti IA

Indice

Aggiornato luglio 2026.

TL;DR: Il tool use di Claude permette al tuo agente di compiere azioni — non solo generare testo. Definisci strumenti come schemi JSON, Claude decide quando chiamarli, e il tuo codice esegue l’azione nel mondo reale. Il loop ha tre fasi: invia messaggio → ricevi blocco tool_use → esegui e restituisci risultato. Ho implementato questo in 15+ agenti di produzione su Cloudflare Workers. Il punto di guasto non è quasi mai l’IA — sono i risultati ambigui che tornano dagli strumenti.

[Nota dell’operatore] Gestisco 30+ agenti IA in produzione tra un brand di consulenza e Pickleland, una struttura di pickleball a Pflugerville, TX. Circa la metà usa il tool use — la funzione dell’API Claude che permette al modello di chiamare funzioni definite dal tuo codice. Ecco il pattern a cui sono giunto dopo aver implementato e iterato in produzione.

Perché il tool use cambia ciò che un agente può fare

Senza strumenti, un agente può solo generare testo. Questo è utile per la sintesi, la redazione e la classificazione — ma non è ciò che la maggior parte delle automazioni aziendali richiede davvero. Le automazioni aziendali devono consultare informazioni, scrivere su database, chiamare API, inviare messaggi.

Il tool use è il modo in cui dai questo accesso a Claude. Definisci un insieme di strumenti come schemi JSON. Claude legge gli schemi, decide quale strumento chiamare e con quali argomenti, e restituisce un blocco di contenuto tool_use strutturato. Il tuo codice esegue la funzione reale. Claude ottiene il risultato e decide cosa fare dopo — incluso chiamare un altro strumento o produrre una risposta testuale finale.

La chiave: Claude decide quando e se chiamare uno strumento. Tu definisci le capacità. Il modello ragiona su quando usarle.

Come funziona il flusso API

Il loop di tool use ha tre fasi. Eseguirai questo loop una o più volte a seconda di quante chiamate di strumento effettua il modello.

Fase 1: Invia il tuo messaggio con gli strumenti definiti

const response = await anthropic.messages.create({
  model: "claude-haiku-4-5-20251001",
  max_tokens: 1024,
  tools: [
    {
      name: "check_court_availability",
      description:
        "Check if a court is available at a given date, time, and duration",
      input_schema: {
        type: "object",
        properties: {
          date: {
            type: "string",
            description: "Date in YYYY-MM-DD format",
          },
          time: {
            type: "string",
            description: "Start time in HH:MM format (24h)",
          },
          duration_minutes: {
            type: "number",
            description: "Duration of the booking in minutes",
          },
        },
        required: ["date", "time", "duration_minutes"],
      },
    },
  ],
  messages: [
    {
      role: "user",
      content: "Is a court available tomorrow at 2pm for 90 minutes?",
    },
  ],
});

Fase 2: Controlla se Claude vuole chiamare uno strumento

if (response.stop_reason === "tool_use") {
  const toolUseBlock = response.content.find(
    (block): block is Anthropic.ToolUseBlock => block.type === "tool_use"
  );

  if (!toolUseBlock) throw new Error("Expected tool_use block");

  // Run your actual function
  const toolResult = await checkCourtAvailability(
    toolUseBlock.input as CourtAvailabilityInput
  );

  // Step 3: Return the result to Claude
  const finalResponse = await anthropic.messages.create({
    model: "claude-haiku-4-5-20251001",
    max_tokens: 1024,
    tools: [
      /* same tools as before */
    ],
    messages: [
      {
        role: "user",
        content: "Is a court available tomorrow at 2pm for 90 minutes?",
      },
      { role: "assistant", content: response.content },
      {
        role: "user",
        content: [
          {
            type: "tool_result",
            tool_use_id: toolUseBlock.id,
            content: JSON.stringify(toolResult),
          },
        ],
      },
    ],
  });

  // finalResponse.content now has the text answer
}

Questo è l’intero pattern. Tre interazioni API per chiamata di strumento: definire strumenti → ricevere blocco tool_use → restituire risultato.

Esempio reale: il verificatore di disponibilità di Pickleland

Pickleland è una struttura di pickleball. Riceviamo richieste di prenotazione su Facebook Messenger, nei commenti e tramite un chatbot. La domanda è quasi sempre una variazione di “siete aperti sabato alle 15?” o “posso prenotare un campo per il mio gruppo di 8 persone?”

L’agente verificatore di disponibilità usa il tool use per interrogare il sistema di prenotazione reale in tempo reale invece di dare una risposta standard.

Ecco l’agente completo — semplificato ma fedele alla produzione:

// workers/availability-checker.ts
import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic();

const AVAILABILITY_TOOLS: Anthropic.Tool[] = [
  {
    name: "check_availability",
    description:
      "Check court availability for a date, time, and group size. Returns available courts and their prices.",
    input_schema: {
      type: "object",
      properties: {
        date: { type: "string", description: "YYYY-MM-DD" },
        start_time: { type: "string", description: "HH:MM (24h)" },
        duration_minutes: { type: "number" },
        players: { type: "number", description: "Number of players" },
      },
      required: ["date", "start_time", "duration_minutes"],
    },
  },
  {
    name: "get_pricing",
    description:
      "Get current pricing for court rentals and open play sessions",
    input_schema: {
      type: "object",
      properties: {
        session_type: {
          type: "string",
          enum: ["court_rental", "open_play", "clinics"],
        },
      },
      required: ["session_type"],
    },
  },
];

export async function handleInquiry(
  userMessage: string,
  env: Env
): Promise<string> {
  const messages: Anthropic.MessageParam[] = [
    { role: "user", content: userMessage },
  ];

  // Agentic loop — keep going until stop_reason is "end_turn"
  while (true) {
    const response = await anthropic.messages.create({
      model: "claude-haiku-4-5-20251001",
      max_tokens: 512,
      system:
        "You are the booking assistant for Pickleland, a pickleball facility in Pflugerville, TX. " +
        "Use the tools to look up real availability and pricing. Never make up availability or prices. " +
        "If the customer wants to book, direct them to pickleland.com/book.",
      tools: AVAILABILITY_TOOLS,
      messages,
    });

    // Push the assistant's response into message history
    messages.push({ role: "assistant", content: response.content });

    if (response.stop_reason === "end_turn") {
      const textBlock = response.content.find(
        (b): b is Anthropic.TextBlock => b.type === "text"
      );
      return (
        textBlock?.text ??
        "I wasn't able to answer that — please call us directly."
      );
    }

    if (response.stop_reason === "tool_use") {
      // Process ALL tool calls in this response (Claude can request multiple at once)
      const toolResults: Anthropic.ToolResultBlockParam[] = [];

      for (const block of response.content) {
        if (block.type !== "tool_use") continue;

        let result: unknown;

        switch (block.name) {
          case "check_availability":
            result = await checkAvailability(
              block.input as AvailabilityInput,
              env
            );
            break;
          case "get_pricing":
            result = await getPricing(block.input as PricingInput, env);
            break;
          default:
            result = { error: `Unknown tool: ${block.name}` };
        }

        toolResults.push({
          type: "tool_result",
          tool_use_id: block.id,
          content: JSON.stringify(result),
        });
      }

      // Return all tool results in a single user message
      messages.push({ role: "user", content: toolResults });
    }
  }
}

Due cose da evidenziare qui.

Il loop agentico. Continuo finché stop_reason === "end_turn". Claude potrebbe chiamare check_availability, decidere che ha bisogno anche dei prezzi, chiamare get_pricing, e poi produrre la risposta finale — sono tre chiamate API per un singolo messaggio dell’utente. Il loop gestisce questo senza alcuna logica speciale.

Chiamate multiple di strumenti per turno. Claude può restituire più blocchi tool_use in una singola risposta. Li elaboro tutti e restituisco tutti i risultati in un singolo messaggio user. Se li elabori uno alla volta e li restituisci individualmente, interrompi il flusso della conversazione e sprechi token.

Esempio reale: l’agente di ricerca lead

Il mio brand di consulenza usa un agente di ricerca che arricchisce i lead in entrata prima che io li contatti. Quando qualcuno compila il modulo di contatto, l’agente ricerca l’azienda ed estrae ciò che devo sapere prima della chiamata.

Le definizioni degli strumenti per questo includono uno strumento di scrittura — ed è qui che il pattern diventa interessante:

const RESEARCH_TOOLS: Anthropic.Tool[] = [
  {
    name: "search_company",
    description: "Search for information about a company",
    input_schema: {
      type: "object",
      properties: {
        company_name: { type: "string" },
        website: { type: "string", description: "Company website if known" },
      },
      required: ["company_name"],
    },
  },
  {
    name: "save_research",
    description:
      "Save the completed research summary to Airtable. Call this when all research is complete.",
    input_schema: {
      type: "object",
      properties: {
        company_summary: { type: "string" },
        estimated_size: {
          type: "string",
          enum: ["1-10", "11-50", "51-200", "200+"],
        },
        likely_use_case: { type: "string" },
        priority: { type: "string", enum: ["high", "medium", "low"] },
        notes: { type: "string" },
      },
      required: [
        "company_summary",
        "estimated_size",
        "likely_use_case",
        "priority",
      ],
    },
  },
];

save_research è quello che chiamo uno strumento di scrittura — il suo scopo non è ottenere informazioni, ma confermare l’output di Claude in un database in forma strutturata. Uso questo pattern invece di cercare di fare il parse di JSON da una risposta testuale. Claude sa quando la ricerca è completata e chiama save_research con campi correttamente tipizzati. Non scrivo mai un parser.

Questa è l’applicazione più pulita del tool use: definisci uno strumento di “azione finale” con lo schema esatto che vuoi, e Claude fornisce output strutturato tramite la chiamata allo strumento. Nessun parsing di testo, nessuna regex, nessuna validazione JSONSchema di output in testo libero.

Uno strumento vs. molti

L’istinto quando si inizia con il tool use è di costruire un unico strumento gigante che fa tutto. Resisti a questo. Gli strumenti piccoli e focalizzati sono migliori per tre ragioni:

1. Claude ragiona meglio sugli strumenti piccoli. Uno strumento chiamato get_court_status che restituisce la disponibilità è più facile da elaborare per il modello rispetto a uno strumento chiamato manage_facility che prende un parametro mode e si ramifica internamente.

2. Gli strumenti piccoli sono più facili da testare. Ogni strumento è una funzione TypeScript che puoi testare unitariamente indipendentemente dall’LLM. Dovresti farlo — i bug degli strumenti sono difficili da debuggare all’interno di una conversazione attiva.

3. Claude può parallelizzare gli strumenti piccoli. Se due strumenti non dipendono l’uno dall’altro, Claude può chiamarli nella stessa risposta e tu li elabori in parallelo. Questo funziona solo se gli strumenti sono genuinamente indipendenti.

L’eccezione: strumenti che necessitano di accesso a molto stato interno condiviso. Se la funzione ha bisogno di 10 variabili dalla stessa fonte di dati, uno strumento con uno schema più ricco supera 10 strumenti che accedono ciascuno separatamente al database.

La mia regola pratica: inizia con uno strumento per capacità distinta. Unisci gli strumenti solo quando vedi Claude chiamarli insieme ad ogni richiesta.

Implicazioni sui costi

Il tool use aggiunge token. Ogni definizione di strumento va nel contesto del prompt di sistema. Ogni blocco tool_use e tool_result consuma token nella cronologia della conversazione. Per un loop agentico multi-turno, questo si accumula rapidamente.

Per il verificatore di disponibilità di Pickleland, una conversazione tipica esegue 3–4 chiamate API in totale (messaggio iniziale + 1–2 chiamate di strumenti + risposta finale), ognuna elaborando 600–900 token. Ai prezzi di Haiku, questo costa meno di $0,001 per richiesta. Come spiego nel post sul calcolo dei costi degli agenti IA, Haiku gestisce in modo affidabile le attività di chiamata di strumenti ben definiti ed è 10× più economico di Sonnet per lo stesso volume di token.

L’agente di ricerca lead funziona su Sonnet perché le decisioni di giudizio — dare priorità a un lead, stimare l’idoneità — richiedono più capacità di ragionamento di quanto Haiku offra in modo affidabile su input aperti. Il calcolo funziona ancora perché viene eseguito raramente (alcune volte a settimana, non migliaia al giorno). La scelta del modello segue la complessità del compito, non la preferenza personale.

Il punto di guasto di cui nessuno parla

Il punto di guasto più comune che vedo nel tool use in produzione non è Claude che chiama lo strumento sbagliato. È lo strumento che restituisce qualcosa su cui Claude non riesce a ragionare chiaramente.

Se il tuo strumento restituisce un oggetto di database grezzo con 40 campi, Claude si confonde su quali campi siano importanti. Se il tuo strumento lancia un’eccezione (che appare come un crash del Worker invece che come un risultato dello strumento), il loop si interrompe silenziosamente. Se il tuo strumento restituisce null quando vuole dire “nessun risultato”, Claude non sa se riprovare o arrendersi.

Tre regole per i risultati degli strumenti:

Restituisci risultati concisi ed espliciti. { available: true, courts: ["Court 3", "Court 5"], price_per_hour: 20 } — non la riga completa del database.

Cattura gli errori all’interno della funzione dello strumento e restituiscili come risultati strutturati. { error: "booking system timeout", retry: true } — non un’eccezione lanciata che fa crashare il Worker.

Rendi “nessun risultato” esplicito. { available: false, next_available: "2026-07-23T14:00:00Z" } — non null o un array vuoto senza contesto.

Claude ragiona molto meglio su segnali chiari che su valori di ritorno ambigui. Ogni ora che ho trascorso a debuggare il tool use in produzione riguardava risultati poco chiari, non il ragionamento del modello.

La conclusione dell’operatore

Il tool use è la funzione che trasforma Claude da un generatore di testo in un operatore. Definisci strumenti focalizzati con schemi di input chiari. Gestisci tutti i blocchi tool_use in una singola risposta al modello. Esegui il loop agentico finché stop_reason === "end_turn". Restituisci risultati puliti e concisi dalle tue funzioni degli strumenti — non oggetti di dati grezzi, non eccezioni lanciate, non null ambigui.

Il modello gestisce il ragionamento. Il tuo codice gestisce le azioni nel mondo reale. Tieni questi due compiti chiaramente separati e l’architettura rimane manutenibile anche quando aggiungi strumenti.

Se stai costruendo il tuo primo agente con tool use, inizia con il pattern del verificatore di disponibilità sopra — uno strumento, uno scopo, un loop agentico. Metti in produzione quello. Poi aggiungi il secondo strumento.

Correlati: Lo stack di agenti che uso per gestire 30+ agenti in produzione · Haiku vs Sonnet: il calcolo dei costi per i task degli agenti · Agenti event-triggered vs schedulati: quale pattern per quale lavoro

Stai costruendo un agente con tool use e sei bloccato? Contattami — progetto e costruisco architetture di agenti di produzione per team di operatori.

FAQ

Il tool use di Claude funziona con tutti i modelli?

Sì — il tool use è supportato da tutti i modelli Claude attuali. Claude Haiku gestisce in modo affidabile strumenti ben definiti con schemi chiari ed è l’opzione più economica per i tipi di task ad alto volume. Sonnet gestisce meglio le decisioni di chiamata di strumenti più ambigue o aperte. Inizia con Haiku; passa a un modello superiore se la qualità dell’output non è sufficiente.

Qual è la differenza tra il tool use di Claude e il function calling di OpenAI?

Meccanicamente identici. OpenAI ha coniato “function calling”; Anthropic lo chiama “tool use”. In entrambi i casi: definisci schemi JSON, il modello restituisce chiamate strutturate, il tuo codice esegue la funzione. La forma dell’API differisce ma il concetto è lo stesso.

Claude può chiamare più strumenti in una singola risposta?

Sì. Claude può restituire più blocchi tool_use in una singola risposta assistant. Elaborali tutti e restituisci tutti i risultati in un singolo messaggio user. Vedi il pattern del loop agentico nell’esempio di Pickleland sopra — il ciclo for su response.content lo gestisce correttamente.

Quanti strumenti dovrei definire per agente?

Rimango sotto 8–10 strumenti per agente. Oltre questo, ho visto Claude occasionalmente scegliere lo strumento sbagliato al primo tentativo, il che spreca token in un loop di correzione. Se hai bisogno di più di 10 capacità, dividi l’agente in più agenti con set di strumenti specializzati invece di costruire un agente che sa tutto.

Dovrei usare il tool use per ottenere output strutturato?

Sì — il pattern dello strumento di scrittura save_research è più pulito che chiedere a Claude di restituire JSON in un blocco testuale e poi fare il parse. Definisci uno strumento di “azione finale” con lo schema esatto che vuoi. Claude lo chiamerà con campi correttamente tipizzati quando ha finito. Nessun parser necessario.