Tool search tool

Tool search tool (alat pencarian alat) memungkinkan Claude bekerja dengan ratusan atau ribuan alat dengan menemukan dan memuatnya sesuai permintaan. 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 memuat hanya alat yang dibutuhkannya.

Memuat setiap definisi alat di awal menyebabkan dua masalah seiring bertambahnya pustaka alat:

• Pembengkakan konteks: Pengaturan multiserver yang umum (GitHub, Slack, Sentry, Grafana, dan Splunk) dapat mengonsumsi ~55k token dalam definisi sebelum Claude melakukan pekerjaan apa pun. Tool search biasanya mengurangi ini lebih dari 85 persen, memuat hanya 3–5 alat yang dibutuhkan Claude untuk permintaan tertentu.
• Akurasi pemilihan alat: Kemampuan Claude untuk memilih alat yang tepat menurun setelah Anda melebihi 30–50 alat yang tersedia. Karena tool search hanya memuat sekumpulan alat relevan yang terfokus sesuai permintaan, akurasi pemilihan tetap tinggi bahkan di antara ribuan alat.

Tool search tersedia secara umum di Claude API. Untuk model yang didukung, lihat Kompatibilitas model.

Tool search berjalan sebagai alat sisi server, tetapi Anda juga dapat mengimplementasikan tool search sisi klien Anda sendiri. Lihat Implementasi tool search kustom untuk detailnya.



Kompatibilitas model

Kedua varian tool search tersedia pada model-model berikut:

Claude Opus 4.1 dan model-model sebelumnya tidak mendukung tool search tool.



Cara kerja tool search

Ada dua varian tool search:

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

Ketika 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 tools Anda.
2. Anda menyediakan setiap definisi alat dalam array tools dan menyetel defer_loading: true pada alat yang tidak boleh dimuat di awal. Setidaknya satu alat, biasanya tool search tool itu sendiri, harus tetap non-deferred.
3. Awalnya, konteks Claude hanya berisi tool search tool dan alat non-deferred apa pun.
4. Ketika Claude membutuhkan alat tambahan, ia mencari menggunakan tool search tool.
5. API menjalankan pencarian dan mengembalikan alat yang cocok sebagai blok tool_reference (hingga 5 secara default).
6. API secara otomatis memperluas referensi ini menjadi definisi alat lengkap.
7. Claude memilih dari alat yang ditemukan dan memanggilnya.



Mulai cepat

Contoh berikut menyertakan tool search tool dan dua alat yang ditangguhkan (deferred):

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=2048,
    messages=[{"role": "user", "content": "What is the weather in San Francisco?"}],
    tools=[
        {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
        {
            "name": "get_weather",
            "description": "Get the weather at a specific location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                },
                "required": ["location"],
            },
            "defer_loading": True,
        },
        {
            "name": "search_files",
            "description": "Search through files in the workspace",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {"type": "string"},
                    "file_types": {"type": "array", "items": {"type": "string"}},
                },
                "required": ["query"],
            },
            "defer_loading": True,
        },
    ],
)

print(response)

Claude mencari katalog, menemukan get_weather, dan memanggilnya. Respons berakhir dengan stop_reason: "tool_use". Jalankan alat yang ditemukan dan kembalikan tool_result seperti dalam Menangani panggilan alat. Format respons menunjukkan blok yang Anda dapatkan kembali dan apa yang harus dikirim selanjutnya.



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
}

defer_loading mengontrol apa yang masuk ke jendela konteks, bukan apa yang Anda kirim dalam permintaan:

• Anda tetap mengirim definisi lengkap setiap alat dalam array tools pada setiap permintaan, termasuk yang ditangguhkan. API membutuhkannya di sisi server untuk menjalankan pencarian dan memperluas blok tool_reference.
• Alat tanpa defer_loading dimuat ke dalam konteks segera.
• Alat dengan defer_loading: true dimuat hanya ketika Claude menemukannya melalui pencarian.
• Jangan pernah menyetel defer_loading: true pada tool search tool itu sendiri.
• Pertahankan 3–5 alat yang paling sering Anda gunakan sebagai non-deferred sehingga Claude dapat memanggilnya tanpa mencari terlebih dahulu.

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

Secara internal, API mengecualikan alat yang ditangguhkan dari prefiks prompt sistem. Ketika Claude menemukan alat yang ditangguhkan melalui tool search, API menambahkan blok tool_reference secara inline dalam percakapan, lalu memperluasnya menjadi definisi alat lengkap sebelum meneruskannya ke Claude. Prefiks tidak tersentuh, sehingga caching prompt tetap terjaga. Grammar untuk strict mode (aturan yang membatasi output panggilan alat agar sesuai dengan skema Anda) dibangun dari toolset lengkap, sehingga defer_loading dan strict mode dapat digabungkan tanpa kompilasi ulang grammar.



Format respons

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

{
  "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": {
        "pattern": "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: panggilan Claude ke tool search tool. Pencarian berjalan di server Anthropic. Jangan pernah mengembalikan tool_result untuk ID srvtoolu_...-nya.
• tool_search_tool_result: hasil pencarian, dalam objek tool_search_tool_search_result bersarang. Pertahankan dalam riwayat pesan apa adanya.
• tool_references: array objek tool_reference yang menunjuk ke alat yang ditemukan. API memperluas ini untuk Claude. Anda tidak pernah memperluasnya sendiri.
• tool_use: panggilan Claude ke alat yang ditemukan. Jalankan dan kembalikan tool_result persis seperti dalam penggunaan alat standar.

API secara otomatis memperluas blok tool_reference menjadi definisi alat lengkap sebelum menampilkannya ke Claude. Anda tidak perlu menangani perluasan ini sendiri, selama Anda menyediakan semua definisi alat yang cocok dalam parameter tools.



Melanjutkan percakapan

Pada permintaan berikutnya, teruskan kembali konten asisten tanpa perubahan, termasuk blok server_tool_use dan tool_search_tool_result. Tambahkan tool_result Anda untuk alat yang ditemukan dalam pesan pengguna, dan kirim array tools yang sama: alat pencarian ditambah setiap definisi yang ditangguhkan. Jangan mengembalikan tool_result untuk ID srvtoolu_...: API menolak permintaan tersebut. API memperluas blok tool_reference di seluruh riwayat percakapan, sehingga Claude dapat menggunakan kembali alat yang ditemukan di giliran berikutnya tanpa mencari ulang. Pencarian yang tidak menemukan apa pun mengembalikan tool_search_tool_search_result dengan array tool_references kosong, bukan error.



Integrasi MCP

Jika alat Anda berasal dari server MCP melalui MCP connector, Anda tidak menyetel defer_loading pada definisi alat individual. Sebagai gantinya, setel sekali pada default_config entri mcp_toolset untuk seluruh server, atau per alat dalam configs-nya. Lihat Konfigurasi toolset MCP.



Implementasi tool search kustom

Anda dapat mengimplementasikan logika tool search Anda sendiri (misalnya, menggunakan embedding 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, biasanya dengan defer_loading: true. Ini memungkinkan Anda menggunakan metode pencarian yang tidak disediakan oleh varian bawaan, seperti pengambilan berbasis embedding, dan API memperluas blok tool_reference yang dikembalikan dengan cara yang sama.

Untuk contoh lengkap menggunakan embedding, lihat resep tool search dengan embedding.



Penanganan error



Error HTTP (status 400)

Error ini mencegah API memproses permintaan:

Semua alat ditangguhkan:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "At least one tool must have defer_loading=false. All tools cannot be deferred."
  }
}

Definisi alat hilang:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Tool reference 'unknown_tool' not found in available tools"
  }
}



Error hasil alat (status 200)

Ketika operasi tool search gagal selama eksekusi, API mengembalikan respons 200 dengan error di dalam body:

{
  "type": "tool_search_tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "tool_search_tool_result_error",
    "error_code": "invalid_tool_input",
    "error_message": "Invalid regular expression pattern: missing ) at position 1"
  }
}

Field error_code memiliki empat nilai yang mungkin:

• invalid_tool_input: input pencarian tidak valid, misalnya pola regex yang salah bentuk atau pola yang melebihi batas 200 karakter
• unavailable: pencarian tidak dapat berjalan, misalnya karena waktu habis atau layanan tidak tersedia
• too_many_requests: batas laju terlampaui untuk operasi tool search
• execution_time_exceeded: pencarian melebihi batas waktu eksekusinya



Kesalahan umum



Caching prompt

Untuk cara defer_loading mempertahankan caching prompt, lihat Penggunaan alat dengan caching prompt.

Alat dengan defer_loading: true tidak dapat juga membawa cache_control: API mengembalikan 400. Letakkan breakpoint cache pada alat non-deferred.



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 pattern streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"pattern\":\"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.



Batasan dan praktik terbaik



Batasan

• Maksimum alat yang ditangguhkan: 10.000 alat dengan defer_loading: true per permintaan
• Hasil pencarian: setiap pencarian mengembalikan hingga 5 alat yang cocok secara default
• Panjang pola dan kueri: maksimum 200 karakter untuk pola regex dan 500 karakter untuk kueri BM25
• Dukungan model: lihat Kompatibilitas model



Kapan menggunakan tool search

Gunakan tool search ketika salah satu dari hal berikut berlaku:

• Anda memiliki 10 alat atau lebih yang tersedia.
• Definisi alat Anda mengonsumsi lebih dari 10k token.
• Akurasi pemilihan alat menurun seiring bertambahnya toolset Anda.
• Anda menggabungkan beberapa server MCP (200+ alat).
• Pustaka alat Anda bertambah seiring waktu.

Pemanggilan alat standar, tanpa tool search, lebih cocok ketika Anda memiliki kurang dari 10 alat, setiap alat digunakan dalam setiap permintaan, atau definisi alat Anda kecil (kurang dari 100 token total).



Tips optimasi

• Pertahankan 3–5 alat yang paling sering Anda gunakan sebagai non-deferred.
• Tulis nama dan deskripsi alat yang jelas dan deskriptif.
• Gunakan namespacing yang konsisten dalam nama alat: beri prefiks berdasarkan layanan atau sumber daya (misalnya, github_, slack_) sehingga satu pencarian mencocokkan seluruh grup.
• Gunakan kata kunci dalam deskripsi yang cocok dengan cara pengguna mendeskripsikan tugas.
• Tambahkan bagian prompt sistem yang mendeskripsikan kategori alat yang tersedia: "Anda dapat mencari alat untuk berinteraksi dengan Slack, GitHub, dan Jira."
• Pantau alat mana yang ditemukan Claude untuk menyempurnakan deskripsi Anda.



Penggunaan

Tool search tidak diukur sebagai alat server terpisah. Objek usage.server_tool_use pada respons tidak memiliki field tool search, dan definisi alat yang dimuat oleh pencarian ke dalam konteks dihitung sebagai input_tokens seperti definisi alat lainnya.



Langkah selanjutnya