Alat pencarian alat

Alat pencarian alat (tool search tool) memungkinkan Claude bekerja dengan ratusan atau ribuan alat dengan menemukan dan memuatnya sesuai permintaan. Alih-alih memuat semua definisi alat ke dalam "context window" (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 menghabiskan ~55k token dalam definisi sebelum Claude melakukan pekerjaan apa pun. Pencarian alat biasanya mengurangi ini lebih dari 85 persen, dengan 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 pencarian alat hanya memuat sekumpulan alat relevan yang terfokus sesuai permintaan, akurasi pemilihan tetap tinggi bahkan di antara ribuan alat.

Untuk model yang mendukung pencarian alat, lihat Kompatibilitas model.

Pencarian alat berjalan sebagai alat sisi server, tetapi Anda juga dapat mengimplementasikan pencarian alat sisi klien Anda sendiri. Lihat Implementasi pencarian alat kustom untuk detailnya.



Kompatibilitas model

Kedua varian pencarian alat tersedia pada model-model berikut:

Claude Opus 4.1 dan model-model sebelumnya tidak mendukung alat pencarian alat.



Cara kerja pencarian alat

Ada dua varian pencarian alat:

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

Saat Anda mengaktifkan alat pencarian alat:

1. Anda menyertakan alat pencarian alat (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 menetapkan defer_loading: true pada alat yang tidak boleh dimuat di awal. Setidaknya satu alat, biasanya alat pencarian alat itu sendiri, harus tetap tidak ditangguhkan.
3. Pada awalnya, konteks Claude hanya berisi alat pencarian alat dan alat apa pun yang tidak ditangguhkan.
4. Ketika Claude membutuhkan alat tambahan, Claude mencari menggunakan alat pencarian alat.
5. API menjalankan pencarian dan mengembalikan alat yang cocok sebagai blok tool_reference (hingga 5 secara default; Claude dapat menetapkan limit dalam input pencariannya).
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 alat pencarian alat dan dua alat yang ditangguhkan:

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 terima kembali dan apa yang harus dikirim selanjutnya.



Definisi alat

Alat pencarian alat 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 menetapkan defer_loading: true pada alat pencarian alat itu sendiri.
• Biarkan 3–5 alat yang paling sering Anda gunakan tidak ditangguhkan sehingga Claude dapat memanggilnya tanpa mencari terlebih dahulu.

Toolset computer use dan browser use (computer_toolset_20260801 dan browser_toolset_20260801) menerima defer_loading per alat anggota di dalam objek configs milik entri, bukan pada entri itu sendiri; permintaan yang menetapkannya di tingkat entri akan ditolak. Karena sebuah toolset ditangguhkan dan diperluas sebagai satu kesatuan, defer_loading harus bernilai sama pada setiap anggota yang diaktifkan, dan ketika Claude menemukan toolset melalui pencarian, setiap anggota yang diaktifkan dimuat sekaligus. Lihat Toolset klien untuk format configs.

Kedua varian pencarian alat (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 pencarian alat, API menambahkan blok tool_reference secara inline dalam percakapan, lalu memperluasnya menjadi definisi alat lengkap sebelum meneruskannya ke Claude. Prefiks tidak tersentuh, sehingga "prompt caching" (caching prompt) tetap terjaga. Grammar untuk mode strict (aturan yang membatasi output panggilan alat agar sesuai dengan skema Anda) dibangun dari toolset lengkap, sehingga defer_loading dan mode strict dapat digabungkan tanpa kompilasi ulang grammar.



Format respons

Ketika Claude menggunakan alat pencarian alat, respons menyertakan jenis 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",
        "limit": 10
      }
    },
    {
      "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 alat pencarian alat. Pencarian berjalan di server Anthropic. Jangan pernah mengembalikan tool_result untuk ID srvtoolu_...-nya. input berisi pencarian (pattern untuk varian regex, query untuk BM25) dan dapat menyertakan limit opsional, bilangan bulat dari 1 hingga 10.000 yang membatasi berapa banyak alat yang cocok yang dikembalikan pencarian (default: 5).
• tool_search_tool_result: hasil pencarian, dalam objek tool_search_tool_search_result bersarang. Simpan dalam riwayat pesan apa adanya.
• tool_references: array objek tool_reference yang menunjuk ke alat yang ditemukan. API memperluasnya 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 akan menolak permintaan tersebut. API memperluas blok tool_reference di seluruh riwayat percakapan, sehingga Claude dapat menggunakan kembali alat yang ditemukan pada giliran berikutnya tanpa mencari ulang. Pencarian yang tidak mencocokkan 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 konektor MCP, Anda tidak menetapkan defer_loading pada definisi alat individual. Sebagai gantinya, tetapkan sekali pada default_config milik entri mcp_toolset untuk seluruh server, atau per alat dalam configs-nya. Lihat Konfigurasi toolset MCP.



Implementasi pencarian alat kustom

Anda dapat mengimplementasikan logika pencarian alat 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 pencarian alat 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 tidak ada:

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



Error hasil alat (status 200)

Ketika operasi pencarian alat 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 dijalankan, misalnya karena waktu habis atau layanan tidak tersedia
• too_many_requests: "rate limit" (batas laju) terlampaui untuk operasi pencarian alat
• execution_time_exceeded: pencarian melebihi batas waktu eksekusinya



Kesalahan umum



Caching prompt

Untuk cara defer_loading menjaga 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 yang tidak ditangguhkan.



Streaming

Dengan streaming diaktifkan, Anda akan menerima event pencarian alat 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 alat pencarian alat dalam Messages Batches API.



Batas dan praktik terbaik



Batas

• 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; Claude dapat menetapkan limit dalam input pencariannya ke bilangan bulat apa pun dari 1 hingga 10.000
• Panjang pola dan kueri: maksimum 200 karakter untuk pola regex dan 500 karakter untuk kueri BM25
• Dukungan model: lihat Kompatibilitas model



Kapan menggunakan pencarian alat

Gunakan pencarian alat ketika salah satu dari hal berikut berlaku:

• Anda memiliki 10 alat atau lebih yang tersedia.
• Definisi alat Anda menghabiskan 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 pencarian alat, 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

• Biarkan 3–5 alat yang paling sering Anda gunakan tidak ditangguhkan.
• Tulis nama dan deskripsi alat yang jelas dan deskriptif.
• Gunakan namespace 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 sesuai dengan cara pengguna mendeskripsikan tugas.
• Tambahkan bagian prompt sistem 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 Anda.



Penggunaan

Pencarian alat tidak diukur sebagai alat server terpisah. Objek usage.server_tool_use pada respons tidak memiliki field pencarian alat, dan definisi alat yang dimuat pencarian ke dalam konteks dihitung sebagai token input seperti definisi alat lainnya.



Langkah selanjutnya