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 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 bertumbuhnya 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 melampaui 30–50 alat yang tersedia. Karena tool search memuat hanya sekumpulan alat relevan yang terfokus sesuai permintaan, akurasi pemilihan tetap tinggi bahkan di seluruh ribuan alat.

Untuk model yang mendukung tool search, 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 pencarian alat

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 mengatur 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; Claude dapat mengatur 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 tool search tool dan dua alat deferred:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-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 deferred

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 deferred. 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 mengatur defer_loading: true pada tool search tool itu sendiri.
• Jaga agar 3–5 alat yang paling sering digunakan tetap non-deferred sehingga Claude dapat memanggilnya tanpa mencari terlebih dahulu.

Toolset computer use dan browser use (computer_toolset_20260801 dan browser_toolset_20260801) mengambil defer_loading per alat anggota di dalam objek configs entri, bukan pada entri itu sendiri; permintaan yang mengaturnya di tingkat entri akan ditolak. Karena toolset menunda dan memperluas sebagai satu unit, defer_loading harus menghasilkan nilai yang sama pada setiap anggota yang diaktifkan, dan ketika Claude menemukan toolset melalui pencarian, setiap anggota yang diaktifkan dimuat sekaligus. Lihat Client toolsets untuk format configs.

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

Secara internal, API mengecualikan alat deferred dari prefiks prompt sistem. Ketika Claude menemukan alat deferred 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 dipertahankan. Tata bahasa untuk mode ketat (aturan yang membatasi output panggilan alat agar cocok dengan skema Anda) dibangun dari toolset lengkap, sehingga defer_loading dan mode ketat disusun tanpa kompilasi ulang tata bahasa.

Format respons

Ketika Claude menggunakan tool search tool, 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 tool search tool. Pencarian berjalan di server Anthropic. Jangan pernah mengembalikan tool_result untuk ID srvtoolu_...-nya. input menyimpan pencarian (pattern untuk varian regex, query untuk BM25) dan dapat menyertakan limit opsional, sebuah integer 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 apa adanya dalam riwayat pesan.
• tool_references: sebuah 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 konten asisten kembali 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 deferred. 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 cocok dengan apa pun mengembalikan tool_search_tool_search_result dengan array tool_references kosong, bukan kesalahan.

Integrasi MCP

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

Implementasi pencarian alat 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 with embeddings.

Penanganan kesalahan

Kesalahan HTTP (status 400)

Kesalahan ini mencegah API memproses permintaan:

Semua alat deferred:

{
  "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"
  }
}

Kesalahan hasil alat (status 200)

Ketika operasi tool search gagal selama eksekusi, API mengembalikan respons 200 dengan kesalahan di 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 melampaui batas waktu eksekusinya

Kesalahan umum

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

{
  "name": "my_tool",
  "description": "Full description here",
  "input_schema": {
    "type": "object"
  },
  "defer_loading": true
}

Caching prompt

Untuk mempelajari bagaimana 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

• Alat deferred maksimum: 10.000 alat dengan defer_loading: true per permintaan
• Hasil pencarian: setiap pencarian mengembalikan hingga 5 alat yang cocok secara default; Claude dapat mengatur limit dalam input pencariannya ke integer mana 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 tool search ketika salah satu dari berikut ini berlaku:

• Anda memiliki 10 atau lebih alat yang tersedia.
• Definisi alat Anda mengonsumsi lebih dari 10k token.
• Akurasi pemilihan alat menurun seiring bertumbuhnya toolset Anda.
• Anda mengagregasi beberapa server MCP (200+ alat).
• Pustaka alat Anda bertumbuh 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

• Jaga agar 3–5 alat yang paling sering digunakan tetap 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 cocok dengan 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 dari respons tidak memiliki field tool search, dan definisi alat yang dimuat pencarian ke dalam konteks dihitung sebagai token input seperti definisi alat lainnya.

Langkah selanjutnya