CostruisciStrumenti

Risoluzione dei problemi di utilizzo degli strumenti

Correggi gli errori più comuni nell'utilizzo degli strumenti con tabelle diagnostiche sintomo-soluzione.

Tabelle sintomo-soluzione per gli errori più comuni nell'utilizzo degli strumenti. Ogni soluzione fa riferimento incrociato alla pagina che possiede la funzionalità.

Claude chiama lo strumento sbagliato

Sintomo	Causa probabile	Soluzione
Claude chiama lo strumento A quando volevi lo strumento B	Ambiguità nella descrizione	Affina le descrizioni. Differenzia gli strumenti in base a QUANDO usarli, non solo COSA fanno. Vedi Definire gli strumenti.
Claude non chiama mai il tuo strumento	Collisione di nomi o schema troppo generico	Controlla i nomi duplicati nell'elenco degli strumenti. Aggiungi `input_examples` per rendere l'uso previsto concreto.
Claude chiama con tipi di parametri sbagliati	Il modello indovina uno schema ambiguo	Aggiungi `strict: true` (se il tuo schema è nel sottoinsieme supportato) o aggiungi `input_examples`.

Claude inventa parametri degli strumenti

Sintomo	Causa probabile	Soluzione
Parametro che non esiste nel tuo schema	Over-generation del modello senza modalità strict	Aggiungi `strict: true` se il tuo schema è nel sottoinsieme supportato.
Valori dei parametri al di fuori del tuo enum	Modalità strict mancante o enum troppo grande	Riduci l'enum o aggiungi `input_examples` mostrando le scelte valide.

Le chiamate parallele degli strumenti non funzionano

Sintomo	Causa probabile	Soluzione
Claude chiama gli strumenti sequenzialmente quando il parallelo sarebbe migliore	Formattazione della cronologia dei messaggi	Invia più blocchi `tool_result` in UN messaggio utente, non uno per turno. Vedi Utilizzo parallelo degli strumenti.
`disable_parallel_tool_use` sembra ignorato	Impostato troppo tardi nella conversazione	Deve essere impostato sulla richiesta che restituisce `tool_use`. Impostarlo su una richiesta successiva non ha effetto sulle chiamate degli strumenti precedenti.

La cache continua a invalidarsi

Sintomo	Causa probabile	Soluzione
Ogni richiesta è un cache miss	`tool_choice` varia tra le richieste	Mantieni `tool_choice` stabile o posiziona il punto di interruzione `cache_control` prima del punto di variazione. Vedi Utilizzo degli strumenti con prompt caching.
L'aggiunta di uno strumento a metà conversazione interrompe la cache	Strumento anteposto all'array degli strumenti	Usa `defer_loading: true` con la ricerca degli strumenti per aggiungere lo strumento inline invece di modificare l'inizio dell'array.

Errori al momento della richiesta

Errore	Causa	Soluzione
`tool_use ids were found without tool_result blocks immediately after`	`tool_result` mancante per alcuni `tool_use` ids, o `tool_result` non è il primo blocco di contenuto nel messaggio utente	Restituisci un `tool_result` per ogni blocco `tool_use` nella risposta dell'assistente. Metti i blocchi `tool_result` prima di qualsiasi testo. Vedi Gestire le chiamate degli strumenti e Utilizzo parallelo degli strumenti.
`Input schema is not compatible with strict mode: string patterns are not supported`	Utilizzo di `pattern` con `strict: true`	Rimuovi il pattern o elimina `strict: true`. La parola chiave `pattern` non è ancora nel sottoinsieme supportato di JSON Schema.
`All tools have defer_loading: true`	Nessuno strumento visibile al modello	Almeno uno strumento deve essere caricato immediatamente. Lo strumento di ricerca degli strumenti stesso non deve mai avere `defer_loading: true`.

Differenze di escape JSON (Opus 4.6+)

Sintomo	Causa	Soluzione
Il confronto di stringhe sugli input degli strumenti fallisce con i modelli più recenti	L'escape Unicode e forward-slash differisce tra le versioni del modello	Analizza con `json.loads()` o `JSON.parse()`. Non fare mai corrispondenze di stringhe grezze su input serializzati.

Passaggi successivi

Definire gli strumenti

Scrivi schemi e descrizioni che guidano Claude verso lo strumento giusto.

Gestire le chiamate degli strumenti

Esegui gli strumenti e restituisci i risultati nel formato di messaggio richiesto.

Riferimento degli strumenti

Directory completa degli strumenti dello schema Anthropic e delle loro stringhe di versione.

Was this page helpful?

Claude chiama lo strumento sbagliato

Sintomo	Causa probabile	Soluzione
Claude chiama lo strumento A quando volevi lo strumento B	Ambiguità nella descrizione	Affina le descrizioni. Differenzia gli strumenti in base a QUANDO usarli, non solo COSA fanno. Vedi Definire gli strumenti.
Claude non chiama mai il tuo strumento	Collisione di nomi o schema troppo generico	Controlla i nomi duplicati nell'elenco degli strumenti. Aggiungi `input_examples` per rendere l'uso previsto concreto.
Claude chiama con tipi di parametri sbagliati	Il modello indovina uno schema ambiguo	Aggiungi `strict: true` (se il tuo schema è nel sottoinsieme supportato) o aggiungi `input_examples`.

Claude inventa parametri degli strumenti

Sintomo	Causa probabile	Soluzione
Parametro che non esiste nel tuo schema	Over-generation del modello senza modalità strict	Aggiungi `strict: true` se il tuo schema è nel sottoinsieme supportato.
Valori dei parametri al di fuori del tuo enum	Modalità strict mancante o enum troppo grande	Riduci l'enum o aggiungi `input_examples` mostrando le scelte valide.

Le chiamate parallele degli strumenti non funzionano

Sintomo	Causa probabile	Soluzione
Claude chiama gli strumenti sequenzialmente quando il parallelo sarebbe migliore	Formattazione della cronologia dei messaggi	Invia più blocchi `tool_result` in UN messaggio utente, non uno per turno. Vedi Utilizzo parallelo degli strumenti.
`disable_parallel_tool_use` sembra ignorato	Impostato troppo tardi nella conversazione	Deve essere impostato sulla richiesta che restituisce `tool_use`. Impostarlo su una richiesta successiva non ha effetto sulle chiamate degli strumenti precedenti.

La cache continua a invalidarsi

Sintomo	Causa probabile	Soluzione
Ogni richiesta è un cache miss	`tool_choice` varia tra le richieste	Mantieni `tool_choice` stabile o posiziona il punto di interruzione `cache_control` prima del punto di variazione. Vedi Utilizzo degli strumenti con prompt caching.
L'aggiunta di uno strumento a metà conversazione interrompe la cache	Strumento anteposto all'array degli strumenti	Usa `defer_loading: true` con la ricerca degli strumenti per aggiungere lo strumento inline invece di modificare l'inizio dell'array.

Errori al momento della richiesta

Errore	Causa	Soluzione
`tool_use ids were found without tool_result blocks immediately after`	`tool_result` mancante per alcuni `tool_use` ids, o `tool_result` non è il primo blocco di contenuto nel messaggio utente	Restituisci un `tool_result` per ogni blocco `tool_use` nella risposta dell'assistente. Metti i blocchi `tool_result` prima di qualsiasi testo. Vedi Gestire le chiamate degli strumenti e Utilizzo parallelo degli strumenti.
`Input schema is not compatible with strict mode: string patterns are not supported`	Utilizzo di `pattern` con `strict: true`	Rimuovi il pattern o elimina `strict: true`. La parola chiave `pattern` non è ancora nel sottoinsieme supportato di JSON Schema.
`All tools have defer_loading: true`	Nessuno strumento visibile al modello	Almeno uno strumento deve essere caricato immediatamente. Lo strumento di ricerca degli strumenti stesso non deve mai avere `defer_loading: true`.

Sintomo

Causa

Soluzione

Il confronto di stringhe sugli input degli strumenti fallisce con i modelli più recenti

L'escape Unicode e forward-slash differisce tra le versioni del modello

Analizza con json.loads() o JSON.parse(). Non fare mai corrispondenze di stringhe grezze su input serializzati.