Tool Search Claude Code: Tunda Tool MCP, Hemat Konteks

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.

Apa yang dilakukan tiap nilai:

# Tool search is ON by default. These override it.

# Threshold mode: load definitions upfront while they total
# under 10% of the context window, defer all of them past that.
ENABLE_TOOL_SEARCH=auto claude

# Same, with your own percentage (N is 0-100).
ENABLE_TOOL_SEARCH=auto:5 claude

# Force deferral even through a proxy. Requests FAIL on proxies
# that do not support tool_reference blocks — that is the trade.
ENABLE_TOOL_SEARCH=true claude

# Load everything upfront, the pre-tool-search behaviour.
ENABLE_TOOL_SEARCH=false claude

# Or put it in the env block of settings.json so it applies
# to every session rather than the one you remembered to flag.

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.

// .mcp.json — exempt ONE server from deferral. Every tool it
// exposes loads at session start regardless of ENABLE_TOOL_SEARCH.
{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

// Cost: alwaysLoad makes STARTUP WAIT for that server's tools,
// capped at the standard 5-second connect timeout, because they
// have to be present when the first prompt is built. Other
// servers connect in the background.
//
// A server can also mark a SINGLE tool always-loaded by putting
// "anthropic/alwaysLoad": true in that tool's _meta object.

// To remove the search step itself rather than the deferral:
{
  "permissions": { "deny": ["ToolSearch"] }
}

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.

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.

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.