- Efisiensi konteks: Definisi tools dapat mengonsumsi porsi besar dari jendela konteks (50 tools dapat menggunakan 10-20K tokens), meninggalkan ruang lebih sedikit untuk pekerjaan sebenarnya.
- Akurasi pemilihan tools: Akurasi pemilihan tools menurun dengan lebih dari 30-50 tools yang dimuat sekaligus.
Cara kerja pencarian tools
Pencarian tools aktif secara default, dengan pengecualian yang tercantum dalam Konfigurasi pencarian tools. Ketika aktif, definisi tools ditahan dari jendela konteks. Agen menerima ringkasan tools yang tersedia dan mencari yang relevan ketika tugas memerlukan kemampuan yang belum dimuat. Hingga lima tools paling relevan dimuat ke dalam konteks secara default, di mana mereka tetap tersedia untuk giliran berikutnya sampai SDK mengompres pesan tempat agen menemukan mereka. Setelah pemadatan itu, agen mencari tools tersebut lagi ketika mereka membutuhkannya berikutnya. Pencarian tools menambahkan satu putaran ekstra setiap kali Claude mencari tools, tetapi untuk set tools besar ini diimbangi oleh konteks yang lebih kecil pada setiap giliran. Dengan lebih sedikit dari ~10 tools yang definisinya pas di jendela konteks, memuat semuanya di awal biasanya lebih cepat. Untuk detail tentang mekanisme API yang mendasarinya, lihat Pencarian tools dalam API.Pencarian tools tidak didukung pada penyebaran Microsoft Foundry yang dihosting di Azure, yang menolaknya di sisi server: SDK mendeteksi penolakan dan memuat definisi tools di awal untuk penyebaran itu.
ENABLE_TOOL_SEARCH tidak dapat mengesampingkan ini, karena penolakan berasal dari penyebaran itu sendiri.Konfigurasi pencarian tools
Pencarian tools aktif secara default. Untuk model pada daftar model yang tidak didukung SDK, SDK memuat definisi tools di awal, dan tidak ada nilaiENABLE_TOOL_SEARCH yang mengganti itu. Di Google Cloud’s Agent Platform, SDK memutuskan berdasarkan generasi model:
- Claude Opus 4.5, Sonnet 4.5, Haiku 4.5, dan yang lebih baru: pencarian tools aktif secara default.
- Model Agent Platform sebelumnya: SDK memuat definisi tools di awal, karena stack serving mereka menolak header beta yang diperlukan.
ENABLE_TOOL_SEARCHtidak dapat mengganti ini.
ENABLE_TOOL_SEARCH.
SDK juga menonaktifkan pencarian tools ketika ANTHROPIC_BASE_URL menunjuk ke host non-first-party, karena sebagian besar proxy tidak meneruskan blok tool_reference. Anda dapat mengganti default itu dengan variabel lingkungan ENABLE_TOOL_SEARCH:
Pengaturan
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS membuat pencarian tools tetap mati. Anda tidak dapat menggantinya dengan menetapkan ENABLE_TOOL_SEARCH sendiri. Organisasi Anda dapat membuat pencarian tools tetap aktif melalui pengaturan terkelola, pada Claude Code v2.1.227 atau lebih baru. Nonaktifkan kemampuan pra-rilis mencakup di mana penggantian berlaku dan apa yang dihapus variabel.
Pencarian tools berlaku untuk semua tools terdaftar, baik berasal dari server MCP jarak jauh atau server MCP SDK kustom. Ketika Anda menggunakan auto, SDK menghitung setiap definisi yang dapat ditunda pencarian tools terhadap satu ambang batas gabungan: setiap tools MCP yang tidak ditandai alwaysLoad, dari server apa pun, ditambah tools bawaan yang dimuat sesuai permintaan. SDK selalu memuat tools bawaan inti seperti Bash, Read, dan Edit di awal dan tidak menghitungnya terhadap ambang batas.
Atur nilai dalam opsi env pada query(). Dalam TypeScript, env menggantikan lingkungan subprocess, jadi sebarkan ...process.env untuk menjaga variabel yang diwariskan. Dalam Python, env digabungkan di atas lingkungan yang diwariskan. Contoh ini terhubung ke server MCP jarak jauh yang mengekspos banyak tools, pra-menyetujui semuanya dengan wildcard, dan menggunakan auto:5 sehingga pencarian tools diaktifkan ketika definisi yang dapat ditundanya mencapai 5% dari jendela konteks:
https://tools.example.com/mcp dengan URL server MCP Anda sendiri. Jika berhasil, teks hasil akan dicetak ke konsol.
Karena ini adalah panggilan query() single-shot, SDK akan melempar setelah menghasilkan hasil kesalahan, jadi contoh membungkus loop dalam blok try. Untuk melihat mengapa jalankan gagal, periksa subtype pesan hasil, seperti error_during_execution, di dalam loop. Untuk informasi lebih lanjut tentang pesan hasil, lihat Menangani hasil.
Optimalkan penemuan tools
Mekanisme pencarian mencocokkan kueri terhadap nama dan deskripsi tools. Nama sepertisearch_slack_messages muncul untuk berbagai permintaan daripada query_slack. Deskripsi dengan kata kunci spesifik (“Cari pesan Slack berdasarkan kata kunci, saluran, atau rentang tanggal”) cocok dengan lebih banyak kueri daripada yang generik (“Kueri Slack”).
Anda juga dapat menambahkan bagian prompt sistem yang mencantumkan kategori tools yang tersedia. Ini memberikan agen konteks tentang jenis tools apa yang tersedia untuk dicari. Teruskan teks melalui opsi systemPrompt di TypeScript atau system_prompt di Python, menggunakan preset claude_code dengan append, yang menambahkan teks Anda ke prompt preset daripada menggantinya:
Batas
- Tools maksimum: 10.000 tools dalam katalog Anda
- Hasil pencarian: mengembalikan hingga lima tools paling relevan per pencarian secara default
- Dukungan model: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5, dan model yang lebih baru; lihat kompatibilitas model dalam dokumentasi API untuk daftar terkini. Hal yang sama berlaku di Agent Platform Google Cloud.
Dokumentasi terkait
- Pencarian tools dalam API: Dokumentasi API lengkap untuk pencarian tools, termasuk implementasi kustom
- Hubungkan server MCP: Terhubung ke tools eksternal melalui server MCP
- Tools kustom: Bangun tools Anda sendiri dengan server MCP SDK
- Referensi SDK TypeScript: Referensi API lengkap
- Referensi SDK Python: Referensi API lengkap