# Tool Search Claude Code: Tunda Tool MCP, Hemat Konteks

> Tool search hanya memuat nama tool MCP saat sesi dimulai dan mengambil schema-nya saat dibutuhkan, jadi menambah server berhenti menagih konteks tiap request.

URL: https://www.matthewswong.com/id/blog/claude-code-tool-search-deferred-tools/

- Author: Matthews Wong (https://www.matthewswong.com/id/about/)
- Published: 2026-08-27
- Updated: 2026-08-27
- Category: AI

> **Key takeaway:** Tool search Claude Code menunda definisi tool MCP sampai Claude benar-benar membutuhkannya. Hanya nama tool dan server instructions yang dimuat saat sesi dimulai, sehingga menambah MCP server berdampak minimal pada context window Anda. Fitur ini menyala secara default pada model yang mendukung, diatur lewat ENABLE_TOOL_SEARCH, dan dimatikan per server dengan alwaysLoad.

Saya menyambungkan MCP server keenam dan sesi saya terukur menjadi lebih buruk sebelum akhirnya membaik. Bukan karena ada satu tool yang jelek — melainkan karena setiap server itu menerbitkan seluruh schema tool-nya ke dalam system prompt pada setiap request, dan modelnya membaca katalog sebelum membaca pertanyaannya.

Tool search adalah perbaikannya, dan ia sudah cukup lama menjadi default sehingga sebagian besar orang tidak pernah melihat masalahnya. Tulisan ini untuk kasus ketika Anda melihatnya: saat Anda menjalankan banyak server, saat Anda berada di balik gateway yang diam-diam mematikan deferral, atau saat Anda ingin tool satu server hadir di setiap giliran. Isinya empat nilai konfigurasi, jalan keluar alwaysLoad, konsekuensi prompt cache yang jarang disebut, dan apa yang perlu dilakukan penulis MCP server.

## Definisi tool adalah bagian yang mahal, dan letaknya di lapisan terburuk

Claude Code menyusun tiap request supaya isi yang jarang berubah ada di depan: system prompt beserta definisi tool-nya, lalu konteks proyek, lalu percakapan. Susunan itulah yang membuat prompt caching bekerja. Definisi tool duduk di lapisan paling pertama, dan itu berarti dua hal sekaligus — ia dibayar pada setiap request, dan perubahan apa pun padanya membatalkan semua cache di belakangnya.

Jadi sebuah server dengan empat puluh schema tool yang bertele-tele bukan biaya sekali bayar saat startup. Ia adalah sewa, ditagih tiap giliran, di lapisan yang bila terjadi reconnect di tengah sesi juga bisa merenggut seluruh cache percakapan Anda. Claude Code tidak menetapkan batas jumlah tool per server; batas praktisnya adalah anggaran konteks Anda, dan batas itu tiba lebih cepat dari dugaan orang.

## Empat nilai, dan hanya satu yang berupa kompromi

Tool search menyala secara default: tool MCP ditunda dan ditemukan saat dibutuhkan, dengan hanya nama dan server instructions yang dimuat di depan. Environment variable-nya ada untuk kasus ketika default itu keliru bagi setup Anda.

| Nilai | Perilaku | Kapan dipakai |
| --- | --- | --- |
| tidak diset | Semua tool MCP ditunda, dengan fallback untuk setup yang tak didukung | Default, dan hampir selalu benar |
| true | Memaksa deferral dan mengirim beta header lewat proxy | Di balik proxy yang Anda tahu meneruskan blok tool_reference |
| auto atau auto:N | Memuat definisi di depan selama masih di bawah ambang | Beberapa server kecil, di mana langkah pencarian hanya menambah latensi |
| false | Semuanya dimuat di depan, tanpa penundaan sama sekali | Debugging, atau provider yang menolak beta-nya |

## alwaysLoad, dan ongkosnya saat startup

Sebagian tool memang dibutuhkan Claude di hampir setiap giliran, dan memaksanya menjalankan langkah pencarian lebih dulu hanyalah latensi tanpa penghematan konteks. Field alwaysLoad mengecualikan satu server dari deferral sepenuhnya, dan tersedia di semua tipe server. Pakai untuk sedikit tool saja, karena tiap tool di depan memakan konteks yang seharusnya tersedia untuk percakapan Anda yang sebenarnya.

> Menyetel alwaysLoad membuat startup menunggu tool server tersebut, dibatasi lima detik oleh connect timeout standar, karena tool-nya harus sudah ada saat prompt pertama dibangun. Server lain menyambung di latar belakang. Server remote dengan entri cache yang valid menyuplai tool-nya dari cache tanpa menyambung, jadi ia tidak menahan startup — artinya flag ini jauh lebih murah pada server yang sudah pernah Anda sambungkan ketimbang pada yang masih dingin.

## Konsekuensi prompt cache yang jarang disebut

Ini bagian yang tidak saya duga, dan ia mengubah cara saya memandang stabilitas MCP. Ketika tool ditunda, server yang menyambung, terputus, atau mengubah daftar tool-nya hanya menambahkan isi baru — ia tidak mengusik apa pun yang sudah ter-cache. Ketika tool dimuat ke dalam prefix, perubahan apa pun padanya membatalkan cache dan request berikutnya membaca ulang seluruh percakapan Anda.

Itu penting karena MCP server bisa terputus tanpa Anda melakukan apa pun. Proses server stdio keluar, sesi HTTP kedaluwarsa, sebuah server menyambung ulang setelah kegagalan sesaat, atau server yang terhubung mengirim pembaruan tool dinamis yang mengubah daftarnya. Dengan deferral menyala, tidak satu pun dari itu menagih cache percakapan Anda. Dengan deferral mati, server yang labil diam-diam menagih Anda satu giliran tanpa cache setiap kali ia berkedip.

> Kalau angka cache creation token Anda tetap tinggi giliran demi giliran dan Anda tidak paham sebabnya, periksa dulu apakah tool search benar-benar aktif sebelum melihat hal lain. Gateway yang mematikannya ditambah satu server stdio yang tidak stabil adalah kombinasi yang memproses ulang seluruh riwayat Anda pada jadwal yang tidak pernah Anda tetapkan.

## Di mana ia diam-diam mematikan dirinya

Defaultnya adalah deferral, tetapi Claude Code kembali ke pemuatan di depan pada beberapa situasi, dan tidak satu pun mengumumkan dirinya:

- Ketika base URL mengarah ke host non-first-party, karena sebagian besar proxy tidak meneruskan blok tool_reference. Setel variabelnya secara eksplisit untuk menimpa fallback ini.
- Pada deployment Microsoft Foundry yang di-host di Azure, yang menolaknya di sisi server. Environment variable tidak bisa menimpa ini, karena penolakannya datang dari deployment-nya.
- Pada model Google Cloud Agent Platform yang lebih lama dari generasi Claude 4.5, yang serving stack-nya menolak beta header yang dibutuhkan.
- Ketika variabel experimental betas diset, yang menahan tool search tetap mati dan tidak bisa Anda timpa dengan menyetel variabel tool search sendiri.

## Kalau Anda sedang menulis MCP server

Deferral mengubah apa yang seharusnya server Anda terbitkan. Claude hanya melihat nama tool dan server instructions Anda sampai ia memutuskan untuk mencari, jadi field instructions mengerjakan tugas yang biasanya dilakukan deskripsi skill — ia harus menjelaskan kapan Claude perlu datang mencari:

- Sebutkan kategori tugas yang ditangani tool Anda, di kalimat pertama alih-alih kalimat ketiga.
- Sebutkan kapan Claude sebaiknya mencarinya, bukan cuma apa isinya.
- Buat ringkas: deskripsi tool dan server instructions sama-sama dipotong pada 2 KB, jadi taruh detail pentingnya di awal.

> Sebuah server bisa menandai satu tool sebagai always-loaded dengan menyertakan penanda alwaysLoad pada objek metadata tool tersebut, alih-alih mengecualikan seluruh server. Itu granularitas yang tepat untuk server dengan satu tool yang terus dipakai Claude dan tiga puluh yang hanya sesekali, dan ia jauh lebih sopan sebagai tetangga daripada menyetel flag di level server.

## Mematikan langkah pencarian tanpa mematikan deferral

Ini dua hal berbeda dan layak dipisahkan. Deferral menyangkut apa yang dimuat ke dalam prefix; tool ToolSearch adalah cara Claude mengambil definisi yang ditunda itu belakangan. Anda bisa menolak tool tersebut lewat permission rule, yang membiarkan deferral tetap berlaku tetapi menghapus kemampuan Claude mengambil yang ditunda — berguna ketika Anda menginginkan penghematan konteksnya dan sudah menjadikan setiap tool yang benar-benar dibutuhkan Claude sebagai always-loaded.

Untuk organisasi, kendalinya ada di tempat lain lagi. Managed settings bisa menjaga tool search tetap menyala di seluruh organisasi, dan managed MCP configuration mengatur server mana yang boleh disambungkan pengguna. Kalau tujuan Anda membatasi biaya konteks satu tim ketimbang sesi Anda sendiri, pasangan itulah tuasnya, bukan environment variable.

Aturan yang sekarang saya pakai sederhana: biarkan tool search menyala, tandai dua atau tiga tool yang benar-benar dipakai tiap giliran sebagai always-loaded, dan perlakukan angka cache creation yang terus tinggi sebagai sinyal bahwa ada sesuatu di lapisan tool yang bergerak. Penghematan konteks memang judulnya, tetapi alasan saya peduli adalah cache-nya — deferral adalah yang mencegah MCP server tidak andal diam-diam merenggut riwayat percakapan Anda tiap beberapa menit.

## Sumber & bacaan lanjutan

- Dokumentasi Claude Code — Connect Claude Code to tools via MCP
- Dokumentasi Claude Code — How Claude Code uses prompt caching
- Dokumentasi Claude Code — Explore the context window
- Dokumentasi Claude Code — Environment variables
- Dokumentasi Claude Code — Managed MCP configuration
- Dokumentasi Claude Code — Tools reference
- Dokumentasi Claude Code — MCP quickstart
- Dokumentasi Claude Code — Settings reference

## Source links

- https://code.claude.com/docs/en/mcp
- https://code.claude.com/docs/en/prompt-caching
- https://code.claude.com/docs/en/context-window
- https://code.claude.com/docs/en/env-vars
- https://code.claude.com/docs/en/managed-mcp
- https://code.claude.com/docs/en/tools-reference
- https://code.claude.com/docs/en/mcp-quickstart
- https://code.claude.com/docs/en/settings-reference

## FAQ

### Apa itu tool search di Claude Code?

Tool search menjaga pemakaian konteks MCP tetap rendah dengan menunda definisi tool sampai Claude membutuhkannya. Hanya nama tool dan server instructions yang dimuat saat sesi dimulai, dan schema lengkapnya diambil saat diperlukan. Artinya menambah MCP server berdampak minimal pada context window, dan Claude Code tidak menetapkan batas jumlah tool per server.

### Bagaimana cara mengonfigurasi ENABLE_TOOL_SEARCH?

Biarkan tidak diset untuk memakai default, di mana semua tool MCP ditunda. Setel ke true untuk memaksa deferral lewat proxy, false untuk memuat semuanya di depan, atau auto untuk memuat definisi di depan selama totalnya di bawah 10 persen context window. Pakai auto:N untuk persentase kustom, misalnya auto:5.

### Bagaimana menjaga tool satu MCP server selalu termuat?

Setel alwaysLoad ke true pada entri server tersebut di .mcp.json. Semua tool yang diekspos server itu lalu dimuat saat sesi dimulai terlepas dari nilai ENABLE_TOOL_SEARCH. Sebuah server juga bisa menandai tool tertentu sebagai always-loaded lewat metadata tool-nya, dan itu lebih baik daripada mengecualikan seluruh server ketika hanya satu tool yang terus dibutuhkan.

### Apakah tool search memengaruhi prompt caching di Claude Code?

Ya, secara signifikan. Ketika tool ditunda, server yang menyambung, terputus, atau mengubah daftar tool-nya hanya menambahkan isi dan membiarkan cache utuh. Ketika tool dimuat ke dalam prefix, perubahan apa pun membatalkan cache dan request berikutnya membaca ulang seluruh percakapan — jadi MCP server yang tidak stabil diam-diam menagih satu giliran tanpa cache setiap kali menyambung ulang.

### Kenapa tool search tidak bekerja di sesi Claude Code saya?

Claude Code kembali memuat tool di depan ketika ANTHROPIC_BASE_URL mengarah ke host non-first-party, pada deployment Microsoft Foundry yang di-host di Azure yang menolaknya di sisi server, dan pada model Google Cloud Agent Platform yang lebih lama dari generasi Claude 4.5. Menyetel CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS juga menahannya tetap mati dan tidak bisa ditimpa.

---

- HTML version: https://www.matthewswong.com/id/blog/claude-code-tool-search-deferred-tools/
- English: https://www.matthewswong.com/en/blog/claude-code-tool-search-deferred-tools/
- Site index for agents: https://www.matthewswong.com/llms.txt
- Sitemap: https://www.matthewswong.com/sitemap.xml
- API description (OpenAPI): https://www.matthewswong.com/openapi.json
