Best Practices Tool Calling Agent: Kenapa Agent-Mu Memilih Tool yang Salah

Best Practices Tool Calling Agent: Kenapa Agent-Mu Memilih Tool yang Salah

Best practices tool calling agent adalah satu-satunya pembatas antara demo yang berjalan mulus dan agent yang diam-diam memanggil tool yang salah di production. Tim engineering Anthropic mengukur bahwa satu deskripsi yang ditulis ulang memangkas satu hasil tool dari 206 token menjadi 72, dan Claude Code kini membatasi keras setiap respons tool di 25.000 token karena kebocoran itu nyata. Agent-mu gagal dengan empat cara: tool salah, argumen salah, loop tak terkendali, dan token yang terbuang. Masing-masing punya perbaikan yang bisa kamu rilis minggu ini.

Poin penting:

• Tool calling agent gagal dengan tepat empat cara: tool salah, argumen salah, loop tak terkendali, dan kebocoran token.
• Deskripsi tool adalah satu-satunya instruksi yang dilihat model saat pemilihan, jadi deskripsi memperbaiki sebagian besar panggilan tool yang salah.
• Skema yang datar, berbentuk sesuai tugas, dengan input tervalidasi menghilangkan sebagian besar kegagalan argumen yang salah.
• Respons tool yang ringkas dan loop evaluasi di setiap perubahan menjaga biaya token dan regresi tetap terukur.

Kenapa tool calling agent gagal di production?

Tool calling agent gagal dengan empat cara: model memilih tool yang salah, menulis argumen yang salah, berputar dalam loop tak terkendali, atau membocorkan token lewat respons yang gemuk. Setiap kegagalan menyerang langkah yang berbeda dalam loop panggilan, jadi urutan perbaikan itu penting. Mulailah dari pemilihan, karena pilihan tool yang salah meracuni setiap langkah setelahnya.

Resep lengkapnya sekilas:

Kerjakan sesuai urutan ini. Praktik 1 dan 2 cuma butuh satu sore dan menyingkirkan sebagian besar kegagalan tool salah dan argumen salah yang kamu lihat hari ini. Deskripsi tool itu bukan dokumentasi. Ia adalah satu-satunya instruksi yang didapat model saat pemilihan.

Fase 1: Desain tool yang benar-benar bisa dipakai model

Peningkatan keandalan termurah dalam tool calling agent ada di definisi tool-mu, bukan di prompt atau pilihan modelmu. Model tidak pernah membaca docs API atau README-mu. Ia melihat sebuah nama, sebuah string deskripsi, dan sebuah skema JSON, lalu memutuskan hanya dari tiga hal itu. Benarkan ketiganya dan akurasi pemilihan bergerak sebelum kamu menyentuh hal lain.

Praktik 1: Tulis deskripsi yang bisa ditindaklanjuti model

Tulis deskripsi tool sebagai instruksi untuk model, bukan sebagai dokumentasi API. Deskripsi yang memuaskan developer manusia ("REST wrapper untuk endpoint users") tidak memberi model apa pun untuk diputuskan. Panduan engineering Anthropic tentang menulis tools dan best practices definisi tool mereka sama-sama mendorong pola yang sama: katakan kapan harus memakai tool ini, apa yang dikembalikannya, dan kapan TIDAK boleh memakainya.

{
  "name": "get_user",
  "description": "Fetches a user profile. Use ONLY when you already have a user_id. Do NOT use to search or list users; call search_users instead. Returns name, email, plan. Errors if user_id is not a valid UUID."
}

bandingkan dengan versi yang dirilis kebanyakan tim:

{
  "name": "get_user",
  "description": "Gets a user."
}

Dua aturan mengerjakan sebagian besar pekerjaan di sini. Pertama, beri nama parameter sehingga maknanya tidak ambigu: user_id, jangan pernah user atau id, karena user mengundang model untuk mengoper nama atau email di tempat yang seharusnya UUID. Kedua, nyatakan pengecualian secara eksplisit. "Do NOT use to search users" mencegah lebih banyak panggilan tool yang salah daripada deskripsi positif sebanyak apa pun, karena model jauh lebih sering keliru membedakan tool yang tumpang tindih daripada salah paham pada tool tunggal yang batasnya jelas. Untuk mekanisme level provider tentang bagaimana definisi-definisi ini sampai ke API OpenAI, Anthropic, dan Google, lihat panduan function calling multi-provider kami.

Praktik 2: Jaga skema tetap datar dan berbentuk sesuai tugas

Jaga skema input tetap datar, dengan setiap field yang benar-benar dibutuhkan tugas dan tidak ada yang tidak. Objek bersarang dengan cabang opsional adalah tempat kegagalan argumen salah berkembang biak: model harus menyimpulkan struktur yang tidak pernah ia lihat contohnya. Panduan function calling OpenAI menerima JSON Schema sembarang, tetapi permisif tidak sama dengan andal.

{
  "name": "create_ticket",
  "parameters": {
    "type": "object",
    "properties": {
      "ticket": {
        "type": "object",
        "properties": {
          "details": {
            "type": "object",
            "properties": {
              "title": { "type": "string" },
              "meta": { "type": "object" }
            }
          }
        }
      }
    }
  }
}

Ratakan sesuai tugasnya:

{
  "name": "create_ticket",
  "parameters": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "priority": { "type": "string", "enum": ["low", "medium", "high"] },
      "assignee_id": { "type": "string" }
    },
    "required": ["title", "priority"]
  }
}

Enum mengalahkan teks bebas untuk field apa pun dengan kumpulan nilai yang terbatas. Array required mengalahkan segalanya yang opsional. Jika model hampir selalu membutuhkan sebuah field, jadikan ia required di skema tool meskipun API-mu menyebutnya opsional. Kamu tidak sedang mencerminkan API-mu. Kamu sedang merancang permukaan yang bisa diisi dengan benar oleh satu model spesifik.

Fase 2: Kelola kumpulan tool, bukan cuma tool-nya satu per satu

Kualitas tool individual tidak lagi cukup begitu sebuah agent membawa lebih dari segenggam tool, karena kesalahan pemilihan tumbuh seiring ukuran daftar yang dibaca model.

Praktik 3: Bungkus urutan API multi-langkah menjadi tool atomik

Ringkas urutan panggilan API yang tetap menjadi satu tool atomik. Postingan engineering Anthropic memakai schedule_event dan get_customer_context sebagai contohnya: satu panggilan yang menuntaskan seluruh pekerjaan mengalahkan tiga panggilan yang harus dirangkai agent dengan benar setiap saat. Setiap mata rantai dalam sebuah rantai adalah satu giliran lagi di mana model bisa macet, retry dengan keliru, atau berputar.

# What the agent does WITHOUT an atomic tool: 3 calls, 3 chances to fail
calendar = call_tool("list_calendars", {})
free = call_tool("find_free_slot", {"calendar_id": calendar["items"][0]["id"], "duration": 30})
call_tool("create_event", {"calendar_id": calendar["items"][0]["id"], "start": free["start"]})

# One atomic tool: the sequence lives in your code, not the model's head
call_tool("schedule_event", {"duration": 30, "attendees": ["[email protected]"]})

Aturan praktisnya: jika model harus selalu memanggil B setelah A, maka A dan B adalah satu tool yang memakai dua kostum.

Praktik 4: Namespace, pangkas, dan saring tool secara dinamis

Beri namespace pada setiap nama tool dan tunjukkan ke setiap agent hanya subset yang dibutuhkan tugasnya saat ini. Nama generik bertabrakan begitu kamu menghubungkan dua integrasi. Bayangkan sebuah agent yang tersambung ke dua server MCP yang keduanya mengekspos tool bernama search: dua kata kerja identik, tanpa cara untuk membedakannya. Anthropic mendokumentasikan peningkatan eval yang terukur dari namespacing prefiks:

Pemangkasan sama pentingnya dengan penamaan. Agent dukungan tidak perlu tool billing-nya dimuat sementara ia menjawab pertanyaan soal kata sandi. Pola planner-worker, di mana sebuah planner merutekan tugas ke worker yang hanya memuat tool yang relevan, adalah perbaikan standarnya; how-to pemuatan tool dinamis LangGraph memandu implementasinya. Berapa banyak tool itu terlalu banyak? Perlakukan 5-10 per agent sebagai kisaran kerja, bukan hukum: akurasi menurun seiring bertambahnya daftar, dan obatnya adalah penyaringan, bukan model yang lebih besar. Jika kamu sedang memilih lapisan routing dan penyaringan itu sendiri, bandingkan pilihanmu dalam rangkuman kami soal library function calling terbaik.

Fase 3: Kontrol apa yang kembali dan apa yang keluar

Loop berjalan dua arah, dan kebanyakan tim hanya merekayasa separuh yang keluar. Apa yang dikembalikan tool-mu menentukan berapa banyak context window yang selamat sampai giliran berikutnya, dan apa yang ditolak validasimu menentukan apakah model belajar dari kesalahannya atau mengulanginya.

Praktik 5: Kembalikan hasil yang ringkas dan bersinyal tinggi

Kembalikan hasil terkecil yang bisa ditindaklanjuti model, dengan identifier yang bisa dibaca manusia alih-alih ID mentah. Postingan engineering Anthropic mendokumentasikan sebuah tool yang hasil default-nya berjalan 206 token; sebuah pengaturan response_format yang ringkas memangkas hasil yang sama menjadi 72 token, kira-kira sepertiga ukurannya. Kalikan itu dengan puluhan panggilan per tugas dan ia menentukan apakah agent-mu selesai sama sekali.

// Before: 206 tokens (shape per Anthropic's documented example)
{
  "status": "success",
  "data": {
    "id": "8f14e45f-ceea-3f9c-a2f3-90c1b5e0a7d2",
    "object": "task", "created_at": "2026-07-02T09:14:00Z",
    "updated_at": "2026-07-11T16:40:12Z", "completed_at": null,
    "assignee": {"id": "c9a1...f2", "object": "user"},
    "projects": [{"id": "b7d3...91", "object": "project"}],
    "permalink": "https://app.asana.com/0/.../f"
  }
}

// After: 72 tokens
{ "task": "Fix login redirect", "assignee": "Dana Kim", "project": "Web App", "due": "2026-07-20" }

Dua detail lagi dari sumber yang sama: Anthropic mendukung enum response_format (detailed versus concise) pada definisi tool, jadi kamu bisa mendeklarasikan bentuk yang kamu inginkan alih-alih mengurai air bahnya. Dan Claude Code membatasi respons tool di 25.000 token, sebuah langit-langit keras yang memotong hasil yang membengkak bagaimanapun juga. Anthropic juga melaporkan, sebagai temuan mereka, bahwa meresolusi UUID menjadi nama semantik mengurangi halusinasi retrieval secara terukur, itulah sebabnya payload "sesudah" di atas menulis "Dana Kim" dan bukan c9a1...f2. Respons yang gemuk juga masalah biaya; lihat panduan kami untuk memangkas biaya API LLM demi gambaran lengkapnya.

Praktik 6: Validasi setiap panggilan dan buat error yang mengajari model

Validasi setiap panggilan tool di sisi server dan kembalikan error yang berisi perbaikannya. Tulisan Martin Fowler tentang function calling membingkainya dengan blak-blakan: jangan pernah percaya output model. Ia akan mengoper string di tempat yang seharusnya enum dan mengarang ID yang tidak ada.

def create_ticket(args):
    if args.get("priority") not in {"low", "medium", "high"}:
        return {"error": f"priority must be one of: low, medium, high. Got '{args.get('priority')}'. Pass priority='medium' for normal issues."}
    if not is_valid_uuid(args.get("assignee_id")):
        return {"error": "assignee_id must be a UUID. Call list_team_members to get valid IDs, then retry."}
    return db.create_ticket(**args)

String error adalah seluruh permainannya. Bandingkan:

# Unhelpful: the model retries the same bad call
{"error": "invalid input"}

# Helpful: the model knows exactly what to change
{"error": "priority must be one of: low, medium, high. Got 'urgent'. Use 'high'."}

Setiap error validasi yang dikembalikan tool-mu adalah prompt yang sedang kamu tulis untuk percobaan model selanjutnya. Error yang menamai constraint dan menunjuk ke tool korektif mengubah loop retry menjadi pemulihan sekali jalan. Ini juga lini pertahanan keamanan pertamamu; panduan guardrails LLM kami membahasnya secara mendalam.

Fase 4: Bagaimana membuatnya aman, lalu membuatnya terukur?

Keamanan dan pengukuran adalah fase yang sama karena aksi destruktif tanpa gerbang dan regresi tanpa pengukuran sama-sama muncul sebagai insiden yang tidak kamu lihat kedatangannya. Gerbangkan aksi yang tidak bisa dibatalkan, lalu instrumentasikan segalanya sehingga perubahan tool berikutnya adalah keputusan dengan bukti di belakangnya, bukan harapan.

Praktik 7: Gerbangkan aksi destruktif di belakang manusia

Pisahkan tool baca dari tool tulis dan pasang gerbang konfirmasi manusia pada apa pun yang destruktif. Anotasi tool spesifikasi MCP ada tepat untuk ini: destructiveHint menandai tool yang melakukan pembaruan destruktif, dan openWorldHint menandai tool yang menyentuh sistem eksternal, sehingga klien bisa meminta konfirmasi sebelum mengeksekusi. Pakai mereka.

Mode kegagalannya bukan hipotesis. Laurent Kubaski mendokumentasikan sebuah kasus, dalam tulisan tool-calling Juli 2025-nya dengan laporan asli yang tertaut, di mana seorang pengguna meminta Copilot di Excel untuk beraksi pada baris 4 dan agent malah beraksi pada baris 8. Tidak ada gerbang konfirmasi yang berdiri di antara baris yang salah dan penulisan itu. Perbaikannya adalah pola yang AWS dokumentasikan untuk Bedrock Agents: agent menyiapkan aksi, mengembalikannya untuk persetujuan, dan mengeksekusi hanya setelah manusia mengonfirmasi. Cursor melakukan hal yang sama untuk pengeditan file. Batasi kredensial menjadi read-only di tempat membaca saja sudah cukup untuk tugasnya, dan perlakukan gerbang konfirmasi sebagai bagian dari permukaan injeksimu, topik panduan pencegahan prompt injection kami.

Praktik 8: Jalankan loop evaluasi di setiap perubahan tool

Jalankan suite evaluasi kecil sebelum dan sesudah setiap perubahan tool, dan baca metriknya dalam urutan tetap. Panduan optimisasi Paragon mengusulkan kerangka empat metrik yang layak diadopsi:

Cookbook evaluasi tool Anthropic, yang dibangun di atas eval MCP Slack dan Asana sungguhan, menunjukkan seperti apa tugas eval yang baik dan yang buruk:

# Weak: vague, many valid paths, impossible to score
"Use the Asana tools to organize some work."

# Strong: one correct tool, checkable arguments, binary outcome
"Create a task titled 'Renew TLS cert' in project 'Infra' assigned to [email protected], due 2026-08-15. Expect exactly one create_task call with those four fields."

Interpretasi kami, diberi label demikian: angka-angka yang dipublikasikan memberimu urutan pengerjaan. periksa ketepatan tool terlebih dahulu, karena pengukuran Anthropic sendiri menunjukkan perubahan deskripsi dan penamaan menggerakkannya secara langsung (penulisan ulang 206-ke-72 token, temuan halusinasi UUID-ke-nama), dan sisakan efisiensi tugas untuk terakhir, karena ia sebagian besar mencerminkan kegagalan yang sudah ditangkap tiga metrik pertama. Untuk suite pemula, desain 15-30 tugas, dua atau tiga per tool, masing-masing dengan satu panggilan yang diharapkan dan kondisi lulus biner. Ukuran itu cukup untuk menangkap regresi dari penulisan ulang deskripsi tanpa seminggu pelabelan, dan kami membaca setup Slack dan Asana cookbook itu sebagai bukti bahwa suite sekecil ini memang titik awal yang dimaksud, bukan jalan pintas. Mekanika yang lebih dalam ada di panduan kami untuk mengevaluasi AI agent di production, dan jika hasil eval-mu bilang tool-nya sendiri baik-baik saja tetapi orkestrasinya tidak, itulah saatnya meninjau ulang pilihan framework-mu terhadap framework AI agent terbaik.

Tool calling agent vs MCP: apa bedanya?

MCP adalah standar transport dan registri, bukan lapisan keandalan, jadi kedelapan praktik yang sama tetap berlaku apakah tool-mu datang lewat MCP atau didefinisikan inline. Tool calling native adalah kontrak model-provider: bagaimana model memancarkan tool_call dan membaca tool_result. MCP menstandardisasi bagaimana tool sampai ke model; ia tidak melakukan apa pun soal apakah model memilih yang benar.

Server MCP yang mengekspos tool bernama search dengan deskripsi "searches things" gagal secara identik dengan fungsi inline yang didefinisikan dengan cara yang sama. Perbaiki definisinya, baru khawatirkan transportnya. Panduan Model Context Protocol kami mencakup sisi protokol dari ujung ke ujung.

Cara Techsy menerapkan delapan praktik ini

Pada setiap pembangunan agent klien, kami menegakkan tiga di antaranya sebelum apa pun yang lain dirilis: deskripsi yang ditulis sebagai instruksi (Praktik 1), gerbang validasi pada setiap tool tulis (Praktik 6), dan suite eval yang berjalan sebelum deploy, bukan setelah insiden (Praktik 8). Tiga itu mencakup panggilan tool salah, panggilan argumen salah, dan regresi yang memperkenalkan ulang keduanya, yang merupakan tempat setiap insiden agent production yang pernah kami debug bermula. Lima praktik lainnya menyusul seiring tumbuhnya agent. Jika agent-mu sudah lewat tahap demo dan masih memilih tool yang salah, dapatkan konsultasi gratis dan kami akan memberitahumu yang mana dari kedelapannya yang harus diperbaiki lebih dulu.

Tentang Penulis

Mert Batur adalah Co-Founder Techsy.io, tempat timnya merilis AI agent, sistem otomasi, dan pipeline voice/SDR untuk klien B2B. Ia menulis tentang tumpukan tooling LLM yang benar-benar dipakai tim Techsy di production. Terhubung di LinkedIn.

Pertanyaan yang Sering Diajukan

Apa itu tool calling agent?

Tool calling agent adalah mekanisme di mana sebuah LLM memutuskan untuk memanggil fungsi eksternal, memancarkan tool_call terstruktur, dan menunggu kodemu mengembalikan tool_result yang bisa ia nalar. Inilah yang mengubah model chat menjadi agent yang bisa meng-query database, memanggil API, dan mengambil tindakan: model memilih tool dan argumennya, eksekutormu menjalankannya.

Bagaimana cara kerja loop tool calling agent?

Loop ini punya lima langkah: permintaan pengguna sampai ke model, model memilih sebuah tool dan menulis tool_call, eksekutormu menjalankannya, sebuah tool_result kembali ke model, dan model menjawab atau mengeluarkan panggilan lain. Siklus itu berulang sampai tugasnya selesai. Empat mode kegagalan dalam panduan ini masing-masing hidup di langkah spesifik dari loop ini.

Kenapa agent-ku memilih tool yang salah?

Biasanya karena dua tool tumpang tindih dan deskripsinya tidak mengatakan yang mana yang mana. Model memilih hanya dari nama dan deskripsi, jadi "gets a user" versus "finds users" terbaca saling tertukar. Perbaiki dengan baris pengecualian ("do NOT use to search"), nama ber-namespace, dan lebih sedikit tool dalam konteks. Uji empat model Kubaski menunjukkan bahkan model kuat pun salah rute pada daftar yang ambigu.

Bagaimana cara memaksa agent tool calling menstrukturkan output-nya?

Batasi skemanya, bukan prompt-nya. Pakai enum untuk field yang terbatas, array required untuk apa pun yang dibutuhkan tugas, dan objek datar di atas yang bersarang. Untuk jawaban akhir alih-alih panggilan tool, fitur provider seperti structured outputs OpenAI dan mode tool-choice Anthropic memaksa bentuk tertentu. Panduan structured outputs kami mencakup kedua jalur dengan kode.

Tool calling agent vs MCP: apa bedanya?

Tool calling native adalah kontrak antara kodemu dan satu model provider: format pesan tool_call dan tool_result. MCP adalah lapisan protokol yang menstandardisasi bagaimana tool ditemukan dan dikirim ke klien kompatibel mana pun. MCP mengubah pemipaannya, bukan keandalannya. Tool yang dideskripsikan dengan buruk gagal dengan cara yang sama lewat jalur mana pun, seperti yang dijelaskan panduan Model Context Protocol kami.

Berapa banyak tool itu terlalu banyak untuk LLM agent?

Perlakukan 5-10 tool per agent sebagai kisaran kerja, bukan hukum. Akurasi pemilihan menurun seiring tumbuhnya daftar yang terlihat, terutama ketika nama atau deskripsi tumpang tindih. Obatnya bukan model yang lebih besar melainkan penyaringan: muat hanya subset yang dibutuhkan tugas saat ini, memakai pemisahan planner-worker. Beri namespace pada segalanya sehingga dua integrasi tidak pernah sama-sama mengekspos search polos.

Apa model terbaik untuk tool calling?

Tidak ada jawaban tunggal, dan benchmark yang dipublikasikan cepat usang di bidang ini. Model frontier dari OpenAI, Anthropic, dan Google semuanya melewati tugas tool-use dasar, sementara model lebih kecil yang dipasangkan dengan tool yang dirancang baik sering menuntaskan tugas hampir sama seringnya dengan sebagian kecil biaya token. Bangun suite eval 15-30 tugas dari Praktik 8 dan uji kandidat terhadap tool-mu sendiri.

Bagaimana cara memangkas biaya token dari tool calling?

Potong apa yang kembali. Kembalikan hasil yang ringkas dan bersinyal tinggi alih-alih payload API mentah: Anthropic mendokumentasikan pemangkasan 206-ke-72 token dari satu perubahan response_format. Resolusi UUID menjadi nama, buang field yang tidak pernah dipakai model, dan ingat bahwa setiap hasil tool masuk kembali ke context window pada setiap giliran berikutnya. Lebih sedikit panggilan, lewat tool atomik, menyingkirkan seluruh hasil dari tagihan.

Bagaimana cara mengevaluasi kualitas tool calling?

Skor empat metrik secara berurutan: ketepatan tool (tool yang benar?), akurasi input (argumen valid?), penuntasan tugas (tujuan tercapai?), dan efisiensi tugas (jumlah token dan panggilan?). Tulis 15-30 tugas, masing-masing mengharapkan satu panggilan spesifik dengan argumen yang bisa diperiksa dan kondisi lulus biner. Jalankan suite sebelum dan sesudah setiap perubahan tool sehingga penulisan ulang deskripsi tidak pernah rilis tanpa terukur.

Kesimpulan

Diagnosis dulu sebelum mengoptimalkan. Agent-mu memilih tool yang salah karena satu dari empat alasan, dan tiga dari delapan praktik di atas, deskripsi, skema datar, dan penyaringan, memperbaiki kegagalan pemilihan yang mendorong sebagian besar insiden production. Mulailah dari sana, karena biayanya cuma satu sore dan merekalah alasan masalah ini bisa diperbaiki sama sekali. Jaga error validasi tetap informatif, gerbangkan apa pun yang destruktif di belakang manusia, dan jalankan loop evaluasi di setiap perubahan sehingga kamu mengukur sebelum mengganti model. Masalah tool yang salah bukan masalah model. Ia masalah desain tool, dan kamulah pemilik desainnya.