Tool search tool

Tool search tool memungkinkan Claude bekerja dengan ratusan atau ribuan alat dengan cara menemukan dan memuatnya secara dinamis sesuai kebutuhan. Alih-alih memuat semua definisi alat ke dalam jendela konteks di awal, Claude mencari katalog alat Anda (termasuk nama alat, deskripsi, nama argumen, dan deskripsi argumen) dan hanya memuat alat yang diperlukan.

Pendekatan ini memecahkan dua masalah yang berkembang pesat seiring bertambahnya skala pustaka alat:

• Pembengkakan konteks: Definisi alat menghabiskan anggaran konteks Anda dengan cepat. Pengaturan multi-server yang umum (GitHub, Slack, Sentry, Grafana, Splunk) dapat mengonsumsi ~55k token dalam definisi sebelum Claude melakukan pekerjaan nyata apa pun. Tool search biasanya mengurangi ini lebih dari 85%, hanya memuat 3–5 alat yang benar-benar dibutuhkan Claude untuk permintaan tertentu.
• Akurasi pemilihan alat: Kemampuan Claude untuk memilih alat yang tepat menurun secara signifikan setelah melebihi 30–50 alat yang tersedia. Dengan menampilkan sekumpulan alat yang relevan secara terfokus sesuai permintaan, tool search menjaga akurasi pemilihan tetap tinggi bahkan di antara ribuan alat.

Meskipun ini disediakan sebagai alat sisi server, Anda juga dapat mengimplementasikan fungsionalitas tool search sisi klien Anda sendiri. Lihat Implementasi tool search kustom untuk detailnya.

Anda juga dapat mengimplementasikan tool search sisi klien dengan mengembalikan blok tool_reference dari implementasi pencarian Anda sendiri.

Cara kerja tool search

Ada dua varian tool search:

• Regex (tool_search_tool_regex_20251119): Claude membuat pola regex untuk mencari alat
• BM25 (tool_search_tool_bm25_20251119): Claude menggunakan kueri bahasa alami untuk mencari alat

Saat Anda mengaktifkan tool search tool:

1. Anda menyertakan tool search tool (misalnya, tool_search_tool_regex_20251119 atau tool_search_tool_bm25_20251119) dalam daftar alat Anda
2. Anda menyediakan semua definisi alat dengan defer_loading: true untuk alat yang tidak boleh dimuat segera
3. Claude hanya melihat tool search tool dan alat yang tidak ditangguhkan pada awalnya
4. Ketika Claude membutuhkan alat tambahan, ia mencari menggunakan tool search tool
5. API mengembalikan 3-5 blok tool_reference yang paling relevan
6. Referensi ini secara otomatis diperluas menjadi definisi alat lengkap
7. Claude memilih dari alat yang ditemukan dan memanggilnya

Ini menjaga jendela konteks Anda tetap efisien sambil mempertahankan akurasi pemilihan alat yang tinggi.

Mulai cepat

Berikut adalah contoh sederhana dengan alat yang ditangguhkan:

Definisi alat

Tool search tool memiliki dua varian:

{
  "type": "tool_search_tool_regex_20251119",
  "name": "tool_search_tool_regex"
}

{
  "type": "tool_search_tool_bm25_20251119",
  "name": "tool_search_tool_bm25"
}

Pemuatan alat yang ditangguhkan

Tandai alat untuk pemuatan sesuai permintaan dengan menambahkan defer_loading: true:

{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": { "type": "string" },
      "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
    },
    "required": ["location"]
  },
  "defer_loading": true
}

Poin-poin penting:

• Alat tanpa defer_loading dimuat ke dalam konteks segera
• Alat dengan defer_loading: true hanya dimuat ketika Claude menemukannya melalui pencarian
• Tool search tool itu sendiri tidak boleh memiliki defer_loading: true
• Pertahankan 3-5 alat yang paling sering digunakan sebagai non-deferred untuk performa optimal

Kedua varian tool search (regex dan bm25) mencari nama alat, deskripsi, nama argumen, dan deskripsi argumen.

Cara kerja penangguhan secara internal: Alat yang ditangguhkan tidak disertakan dalam prefiks system-prompt. Ketika model menemukan alat yang ditangguhkan melalui tool search, definisi alat ditambahkan secara inline sebagai blok tool_reference dalam percakapan. Prefiks tidak tersentuh, sehingga prompt caching tetap terjaga. Tata bahasa untuk mode ketat dibangun dari keseluruhan toolset, sehingga defer_loading dan mode ketat dapat dikombinasikan tanpa kompilasi ulang tata bahasa.

Format respons

Ketika Claude menggunakan tool search tool, respons menyertakan tipe blok baru:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll search for tools to help with the weather information."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01ABC123",
      "name": "tool_search_tool_regex",
      "input": {
        "query": "weather"
      }
    },
    {
      "type": "tool_search_tool_result",
      "tool_use_id": "srvtoolu_01ABC123",
      "content": {
        "type": "tool_search_tool_search_result",
        "tool_references": [{ "type": "tool_reference", "tool_name": "get_weather" }]
      }
    },
    {
      "type": "text",
      "text": "I found a weather tool. Let me get the weather for San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01XYZ789",
      "name": "get_weather",
      "input": { "location": "San Francisco", "unit": "fahrenheit" }
    }
  ],
  "stop_reason": "tool_use"
}

Memahami respons

• server_tool_use: Menunjukkan bahwa Claude sedang memanggil tool search tool
• tool_search_tool_result: Berisi hasil pencarian dengan objek tool_search_tool_search_result yang bersarang
• tool_references: Array objek tool_reference yang menunjuk ke alat yang ditemukan
• tool_use: Claude memanggil alat yang ditemukan

Blok tool_reference secara otomatis diperluas menjadi definisi alat lengkap sebelum ditampilkan ke Claude. Anda tidak perlu menangani perluasan ini sendiri. Ini terjadi secara otomatis di API selama Anda menyediakan semua definisi alat yang cocok dalam parameter tools.

Integrasi MCP

Untuk mengonfigurasi mcp_toolset dengan defer_loading, lihat MCP connector.

Implementasi tool search kustom

Anda dapat mengimplementasikan logika tool search Anda sendiri (misalnya, menggunakan embeddings atau pencarian semantik) dengan mengembalikan blok tool_reference dari alat kustom. Ketika Claude memanggil alat pencarian kustom Anda, kembalikan tool_result standar dengan blok tool_reference dalam array konten:

{
  "type": "tool_result",
  "tool_use_id": "toolu_your_tool_id",
  "content": [{ "type": "tool_reference", "tool_name": "discovered_tool_name" }]
}

Setiap alat yang direferensikan harus memiliki definisi alat yang sesuai dalam parameter tools tingkat atas dengan defer_loading: true. Pendekatan ini memungkinkan Anda menggunakan algoritma pencarian yang lebih canggih sambil mempertahankan kompatibilitas dengan sistem tool search.

Untuk contoh lengkap menggunakan embeddings, lihat tool search with embeddings cookbook.

Penanganan kesalahan

Kesalahan HTTP (status 400)

Kesalahan ini mencegah permintaan diproses:

Semua alat ditangguhkan:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "All tools have defer_loading set. At least one tool must be non-deferred."
  }
}

Definisi alat tidak ditemukan:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Tool reference 'unknown_tool' has no corresponding tool definition"
  }
}

Kesalahan hasil alat (status 200)

Kesalahan selama eksekusi alat mengembalikan respons 200 dengan informasi kesalahan di dalam body:

{
  "type": "tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "tool_search_tool_result_error",
    "error_code": "invalid_pattern"
  }
}

Kode kesalahan:

• too_many_requests: Batas laju terlampaui untuk operasi tool search
• invalid_pattern: Pola regex tidak valid
• pattern_too_long: Pola melebihi batas 200 karakter
• unavailable: Layanan tool search sementara tidak tersedia

Kesalahan umum

Prompt caching

Untuk cara defer_loading mempertahankan prompt caching, lihat Tool use with prompt caching.

Sistem secara otomatis memperluas blok tool_reference di seluruh riwayat percakapan, sehingga Claude dapat menggunakan kembali alat yang ditemukan pada giliran berikutnya tanpa perlu mencari ulang.

Streaming

Dengan streaming diaktifkan, Anda akan menerima event tool search sebagai bagian dari stream:

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "tool_search_tool_regex"}}

// Search query streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"weather\"}"}}

// Pause while search executes

// Search results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "tool_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "tool_search_tool_search_result", "tool_references": [{"type": "tool_reference", "tool_name": "get_weather"}]}}}

// Claude continues with discovered tools

Permintaan batch

Anda dapat menyertakan tool search tool dalam Messages Batches API. Operasi tool search melalui Messages Batches API dihargai sama dengan yang ada dalam permintaan Messages API biasa.

Retensi data

Tool search sisi server (alat tool_search) mengindeks dan menyimpan data katalog alat (nama alat, deskripsi, dan metadata argumen) di luar respons API langsung; data katalog ini disimpan sesuai dengan kebijakan retensi standar Anthropic. Implementasi tool search sisi klien kustom yang menggunakan Messages API standar sepenuhnya memenuhi syarat ZDR.

Untuk kelayakan ZDR di semua fitur, lihat API and data retention.

Batas dan praktik terbaik

Batas

• Alat maksimum: 10.000 alat dalam katalog Anda
• Hasil pencarian: Mengembalikan 3-5 alat paling relevan per pencarian
• Panjang pola: Maksimum 200 karakter untuk pola regex
• Dukungan model: Hanya Claude Mythos Preview, Sonnet 4.0+, Opus 4.0+ (tidak ada Haiku)

Kapan menggunakan tool search

Kasus penggunaan yang baik:

• 10+ alat tersedia dalam sistem Anda
• Definisi alat mengonsumsi >10k token
• Mengalami masalah akurasi pemilihan alat dengan set alat yang besar
• Membangun sistem bertenaga MCP dengan beberapa server (200+ alat)
• Pustaka alat yang terus berkembang seiring waktu

Kapan pemanggilan alat tradisional mungkin lebih baik:

• Kurang dari 10 alat secara total
• Semua alat sering digunakan dalam setiap permintaan
• Definisi alat yang sangat kecil (<100 token secara total)

Tips optimasi

• Pertahankan 3-5 alat yang paling sering digunakan sebagai non-deferred
• Tulis nama dan deskripsi alat yang jelas dan deskriptif
• Gunakan penamaan yang konsisten dalam nama alat: beri awalan berdasarkan layanan atau sumber daya (misalnya, github_, slack_) sehingga kueri pencarian secara alami menampilkan grup alat yang tepat
• Gunakan kata kunci semantik dalam deskripsi yang cocok dengan cara pengguna mendeskripsikan tugas
• Tambahkan bagian system prompt yang mendeskripsikan kategori alat yang tersedia: "You can search for tools to interact with Slack, GitHub, and Jira"
• Pantau alat mana yang ditemukan Claude untuk menyempurnakan deskripsi

Penggunaan

Penggunaan tool search tool dilacak dalam objek penggunaan respons:

{
  "usage": {
    "input_tokens": 1024,
    "output_tokens": 256,
    "server_tool_use": {
      "tool_search_requests": 2
    }
  }
}

Langkah selanjutnya