Skip to main content
Pencarian tools memungkinkan agen Anda bekerja dengan ratusan atau ribuan tools dengan secara dinamis menemukan dan memuat mereka sesuai permintaan. Alih-alih memuat semua definisi tools ke dalam jendela konteks di awal, agen mencari katalog tools Anda dan memuat hanya tools yang dibutuhkannya. Pendekatan ini menyelesaikan dua tantangan saat perpustakaan tools berkembang:
  • 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.
Pencarian tool aktif secara default. Untuk model pada daftar model yang tidak didukung SDK, SDK memuat definisi tool di awal, dan tidak ada nilai ENABLE_TOOL_SEARCH yang dapat menimpa 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 tool aktif secara default.
  • Model Agent Platform sebelumnya: SDK memuat definisi tool di awal, karena stack serving mereka menolak header beta yang diperlukan. ENABLE_TOOL_SEARCH tidak dapat menimpa ini.
Sebelum Claude Code v2.1.221, SDK menonaktifkan pencarian tool untuk semua model di Google Cloud’s Agent Platform kecuali Anda menetapkan ENABLE_TOOL_SEARCH. SDK juga menonaktifkan pencarian tool ketika ANTHROPIC_BASE_URL menunjuk ke host non-first-party, karena sebagian besar proxy tidak meneruskan blok tool_reference. Anda dapat menimpa default itu dengan environment variable ENABLE_TOOL_SEARCH: Pengaturan CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS membuat pencarian tool tetap mati. Anda tidak dapat menimpanya dengan menetapkan ENABLE_TOOL_SEARCH sendiri. Pada Claude Code v2.1.227 atau lebih baru, organisasi Anda dapat membuat pencarian tool tetap aktif di bawah variabel ini melalui pengaturan terkelola. Dalam sesi yang mendapatkan konfigurasi HIPAA, pencarian tool dimatikan, dan baik ENABLE_TOOL_SEARCH maupun pengaturan terkelola tidak dapat mengaktifkannya kembali. Nonaktifkan kemampuan pra-rilis mencakup di mana override berlaku dan apa yang dihapus variabel tersebut. Pencarian tool berlaku untuk semua tool 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 tool terhadap satu ambang batas gabungan: setiap tool MCP yang tidak ditandai alwaysLoad, dari server apa pun, ditambah tool bawaan yang dimuat sesuai permintaan. SDK memuat tool bawaan inti seperti Bash, Read, dan Edit di awal dan tidak menghitungnya terhadap ambang batas. Sebuah mod di salah satu plugin Anda juga dapat menunda sebuah tool atau memuatnya di awal, yang mengubah hitungan tersebut. 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 tool, pra-menyetujui semuanya dengan wildcard, dan menggunakan auto:5 sehingga pencarian tool diaktifkan ketika definisi yang dapat ditundanya mencapai 5% dari context window:
Untuk menjalankan contoh ini, ganti 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 seperti search_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:
Untuk rangkaian lengkap opsi prompt sistem, lihat Memodifikasi prompt sistem.

Batas

  • Tools maksimum: 10.000 tools dalam katalog Anda
  • Hasil pencarian: mengembalikan hingga lima tools paling relevan per pencarian secara default
  • Dukungan model: Opus 4, Sonnet 4, Haiku 4.5, dan model yang lebih baru, atau Opus 4.5, Sonnet 4.5, Haiku 4.5, dan model yang lebih baru di Agent Platform Google Cloud. Pada model yang lebih lama, SDK memuat definisi tool di awal, seperti yang dijelaskan dalam Konfigurasi pencarian tool.