Alat pencarian alat

Alat pencarian alat memungkinkan Claude untuk bekerja dengan ratusan atau ribuan alat dengan secara dinamis menemukan dan memuat mereka sesuai permintaan. Alih-alih memuat semua definisi alat ke jendela konteks di awal, Claude mencari katalog alat Anda (termasuk nama alat, deskripsi, nama argumen, dan deskripsi argumen) dan memuat hanya alat yang dibutuhkannya.

Pendekatan ini menyelesaikan dua masalah yang berkembang pesat seiring dengan skala perpustakaan alat:

• Konteks bloat: Definisi alat menghabiskan anggaran konteks Anda dengan cepat. Pengaturan multi-server yang khas (GitHub, Slack, Sentry, Grafana, Splunk) dapat mengonsumsi ~55k token dalam definisi sebelum Claude melakukan pekerjaan apa pun. Pencarian alat biasanya mengurangi ini lebih dari 85%, memuat hanya 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 Anda melampaui 30–50 alat yang tersedia. Dengan menampilkan serangkaian alat yang relevan dan terfokus sesuai permintaan, pencarian alat menjaga akurasi pemilihan tetap tinggi bahkan di seluruh ribuan alat.

Meskipun ini disediakan sebagai alat sisi server, Anda juga dapat menerapkan fungsionalitas pencarian alat sisi klien Anda sendiri. Lihat Implementasi pencarian alat khusus untuk detail.

Anda juga dapat menerapkan pencarian alat sisi klien dengan mengembalikan blok tool_reference dari implementasi pencarian Anda sendiri.

Cara kerja pencarian alat

Ada dua varian pencarian alat:

• 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

Ketika 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 alat Anda
2. Anda menyediakan semua definisi alat dengan defer_loading: true untuk alat yang tidak boleh dimuat segera
3. Claude awalnya hanya melihat alat pencarian alat dan alat non-deferred apa pun
4. Ketika Claude membutuhkan alat tambahan, ia mencari menggunakan alat pencarian alat
5. API mengembalikan 3-5 blok tool_reference paling relevan
6. Referensi ini secara otomatis diperluas menjadi definisi alat lengkap
7. Claude memilih dari alat yang ditemukan dan menginvokasinya

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

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
}

Poin kunci:

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

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

Cara penundaan bekerja secara internal: Alat yang ditangguhkan tidak disertakan dalam awalan system-prompt. Ketika model menemukan alat yang ditangguhkan melalui pencarian alat, definisi alat ditambahkan secara inline sebagai blok tool_reference dalam percakapan. Awalan tidak tersentuh, sehingga caching prompt dipertahankan. Tata bahasa untuk mode ketat dibangun dari set alat lengkap, jadi defer_loading dan mode ketat bersusun tanpa kompilasi ulang tata bahasa.

Format respons

Ketika Claude menggunakan alat pencarian alat, respons mencakup jenis 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 Claude menginvokan alat pencarian alat
• tool_search_tool_result: Berisi hasil pencarian dengan objek tool_search_tool_search_result bersarang
• tool_references: Array objek tool_reference yang menunjuk ke alat yang ditemukan
• tool_use: Claude menginvokan alat yang ditemukan

Blok tool_reference secara otomatis diperluas menjadi definisi alat lengkap sebelum ditampilkan kepada Claude. Anda tidak perlu menangani ekspansi 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 Konektor MCP.

Implementasi pencarian alat khusus

Anda dapat menerapkan logika pencarian alat Anda sendiri (misalnya, menggunakan embeddings atau pencarian semantik) dengan mengembalikan blok tool_reference dari alat khusus. Ketika Claude memanggil alat pencarian khusus 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 pencarian alat.

Untuk contoh lengkap menggunakan embeddings, lihat cookbook pencarian alat dengan embeddings.

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 yang hilang:

{
  "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 dalam badan:

{
  "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 pencarian alat
• invalid_pattern: Pola regex yang salah format
• pattern_too_long: Pola melebihi batas 200 karakter
• unavailable: Layanan pencarian alat sementara tidak tersedia

Kesalahan umum

Caching prompt

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

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

Streaming

Dengan streaming diaktifkan, Anda akan menerima acara pencarian alat sebagai bagian dari aliran:

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 alat pencarian alat dalam Messages Batches API. Operasi pencarian alat melalui Messages Batches API dihargai sama dengan operasi dalam permintaan Messages API reguler.

Retensi data

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

Untuk kelayakan ZDR di semua fitur, lihat API dan retensi data.

Batas dan praktik terbaik

Batas

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

Kapan menggunakan pencarian alat

Kasus penggunaan yang baik:

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

Kapan pemanggilan alat tradisional mungkin lebih baik:

• Kurang dari 10 alat total
• Semua alat sering digunakan dalam setiap permintaan
• Definisi alat sangat kecil (<100 token 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 konsisten dalam nama alat: awali dengan 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: "Anda dapat mencari alat untuk berinteraksi dengan Slack, GitHub, dan Jira"
• Pantau alat mana yang Claude temukan untuk menyempurnakan deskripsi

Penggunaan

Penggunaan alat pencarian alat dilacak dalam objek penggunaan respons:

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

Langkah berikutnya