Definire gli strumenti



Scegliere un modello

Usa il modello Claude Opus (4.8) più recente per strumenti complessi e query ambigue; gestisce meglio più strumenti e chiede chiarimenti quando necessario.

Usa i modelli Claude Haiku per strumenti semplici, ma tieni presente che potrebbero inferire parametri mancanti.



Specificare gli strumenti client

Gli strumenti client (sia quelli con schema Anthropic che quelli definiti dall'utente) sono specificati nel parametro di primo livello tools della richiesta API. Ogni definizione di strumento include:

Per l'insieme completo delle proprietà opzionali disponibili su qualsiasi definizione di strumento, inclusi cache_control, strict, defer_loading e allowed_callers, consulta il Riferimento degli strumenti.



Prompt di sistema per l'uso degli strumenti

Quando chiami l'API di Claude con il parametro tools, l'API costruisce un prompt di sistema speciale 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 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 non dovrebbe)
  • Cosa significa ogni 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 fornire a Claude sui tuoi strumenti, meglio sarà in grado di decidere quando e come usarli. Punta ad almeno 3-4 frasi per descrizione dello 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. Vedi 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 unico strumento con un parametro action. Meno strumenti, ma 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, aggiungi un prefisso ai nomi con il servizio (ad es. 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 per restituire solo informazioni ad alto valore. Restituisci identificatori semantici e stabili (ad es. slug o UUID) invece di riferimenti interni opachi, e includi solo i campi di cui Claude ha bisogno per ragionare sul suo prossimo passo. Risposte gonfiate sprecano contesto e rendono più difficile per Claude estrarre ciò che conta.

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 l'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:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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 sono inclusi nel prompt insieme allo schema del tuo strumento, mostrando a Claude pattern concreti per chiamate agli 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 - Gli esempi di input funzionano su strumenti client definiti dall'utente e con schema Anthropic, ma non su strumenti server come la ricerca web o l'esecuzione di codice
• Costo in token - Gli esempi aggiungono token al 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 risponderebbe altrimenti direttamente senza chiamare uno strumento. Puoi farlo specificando lo strumento nel campo tool_choice della richiesta. Le righe evidenziate sono l'unica differenza rispetto a una richiesta standard di uso degli strumenti:

import anthropic

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-4-8",
    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 consente a Claude di decidere se chiamare o meno uno qualsiasi degli strumenti forniti. Questo è il valore predefinito quando vengono forniti tools.
• any indica a Claude che deve usare uno degli strumenti forniti, ma non forza uno strumento particolare.
• tool forza Claude a usare sempre uno strumento 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. Ciò significa che i modelli non emetteranno una risposta o spiegazione in linguaggio naturale prima dei blocchi di contenuto tool_use, anche se esplicitamente richiesto.

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 strumenti

Quando usa gli strumenti, Claude spesso commenta ciò che sta facendo o risponde in modo naturale all'utente prima di invocare 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.



Passaggi successivi