Definire gli strumenti

Prerequisiti

• Familiarità con la panoramica sull'uso degli strumenti
• Una chiave API di Claude e una configurazione funzionante dell'SDK o di cURL

Specificare gli strumenti client

Gli strumenti client vengono specificati nel parametro di primo livello tools della richiesta API. Gli strumenti client con schema Anthropic, come gli strumenti bash ed editor di testo, vengono dichiarati tramite un type con versione datata; consulta la pagina di ciascuno strumento, collegata dal Riferimento degli strumenti, per i campi che accetta. Gli strumenti computer use e browser use sono toolset client: una singola voce senza name che dichiara un insieme fisso di strumenti membri. Una definizione di strumento definita dall'utente include:

Per l'insieme completo delle proprietà opzionali disponibili su qualsiasi singola definizione di strumento, incluse cache_control, strict, defer_loading e allowed_callers, consulta il Riferimento degli strumenti. Una voce di toolset client accetta cache_control e allowed_callers sulla voce e imposta defer_loading per ciascun membro; consulta Toolset client.

{
  "name": "get_weather",
  "description": "Get the current weather in a given location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city and state, e.g. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

Prompt di sistema per l'uso degli strumenti

Quando chiami la Claude API con il parametro tools, l'API costruisce uno speciale "system prompt" (prompt di sistema) a partire dalle definizioni degli strumenti, dalla configurazione degli strumenti e da qualsiasi prompt di sistema specificato dall'utente. Il prompt costruito è progettato per istruire il modello a usare lo strumento o gli strumenti specificati e fornire il contesto necessario affinché lo strumento funzioni correttamente:

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}

Best practice per le definizioni degli strumenti

Per ottenere le migliori prestazioni da Claude quando usi gli strumenti, segui queste linee guida:

• Fornisci descrizioni estremamente dettagliate. Questo è di gran lunga il fattore più importante per le prestazioni degli strumenti. Le tue descrizioni dovrebbero spiegare ogni dettaglio dello strumento, inclusi:
  • Cosa fa lo strumento
  • Quando dovrebbe essere usato (e quando no)
  • Cosa significa ciascun parametro e come influisce sul comportamento dello strumento
  • Eventuali avvertenze o limitazioni importanti, come quali informazioni lo strumento non restituisce se il nome dello strumento non è chiaro. Più contesto puoi dare a Claude sui tuoi strumenti, migliore sarà nel decidere quando e come usarli. Punta ad almeno 3–4 frasi per ogni descrizione di strumento, di più se lo strumento è complesso.
• Dai priorità alle descrizioni, ma considera l'uso di input_examples per strumenti complessi. Descrizioni chiare sono la cosa più importante, ma per strumenti con input complessi, oggetti annidati o parametri sensibili al formato, puoi usare il campo input_examples per fornire esempi validati rispetto allo schema. Consulta Fornire esempi di uso degli strumenti per i dettagli.
• Consolida le operazioni correlate in meno strumenti. Invece di creare uno strumento separato per ogni azione (create_pr, review_pr, merge_pr), raggruppale in un singolo strumento con un parametro action. Strumenti meno numerosi e più capaci riducono l'ambiguità nella selezione e rendono la tua superficie di strumenti più facile da navigare per Claude.
• Usa un namespacing significativo nei nomi degli strumenti. Quando i tuoi strumenti coprono più servizi o risorse, anteponi ai nomi il servizio (ad esempio, github_list_prs, slack_send_message). Questo rende la selezione degli strumenti non ambigua man mano che la tua libreria cresce, ed è particolarmente importante quando usi la ricerca degli strumenti.
• Progetta le risposte degli strumenti in modo che restituiscano solo informazioni ad alto segnale. Restituisci identificatori semantici e stabili (ad esempio, slug o UUID) invece di riferimenti interni opachi, e includi solo i campi di cui Claude ha bisogno per ragionare sul passo successivo. Risposte gonfiate sprecano contesto e rendono più difficile per Claude estrarre ciò che conta.

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

{
  "name": "get_stock_price",
  "description": "Gets the stock price for a ticker.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

La buona descrizione spiega chiaramente cosa fa lo strumento, quando usarlo, quali dati restituisce e cosa significa il parametro ticker. La descrizione scadente è troppo breve e lascia Claude con molte domande aperte sul comportamento e sull'utilizzo dello strumento.

Fornire esempi di uso degli strumenti

Puoi fornire esempi concreti di input validi per gli strumenti per aiutare Claude a capire come usare i tuoi strumenti in modo più efficace. Questo è particolarmente utile per strumenti complessi con oggetti annidati, parametri opzionali o input sensibili al formato.

Utilizzo di base

Aggiungi un campo opzionale input_examples alla definizione del tuo strumento con un array di oggetti di input di esempio. Ogni esempio deve essere valido secondo l'input_schema dello strumento:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature",
                    },
                },
                "required": ["location"],
            },
            "input_examples": [
                {"location": "San Francisco, CA", "unit": "fahrenheit"},
                {"location": "Tokyo, Japan", "unit": "celsius"},
                {
                    "location": "New York, NY"  # 'unit' is optional
                },
            ],
        }
    ],
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

print(response)

Gli esempi vengono inclusi nel prompt insieme allo schema del tuo strumento, mostrando a Claude pattern concreti di chiamate di strumenti ben formate. Questo aiuta Claude a capire quando includere parametri opzionali, quali formati usare e come strutturare input complessi.

Requisiti e limitazioni

• Validazione dello schema - Ogni esempio deve essere valido secondo l'input_schema dello strumento. Esempi non validi restituiscono un errore 400
• Non supportato per strumenti lato server o toolset client - Gli esempi di input funzionano sugli strumenti client definiti dall'utente e con schema Anthropic diversi dai toolset computer use e browser use, ma non sugli strumenti server come la ricerca web o l'esecuzione di codice
• Costo in token - Gli esempi si aggiungono ai token del prompt: ~20–50 token per esempi semplici, ~100–200 token per oggetti annidati complessi

Controllare l'output di Claude

Forzare l'uso degli strumenti

In alcuni casi, potresti volere che Claude usi uno strumento specifico per rispondere alla domanda dell'utente, anche se Claude altrimenti risponderebbe direttamente senza chiamare uno strumento. Puoi farlo specificando lo strumento nel campo tool_choice della richiesta.

Non tutti i modelli e le impostazioni supportano l'uso forzato degli strumenti. Dove non è supportato, tool_choice: {"type": "any"} e tool_choice: {"type": "tool", "name": "..."} falliscono, mentre tool_choice: {"type": "auto"} (il valore predefinito) e tool_choice: {"type": "none"} continuano a funzionare:

Sui modelli che lo supportano, le righe evidenziate sono l'unica differenza rispetto a una richiesta standard di uso degli strumenti:

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    }
]

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

print(response)

Quando lavori con il parametro tool_choice, ci sono quattro opzioni possibili:

• auto permette a Claude di decidere se chiamare o meno uno degli strumenti forniti. Questo è il valore predefinito quando vengono forniti tools.
• any dice a Claude che deve usare uno degli strumenti forniti, ma non forza uno strumento in particolare.
• tool forza Claude a usare sempre uno strumento in particolare.
• none impedisce a Claude di usare qualsiasi strumento. Questo è il valore predefinito quando non vengono forniti tools.

Questo diagramma illustra come funziona ciascuna opzione:

Nota che quando hai tool_choice impostato su any o tool, l'API precompila il messaggio dell'assistente per forzare l'uso di uno strumento. Questo significa che i modelli non emetteranno una risposta o spiegazione in linguaggio naturale prima dei blocchi di contenuto tool_use, anche se viene chiesto esplicitamente di farlo.

I test hanno dimostrato che questo non dovrebbe ridurre le prestazioni. Se desideri che il modello fornisca contesto o spiegazioni in linguaggio naturale pur richiedendo che il modello usi uno strumento specifico, puoi usare {"type": "auto"} per tool_choice (il valore predefinito) e aggiungere istruzioni esplicite in un messaggio user. Ad esempio: What's the weather like in London? Use the get_weather tool in your response.

Risposte del modello con gli strumenti

Quando usa gli strumenti, Claude spesso commenta ciò che sta facendo o risponde in modo naturale all'utente prima di chiamare gli strumenti.

Ad esempio, dato il prompt "What's the weather like in San Francisco right now, and what time is it there?", Claude potrebbe rispondere con:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll help you check the current weather and time in San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}

Questo stile di risposta naturale aiuta gli utenti a capire cosa sta facendo Claude e crea un'interazione più conversazionale. Puoi guidare lo stile e il contenuto di queste risposte attraverso i tuoi prompt di sistema e fornendo <examples> nei tuoi prompt.

È importante notare che Claude può usare varie formulazioni e approcci quando spiega le sue azioni. Il tuo codice dovrebbe trattare queste risposte come qualsiasi altro testo generato dall'assistente, e non fare affidamento su convenzioni di formattazione specifiche.

Prossimi passi