Definire gli strumenti



Prerequisiti

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



Scegliere un modello

Usa il modello Claude Opus più recente, Claude Opus 5, 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 dedurre parametri mancanti.



Specificare gli strumenti client

Gli strumenti client (sia con schema Anthropic che definiti dall'utente) vengono 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 uno speciale 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/gli strumento/i specificato/i 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 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. Le 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 dallo 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 unico 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, aggiungi come prefisso 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 si usa la ricerca degli strumenti.
• Progetta le risposte degli strumenti in modo che restituiscano solo informazioni ad alto valore. 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 suo passo successivo. 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 sull'uso 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.



Uso 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",
    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 modelli concreti di 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 gli strumenti lato server - Gli esempi di input funzionano sugli strumenti client definiti dall'utente e con schema Anthropic, 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. 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 consente a Claude di decidere se chiamare o meno uno 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 imposti tool_choice 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 in linguaggio naturale o una spiegazione 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 comunque 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 tramite 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