MessaggiStrumenti

Risoluzione dei problemi nell'uso degli strumenti

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

Tabelle sintomo-soluzione per gli errori più comuni nell'uso degli strumenti. Ogni soluzione fa riferimento alla pagina che documenta 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 a COSA fanno. Consulta Definire gli strumenti.
Claude non chiama mai il tuo strumento	Collisione di nomi degli strumenti o schema troppo generico	Verifica la presenza di nomi duplicati nell'elenco degli strumenti. Aggiungi `input_examples` per rendere concreto l'uso previsto.
Claude chiama con tipi di parametri errati	Il modello tira a indovinare su uno schema ambiguo	Aggiungi `strict: true` (se il tuo schema rientra nel sottoinsieme supportato) o aggiungi `input_examples`.

Claude inventa parametri degli strumenti

Sintomo	Causa probabile	Soluzione
Parametro che non esiste nel tuo schema	Sovra-generazione del modello senza modalità strict	Aggiungi `strict: true` se il tuo schema rientra 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` che mostrino scelte valide.

Le chiamate parallele agli strumenti non funzionano

Sintomo	Causa probabile	Soluzione
Claude chiama gli strumenti in sequenza quando sarebbe meglio in parallelo	Formattazione della cronologia dei messaggi	Invia più blocchi `tool_result` in UN SOLO messaggio utente, non uno per turno. Consulta Uso 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 agli 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 breakpoint `cache_control` prima del punto di variazione. Consulta Uso degli strumenti con la cache dei prompt.
Aggiungere uno strumento a metà conversazione invalida 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 id `tool_use`, oppure `tool_result` non è il primo blocco di contenuto nel messaggio utente	Restituisci un `tool_result` per ogni blocco `tool_use` nella risposta dell'assistente. Posiziona i blocchi `tool_result` prima di qualsiasi testo. Consulta Gestire le chiamate agli strumenti e Uso parallelo degli strumenti.
`was found without a corresponding <name>_tool_result block`	Il turno precedente dell'assistente ha un blocco `server_tool_use` senza blocco di risultato (il più delle volte, Claude lo ha chiamato insieme a uno strumento client), e il tuo messaggio utente successivo ha terminato quel turno (ad esempio, con del testo dopo i blocchi `tool_result`) oppure la richiesta di ripresa non definisce più quello strumento server (il messaggio termina quindi con `but no <name> tool was provided`)	Invia un messaggio utente contenente solo i blocchi `tool_result` per gli id `tool_use` client e mantieni lo stesso array `tools`. Consulta Motivi di arresto e fallback.
`Input schema is not compatible with strict mode: string patterns are not supported`	Uso di `pattern` con `strict: true`	Rimuovi il pattern o elimina `strict: true`. La parola chiave `pattern` non è ancora nel sottoinsieme JSON Schema supportato.
`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`.

Errore: i blocchi thinking non possono essere modificati

Se una richiesta fallisce con un errore 400 invalid_request_error il cui messaggio contiene `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified quando continui una conversazione dopo una chiamata a uno strumento, la tua applicazione sta alterando i blocchi thinking dell'assistente prima di rinviarli. Rinvia l'intero messaggio dell'assistente senza modifiche, quindi aggiungi il tuo tool_result.

Consulta I blocchi thinking non possono essere modificati per l'errore completo e i passaggi di risoluzione.

Claude segnala i risultati degli strumenti come prompt injection

Sintomo	Causa probabile	Soluzione
Claude rifiuta di agire su un risultato di uno strumento, o chiede all'utente di confermare le istruzioni che ne derivano	Le tue istruzioni vengono fornite all'interno del contenuto `tool_result`	Claude è addestrato a trattare le istruzioni all'interno dei risultati degli strumenti come contenuto di terze parti potenzialmente non attendibile. Sposta le tue istruzioni fuori dal risultato dello strumento: inviale in un turno `user` dopo il blocco `tool_result`, oppure (su Claude Opus 4.8 e versioni successive) in un messaggio di sistema a metà conversazione. Limita il risultato dello strumento ai soli dati. Consulta Mitigare jailbreak e prompt injection.

Differenze nell'escaping JSON (Opus 4.6+)

Sintomo	Causa	Soluzione
Il confronto di stringhe sugli input degli strumenti fallisce con i modelli più recenti	L'escaping di Unicode e delle barre oblique differisce tra le versioni del modello	Effettua il parsing con `json.loads()` o `JSON.parse()`. Non fare mai confronti di stringhe grezze sull'input serializzato.

Passaggi successivi

Definire gli strumenti

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

Gestire le chiamate agli strumenti

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

Riferimento degli strumenti

Directory completa degli strumenti con schema Anthropic e le loro stringhe di versione.

Was this page helpful?

MessaggiStrumenti

Risoluzione dei problemi nell'uso degli strumenti

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

Tabelle sintomo-soluzione per gli errori più comuni nell'uso degli strumenti. Ogni soluzione fa riferimento alla pagina che documenta 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 a COSA fanno. Consulta Definire gli strumenti.
Claude non chiama mai il tuo strumento	Collisione di nomi degli strumenti o schema troppo generico	Verifica la presenza di nomi duplicati nell'elenco degli strumenti. Aggiungi `input_examples` per rendere concreto l'uso previsto.
Claude chiama con tipi di parametri errati	Il modello tira a indovinare su uno schema ambiguo	Aggiungi `strict: true` (se il tuo schema rientra nel sottoinsieme supportato) o aggiungi `input_examples`.

Claude inventa parametri degli strumenti

Sintomo	Causa probabile	Soluzione
Parametro che non esiste nel tuo schema	Sovra-generazione del modello senza modalità strict	Aggiungi `strict: true` se il tuo schema rientra 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` che mostrino scelte valide.

Le chiamate parallele agli strumenti non funzionano

Sintomo	Causa probabile	Soluzione
Claude chiama gli strumenti in sequenza quando sarebbe meglio in parallelo	Formattazione della cronologia dei messaggi	Invia più blocchi `tool_result` in UN SOLO messaggio utente, non uno per turno. Consulta Uso 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 agli 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 breakpoint `cache_control` prima del punto di variazione. Consulta Uso degli strumenti con la cache dei prompt.
Aggiungere uno strumento a metà conversazione invalida 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 id `tool_use`, oppure `tool_result` non è il primo blocco di contenuto nel messaggio utente	Restituisci un `tool_result` per ogni blocco `tool_use` nella risposta dell'assistente. Posiziona i blocchi `tool_result` prima di qualsiasi testo. Consulta Gestire le chiamate agli strumenti e Uso parallelo degli strumenti.
`was found without a corresponding <name>_tool_result block`	Il turno precedente dell'assistente ha un blocco `server_tool_use` senza blocco di risultato (il più delle volte, Claude lo ha chiamato insieme a uno strumento client), e il tuo messaggio utente successivo ha terminato quel turno (ad esempio, con del testo dopo i blocchi `tool_result`) oppure la richiesta di ripresa non definisce più quello strumento server (il messaggio termina quindi con `but no <name> tool was provided`)	Invia un messaggio utente contenente solo i blocchi `tool_result` per gli id `tool_use` client e mantieni lo stesso array `tools`. Consulta Motivi di arresto e fallback.
`Input schema is not compatible with strict mode: string patterns are not supported`	Uso di `pattern` con `strict: true`	Rimuovi il pattern o elimina `strict: true`. La parola chiave `pattern` non è ancora nel sottoinsieme JSON Schema supportato.
`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`.

Errore: i blocchi thinking non possono essere modificati

Consulta I blocchi thinking non possono essere modificati per l'errore completo e i passaggi di risoluzione.

Claude segnala i risultati degli strumenti come prompt injection

Sintomo	Causa probabile	Soluzione
Claude rifiuta di agire su un risultato di uno strumento, o chiede all'utente di confermare le istruzioni che ne derivano	Le tue istruzioni vengono fornite all'interno del contenuto `tool_result`	Claude è addestrato a trattare le istruzioni all'interno dei risultati degli strumenti come contenuto di terze parti potenzialmente non attendibile. Sposta le tue istruzioni fuori dal risultato dello strumento: inviale in un turno `user` dopo il blocco `tool_result`, oppure (su Claude Opus 4.8 e versioni successive) in un messaggio di sistema a metà conversazione. Limita il risultato dello strumento ai soli dati. Consulta Mitigare jailbreak e prompt injection.

Differenze nell'escaping JSON (Opus 4.6+)

Sintomo	Causa	Soluzione
Il confronto di stringhe sugli input degli strumenti fallisce con i modelli più recenti	L'escaping di Unicode e delle barre oblique differisce tra le versioni del modello	Effettua il parsing con `json.loads()` o `JSON.parse()`. Non fare mai confronti di stringhe grezze sull'input serializzato.

Passaggi successivi

Definire gli strumenti

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

Gestire le chiamate agli strumenti

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

Riferimento degli strumenti

Directory completa degli strumenti con schema Anthropic e le loro stringhe di versione.

Was this page helpful?

Claude chiama lo strumento sbagliato

Claude inventa parametri degli strumenti

Le chiamate parallele agli strumenti non funzionano

La cache continua a invalidarsi

Errori al momento della richiesta

Errore: i blocchi thinking non possono essere modificati

Claude segnala i risultati degli strumenti come prompt injection

Differenze nell'escaping JSON (Opus 4.6+)

Passaggi successivi

Claude chiama lo strumento sbagliato

Claude inventa parametri degli strumenti

Le chiamate parallele agli strumenti non funzionano

La cache continua a invalidarsi

Errori al momento della richiesta

Errore: i blocchi thinking non possono essere modificati

Claude segnala i risultati degli strumenti come prompt injection

Differenze nell'escaping JSON (Opus 4.6+)

Passaggi successivi

Claude chiama lo strumento sbagliato

Claude inventa parametri degli strumenti

Le chiamate parallele agli strumenti non funzionano

La cache continua a invalidarsi

Errori al momento della richiesta

Errore: i blocchi thinking non possono essere modificati

Claude segnala i risultati degli strumenti come prompt injection

Differenze nell'escaping JSON (Opus 4.6+)

Passaggi successivi

Claude chiama lo strumento sbagliato

Claude inventa parametri degli strumenti

Le chiamate parallele agli strumenti non funzionano

La cache continua a invalidarsi

Errori al momento della richiesta

Errore: i blocchi thinking non possono essere modificati

Claude segnala i risultati degli strumenti come prompt injection

Differenze nell'escaping JSON (Opus 4.6+)

Passaggi successivi