Desain Skema Alat: Bantu Agen AI Memilih Endpoint yang Tepat

Anda memberi agen dua alat: updateUser dan deactivateUser. Sebuah tiket dukungan mengatakan “tutup akun ini.” Agen memanggil deactivateUser. Minggu lalu, tiket yang hampir sama membuatnya memanggil updateUser dengan status: "closed", yang diterima oleh API Anda dan yang berarti sesuatu yang sedikit berbeda di hilir.

Tidak ada yang rusak. Model memilih antara dua opsi yang masuk akal dengan deskripsi yang tidak memberitahunya mana yang berlaku. Pemilihan alat adalah mode kegagalan yang orang salahkan pada model dan perbaiki dalam skema, karena skema adalah satu-satunya hal yang menjadi acuan model.

Panduan ini membahas apa yang sebenarnya dibaca model saat memilih alat, cara menulis nama dan deskripsi yang membedakan, bagaimana desain parameter mengubah tingkat kesalahan, dan cara menguji pemilihan agar perubahan kata tidak merusaknya secara diam-diam. Setelah alat Anda dihasilkan dari spesifikasi, seperti dalam panduan kami tentang mengubah spesifikasi OpenAPI menjadi alat agen, ini menjadi pertanyaan tentang apa yang masuk ke dalam spesifikasi tersebut.

Apidog adalah tempat deskripsi berada jika alat Anda berasal dari definisi API Anda, jadi meningkatkan salah satunya akan meningkatkan dokumen dan alat secara bersamaan.

Apa yang dilihat model

Pada saat memilih, model memiliki percakapan, perintah sistem, dan daftar definisi alat. Setiap definisi adalah nama, deskripsi, dan skema parameter. Model tidak memiliki dokumentasi API Anda, komentar kode Anda, atau pengetahuan "turun-temurun" bahwa updateUser adalah warisan.

Itu berarti setiap disambiguasi harus ditulis ke dalam definisi itu sendiri. Baik panduan pemanggilan fungsi OpenAI maupun dokumentasi penggunaan alat Anthropic menyampaikan poin yang sama: deskripsi adalah teks yang paling penting dalam seluruh definisi, dan seharusnya bertele-tele daripada ringkas.

Kesalahan pemilihan muncul dalam empat bentuk, dan masing-masing memiliki perbaikan yang berbeda.

Model memilih alat yang serupa ketika dua definisi tumpang tindih. Perbaiki deskripsinya sehingga masing-masing menyatakan kapan tidak menggunakannya. Model tidak memilih apa pun dan menjawab dari memori ketika tidak ada deskripsi yang cocok dengan bahasa tugas. Perbaiki dengan menggunakan kata-kata yang digunakan pengguna Anda. Model memilih alat yang tepat dengan argumen yang salah ketika parameternya ambigu. Perbaiki dengan tipe, enum, dan unit. Model merantai alat dengan buruk ketika urutan penting dan tidak ada yang mengatakannya. Perbaiki dengan menyatakan prasyarat dalam deskripsi.

Namai alat sesuai fungsinya

Nama membawa lebih banyak sinyal daripada yang disarankan panjangnya, karena model membacanya terlebih dahulu.

Gunakan kataKerjaKataBenda (verbNoun), dengan gaya yang sama di seluruh kumpulan alat: createOrder, refundOrder, getOrderStatus. Konsistensi sama pentingnya dengan pilihan individu, karena kumpulan yang mencampur order_create, getOrder, dan refund membuat setiap nama sedikit lebih sulit dibaca.

Spesifiklah tentang objeknya. search adalah nama alat yang buruk. searchCustomersByEmail adalah nama yang baik, dan ini memberi tahu model apa yang dicari dan bagaimana caranya.

Hindari jargon internal. Jika API Anda menyebut pelanggan sebagai "entitas" dan langganan sebagai "instrumen", model tidak akan menghubungkannya dengan tiket yang mengatakan "pelanggan" dan "paket". Namai alat dalam bahasa tugas, bukan bahasa skema.

Jangan pernah menggunakan kembali nama di seluruh konteks. Dua alat bernama list dalam namespace yang berbeda akan menjadi ambigu begitu keduanya muncul dalam satu daftar.

Tulis deskripsi yang membedakan

Deskripsi yang berguna menjawab empat pertanyaan: apa yang dilakukannya, apa yang diubahnya, kapan menggunakannya, dan kapan tidak menggunakannya.

Berikut adalah pasangan yang lemah:

{ "name": "updateUser", "description": "Updates a user." }
{ "name": "deactivateUser", "description": "Deactivates a user." }

Dan pasangan yang benar-benar membedakan:

{
  "name": "updateUser",
  "description": "Updates profile fields on an active user, such as name, email, or timezone. Use for corrections and profile edits requested by the user. Does NOT change account status. To disable an account, use deactivateUser instead. Do not use to close or cancel an account."
}
{
  "name": "deactivateUser",
  "description": "Disables a user account, revoking all sessions and blocking sign-in. Reversible with reactivateUser. Use when a customer asks to close, cancel, pause, or suspend their account. Does NOT delete data. For permanent deletion use deleteUser, which cannot be undone."
}

Empat teknik yang bekerja di sana.

Sebutkan saudaranya. “Gunakan deactivateUser sebagai gantinya” menyelesaikan ambiguitas secara langsung, pada saat model membandingkannya.

Sertakan kosakata pengguna. Kata-kata “tutup”, “batalkan”, “jeda”, dan “tangguhkan” muncul karena itulah kata-kata yang muncul di tiket. Ini adalah suntingan dengan pengembalian tertinggi yang dapat Anda lakukan, dan hampir gratis.

Katakan apa yang tidak dilakukannya. Pernyataan negatif lebih membedakan daripada pernyataan positif, karena klaim positif dari dua alat yang berdekatan cenderung terlihat mirip.

Tandai reversibilitas. Model mempertimbangkan risiko ketika Anda memberitahunya ada risiko. Ini berpasangan dengan pola penegakan dalam postingan kami tentang pelindung agen AI, di mana perlindungan sebenarnya berada.

Panjang tidak masalah. Deskripsi seratus kata yang mencegah satu panggilan salah ke endpoint destruktif itu murah.

Rancang parameter agar argumen yang salah menjadi sulit

Setelah alat yang tepat dipilih, argumen adalah tempat selanjutnya hal-hal salah.

JSON Schema memberi Anda sebagian besar batasan yang Anda perlukan di sini, dan kosakata validasi JSON Schema layak dibaca sekilas untuk kata kunci yang didukung API pemanggil alat Anda.

Gunakan enum di mana pun setnya tertutup. Parameter status yang diketik sebagai string mengundang penemuan. Diketik sebagai enum, ini membatasi model pada nilai-nilai yang diterima API Anda.

"status": {
  "type": "string",
  "enum": ["pending", "paid", "refunded", "cancelled"],
  "description": "Order status. 'cancelled' means never fulfilled; 'refunded' means fulfilled then reversed."
}

Sertakan unit dalam nama. amount ambigu dan model akan menebak dolar atau sen secara tidak konsisten. amount_cents tidak pernah ambigu. Hal yang sama berlaku untuk timeout_seconds, distance_meters, dan duration_ms.

Berikan contoh format tanggal. "description": "Start date in ISO 8601 format, for example 2026-08-26" menghasilkan tanggal yang diformat dengan benar jauh lebih sering daripada “start date” saja.

Jaga agar daftar yang wajib diisi tetap jujur. Menandai semuanya opsional mendorong kegagalan ke runtime; menandai hal-hal yang wajib diisi yang secara masuk akal di-default oleh API membuat model menciptakan nilai. Keduanya umum, dan keduanya muncul sebagai kesalahan validasi yang dibahas dalam postingan kami tentang desain kesalahan API untuk agen.

Pilih flat daripada bersarang. Model yang mengisi {"customer": {"address": {"postal_code": "..."}}} membuat kesalahan struktural yang tidak dibuatnya pada customer_postal_code. Ratakan di batas alat dan rakit kembali di pelaksana Anda.

Pisahkan alat yang kelebihan beban. Alat dengan parameter mode yang mengubah arti setiap bidang lainnya sebenarnya adalah dua alat. Memisahkannya meningkatkan pemilihan dan menyederhanakan kedua skema.

Nyatakan prasyarat dan urutan

Pekerjaan multi-langkah gagal ketika model tidak mengetahui urutannya. Katakan dalam deskripsi alat yang bergantung:

{
  "name": "captureCharge",
  "description": "Captures a previously authorized charge. Requires an authorization_id from authorizeCharge. Call authorizeCharge first if you do not already have one. Cannot capture more than the authorized amount."
}

Dua baris, dan masalah urutan ditangani di tempat model sudah membaca. Ini berlaku untuk seluruh kelas: buat sebelum perbarui, unggah sebelum proses, otorisasi sebelum tangkap. Jika deskripsi langkah yang bergantung tidak menyebutkan langkah sebelumnya, harapkan model akan melewatinya. Di mana urutan mencakup beberapa agen daripada beberapa panggilan, aturan serah terima dalam postingan kami tentang meneruskan konteks antar sub-agen berlaku.

Uji pemilihan seperti perilaku lainnya

Deskripsi adalah kode, dan mereka mengalami regresi. Seseorang memendekkan satu untuk menyesuaikan panduan gaya dan agen mulai memilih endpoint yang salah pada hari Selasa berikutnya.

Bangun suite pemilihan kecil. Dua puluh hingga lima puluh prompt, masing-masing dengan alat yang Anda harapkan. Jalankan, catat alat mana yang dipilih model, dan hanya tegaskan namanya. Argumen bervariasi dari satu eksekusi ke eksekusi lainnya; pilihannya tidak boleh bervariasi. Ini adalah bentuk praktis dari pendekatan dalam panduan kami untuk menguji agen non-deterministik.

Lengkapi dengan kasus-kasus yang paling mungkin rusak:

• Dua alat yang paling mirip dalam kumpulan Anda, dengan prompt yang seharusnya mengarah ke masing-masing.
• Prompt yang menggunakan kosakata pelanggan daripada kosakata API.
• Prompt yang seharusnya tidak cocok dengan apa pun, di mana perilaku yang benar adalah bertanya daripada memaksakan panggilan.
• Alat yang destruktif, di mana pilihan yang salah memiliki biaya nyata.

Jalankan setiap prompt beberapa kali. Alat yang menang empat dari lima kali adalah lemparan koin dalam produksi dan deskripsinya perlu diperbaiki.

Arahkan eksekusi ke mock sehingga uji pemilihan tidak pernah menyentuh data langsung. Postingan kami tentang menjalankan agen terhadap mock daripada produksi mencakup penyiapan, dan Apidog dapat menyediakan mock tersebut dari definisi yang sama tempat alat Anda dihasilkan, yang menjaga skema dan perilaku tetap selaras.

Tiga set yang salah dengan cara yang sama

Set CRUD. Sebuah API mengekspos getUser, listUsers, searchUsers, dan queryUsers, semuanya dihasilkan dari endpoint yang berkembang selama bertahun-tahun. Bagi model, ini adalah empat nama untuk satu ide. Perbaikannya bukan deskripsi yang lebih baik pada keempatnya; melainkan mengekspos salah satunya ke agen dan meninggalkan sisanya dari daftar alat. Kumpulan yang dikurasi mengalahkan kumpulan yang lengkap setiap saat.

Set admin. Alat baca dan alat destruktif berdampingan dengan nada yang sama: getInvoice, voidInvoice, deleteInvoice. Tidak ada dalam teks yang menandakan bahwa dua di antaranya mengakhiri karier. Tambahkan konsekuensinya ke deskripsi, tandai untuk persetujuan, dan pertahankan penegakan di eksekutor daripada mempercayai kata-kata. Pendekatan berlapis ada dalam postingan kami tentang menghentikan agen menghancurkan API Anda.

Set legasi. Dua endpoint melakukan pekerjaan yang sama, satu sudah usang. Spesifikasi masih mencantumkan keduanya, sehingga generator mengeluarkan keduanya, dan agen memilih yang lama sekitar setengah dari waktu. Hapus operasi yang sudah usang dari alat yang dihasilkan atau mulai deskripsinya dengan kata-kata "Tidak digunakan lagi. Gunakan createOrderV2 sebagai gantinya." Model menghargai baris itu ketika di awal, dan mengabaikannya ketika terkubur di akhir.

Deskripsi adalah konfigurasi bersama

Setelah Anda menerima bahwa deskripsi alat mendorong perilaku, pertanyaan berikutnya adalah siapa pemiliknya. Di sebagian besar tim jawabannya tidak disengaja: siapa pun yang menyiapkan agen pertama kali, dalam sebuah file di mesin mereka.

Perlakukan kumpulan alat sebagai artefak bersama, ditinjau seperti antarmuka lainnya. Platform yang dibangun di sekitar pekerjaan agen sering kali memodelkan ini secara langsung. Agen Sharkly adalah konfigurasi tersimpan yang mencakup instruksi, Runtime, Keterampilan, dan repositori, dan membagikannya di Ruang membuat pengaturan kerja satu orang dapat digunakan kembali oleh tim. Nilainya bukan penyimpanan. Ini adalah bahwa perubahan deskripsi menjadi suntingan yang dapat ditinjau yang memengaruhi semua orang, daripada perubahan lokal yang senyap yang membuat agen satu pengembang berperilaku berbeda dari yang lain.

Perhatikan kata-kata yang dibawa pengguna

Kesenjangan yang paling umum adalah kosakata. API Anda mengatakan subscription, pelanggan Anda mengatakan plan, membership, dan billing. API Anda mengatakan deactivate, mereka mengatakan cancel, close, dan turn off.

Kumpulkan bahasa yang sebenarnya. Ambil frasa teratas dari tiket dukungan, log pencarian, atau transkrip eksekusi agen yang gagal, lalu masukkan ke dalam deskripsi alat yang seharusnya cocok. Ini memakan waktu satu jam dan biasanya meningkatkan akurasi pemilihan lebih dari tuning skema apa pun.

Perhatikan juga kegagalannya. Ketika agen tidak memilih apa pun dan menjawab dari pengetahuannya sendiri, itu adalah kesalahan kosakata, bukan kegagalan penalaran. Bahasa tugas tidak pernah tumpang tindih dengan teks alat, sehingga alat tersebut tidak terlihat.

Daftar periksa untuk kumpulan alat

• Nama mengikuti satu konvensi kataKerjaKataBenda dan menamai objek tertentu.
• Setiap deskripsi menyatakan apa yang berubah, kapan menggunakannya, dan kapan tidak menggunakannya.
• Alat yang tumpang tindih secara eksplisit menyebutkan satu sama lain.
• Deskripsi mencakup kata-kata yang sebenarnya digunakan pengguna, bukan hanya istilah internal.
• Tindakan yang destruktif dan tidak dapat dibatalkan disebutkan dalam deskripsi.
• Enum dideklarasikan untuk setiap set tertutup.
• Unit dan format berada di nama atau deskripsi parameter, dengan contoh.
• Daftar yang wajib diisi sesuai dengan apa yang benar-benar diberlakukan oleh API.
• Alat yang bergantung menyebutkan prasyaratnya.
• Suite pemilihan berjalan di CI terhadap mock.

Model melakukan pencocokan pola terhadap teks yang Anda tulis. Ketika ia salah memilih, teks adalah tempat pertama yang harus dicari, dan biasanya satu-satunya tempat yang perlu Anda ubah. Unduh Apidog jika Anda menginginkan deskripsi, mock, dan tes dalam satu proyek.

Pertanyaan yang sering diajukan

Berapa panjang seharusnya deskripsi alat? Cukup panjang untuk menghilangkan ambiguitas, yang biasanya dua hingga lima kalimat. Deskripsi memang memakan konteks, jadi potong yang untuk alat yang tidak ambigu dan gunakan ruang untuk alat yang berdekatan satu sama lain.

Haruskah saya menyertakan contoh dalam deskripsi? Ya untuk format dan unit, di mana contoh menghilangkan seluruh kelas kesalahan. Lewati contoh penggunaan yang panjang, karena memakan konteks dan jarang mengubah pemilihan.

Apakah lebih baik memiliki banyak alat sempit atau beberapa yang fleksibel? Alat sempit, sampai batas tertentu. Setiap alat memilih lebih andal karena melakukan satu hal. Lebih dari beberapa lusin, daftar itu sendiri menjadi masalah dan Anda memfilter atau mengambil, seperti yang dibahas dalam postingan kami tentang menghasilkan alat agen dari OpenAPI.

Bisakah saya memperbaiki pemilihan dalam prompt sistem sebagai gantinya? Sebagian, dan itu adalah solusi sementara yang masuk akal untuk satu atau dua kebingungan yang diketahui. Ini tidak berskala, karena prompt dibagikan di semua alat sementara deskripsi menyertai alat yang membutuhkannya.

Bagaimana jika model terus menciptakan nilai parameter? Batasi tipenya, tambahkan enum, dan katakan dalam deskripsi bahwa nilai harus berasal dari panggilan sebelumnya daripada dibuat. Jika masih terjadi, validasi di pembungkus dan kembalikan kesalahan yang menyebutkan nilai yang diizinkan.

Apakah aturan ini berlaku untuk server MCP juga? Ya. Server MCP mengekspos nama, deskripsi, dan skema dalam bentuk yang sama, sehingga aturan penulisan kata yang sama berlaku. Penjelasan kami tentang apa itu MCP mencakup protokol itu sendiri.