Claude Platform Docs
PesanAlat

Pemecahan masalah penggunaan alat

Perbaiki kesalahan penggunaan alat yang paling umum dengan tabel diagnostik gejala-ke-perbaikan.

Temukan gejala atau kesalahan yang Anda lihat, lalu terapkan perbaikan yang tercantum untuknya.

Claude memanggil alat yang salah

GejalaKemungkinan penyebabPerbaikan
Claude memanggil alat A padahal Anda menginginkan alat BDeskripsi ambiguPertajam deskripsi. Bedakan alat berdasarkan KAPAN menggunakannya, bukan hanya APA yang dilakukannya. Lihat Mendefinisikan alat.
Claude tidak pernah memanggil alat AndaTabrakan nama alat atau skema yang terlalu generikPeriksa nama duplikat di seluruh daftar alat Anda. Tambahkan input_examples agar penggunaan yang dimaksud menjadi konkret.
Claude memanggil dengan tipe parameter yang salahSkema ambiguTambahkan strict: true (jika skema Anda berada dalam subset yang didukung) atau tambahkan input_examples.

Claude mengarang parameter alat

GejalaKemungkinan penyebabPerbaikan
Parameter yang tidak ada dalam skema AndaModel menghasilkan berlebihan tanpa mode strictTambahkan strict: true jika skema Anda berada dalam subset yang didukung.
Nilai parameter di luar enum AndaMode strict tidak ada atau enum terlalu besarPerkecil enum atau tambahkan input_examples yang menunjukkan pilihan yang valid.

Pemanggilan alat paralel tidak berfungsi

GejalaKemungkinan penyebabPerbaikan
Claude memanggil alat secara berurutan padahal paralel akan lebih baikPemformatan riwayat pesanKirim beberapa blok tool_result dalam SATU pesan pengguna, bukan satu per giliran. Lihat Penggunaan alat paralel.
disable_parallel_tool_use tampaknya diabaikanDiatur terlalu lambat dalam percakapanAtur pada permintaan yang mengembalikan tool_use. Mengaturnya pada permintaan selanjutnya tidak berpengaruh pada pemanggilan alat sebelumnya.

Cache terus menjadi tidak valid

GejalaKemungkinan penyebabPerbaikan
Setiap permintaan adalah cache misstool_choice, konfigurasi thinking, atau output_config.effort bervariasi antar permintaanJaga tool_choice tetap stabil atau tempatkan breakpoint cache_control sebelum titik variasi; pertahankan konfigurasi thinking dan tingkat effort konstan selama masa hidup percakapan yang di-cache. Lihat Penggunaan alat dengan caching prompt dan Thinking dan caching prompt.
Menambahkan alat di tengah percakapan merusak cacheAlat ditambahkan di awal array toolsDeklarasikan alat dengan defer_loading: true sejak permintaan pertama dan biarkan pencarian alat memuatnya secara inline, alih-alih menambahkannya ke array di kemudian waktu.

Kesalahan pada saat permintaan

Kolom Kesalahan menampilkan sebagian dari setiap pesan, dan ... mewakili teks yang bervariasi.

KesalahanPenyebabPerbaikan
tool_use ids were found without tool_result blocks immediately aftertool_result tidak ada untuk beberapa ID tool_use, atau tool_result bukan blok konten pertama dalam pesan penggunaKembalikan satu tool_result untuk setiap blok tool_use dalam respons asisten. Letakkan blok tool_result sebelum teks apa pun. Lihat Menangani pemanggilan alat dan Penggunaan alat paralel.
was found without a corresponding ... blockPermintaan lanjutan mencegah alat server yang sedang menunggu untuk dijalankanLihat Pemanggilan alat server tidak memiliki blok hasil.
Unsupported regex feature in pattern field: ...Sebuah pattern alat strict menggunakan fitur regex yang tidak dapat dikompilasi oleh mode strict, seperti backreference, batas kata, atau rentang {n,m} yang besarSederhanakan pola tersebut. Lihat Batasan JSON Schema.
Invalid regex in pattern field: ...Sebuah pattern alat strict memiliki lookahead, lookbehind, atau kesalahan sintaksisHapus lookahead atau lookbehind apa pun dan perbaiki kesalahan sintaksis apa pun. Lihat Batasan JSON Schema.
All tools have defer_loading: trueTidak ada alat yang terlihat oleh modelSetidaknya satu alat harus dimuat segera. Alat pencarian alat itu sendiri tidak boleh memiliki defer_loading: true.

Pemanggilan alat server tidak memiliki blok hasil

Sebuah alat server masih menunggu untuk dijalankan ketika blok server_tool_use atau mcp_tool_use-nya tidak memiliki blok hasil. Kesalahan was found without a corresponding ... block berarti permintaan lanjutan mencegah alat yang sedang menunggu tersebut dijalankan. Pesan kesalahan dan stop_reason sebelumnya menunjukkan alasannya. Gunakan kasus pertama yang cocok:

  • Pesan diakhiri dengan but no `<name>` tool was provided atau is not available after the last message: Di sini, <name> adalah nama alat, seperti web_search. Permintaan tidak lagi mendefinisikan alat tersebut. Kirim array tools yang sama seperti sebelumnya, dan mcp_servers yang sama untuk alat MCP.
  • stop_reason sebelumnya adalah tool_use: Pesan pengguna Anda memiliki konten setelah blok tool_result. Kirim hanya blok tool_result, satu untuk setiap blok tool_use klien.
  • stop_reason sebelumnya adalah pause_turn: Anda menambahkan pesan pengguna. Hapus pesan tersebut agar permintaan diakhiri dengan respons yang dijeda sebagai pesan assistant.

Untuk langkah lengkapnya, lihat Ketika alat server masih menunggu dan alasan berhenti pause_turn.

Kesalahan: blok thinking tidak dapat dimodifikasi

Jika sebuah permintaan gagal dengan 400 invalid_request_error yang pesannya berisi `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified saat melanjutkan percakapan setelah pemanggilan alat, aplikasi Anda mengubah blok thinking asisten sebelum mengirimkannya kembali. Kirim seluruh pesan asisten kembali tanpa perubahan, lalu tambahkan tool_result Anda.

Lihat Blok thinking tidak dapat dimodifikasi untuk kesalahan lengkap dan langkah perbaikannya.

Claude menandai hasil alat sebagai injeksi prompt

GejalaKemungkinan penyebabPerbaikan
Claude menolak bertindak berdasarkan hasil alat, atau meminta pengguna mengonfirmasi instruksi yang berasal darinyaInstruksi Anda sendiri dikirimkan di dalam konten tool_resultClaude dilatih untuk memperlakukan instruksi di dalam hasil alat sebagai konten pihak ketiga yang berpotensi tidak tepercaya. Pindahkan instruksi Anda keluar dari hasil alat: kirimkan dalam giliran user setelah blok tool_result, atau, pada model yang didukung, dalam pesan sistem di tengah percakapan. Jaga agar hasil alat hanya berisi data. Lihat Memitigasi jailbreak dan prompt injection.

Perbedaan escaping JSON antar versi model

GejalaPenyebabPerbaikan
Perbandingan string pada input alat gagal dengan model yang lebih baruEscaping Unicode dan garis miring berbeda antar versi modelParse dengan json.loads() atau JSON.parse(). Jangan pernah melakukan pencocokan string mentah pada input yang diserialisasi.

Langkah selanjutnya

Tulis skema dan deskripsi yang mengarahkan Claude ke alat yang tepat.

Jalankan alat dan kembalikan hasil dalam format pesan yang diperlukan.

Direktori lengkap alat yang disediakan Anthropic dan string versinya.

Apakah halaman ini membantu?