Praktik terbaik WebMCP

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

Dipublikasikan: 18 Mei 2026

Pernyataan alat WebMCP harus jelas, tanpa perlu developer atau agen melihat output dan mencoba lagi. Baik Anda menggunakan Imperative API atau Declarative API, ikuti praktik terbaik berikut:

  • Sebelum membangun, buat strategi alat.
  • Gunakan bahasa yang jelas dan HTML semantik.
  • Desain skema dan tangani input.
  • Membangun alat yang andal.
  • Uji dan debug.

Membuat strategi alat

Sama seperti yang akan Anda lakukan untuk aplikasi software apa pun, langkah pertama Anda adalah merencanakan strategi alat:

  • Setiap alat harus terdiri dari satu fungsi. Misalnya, salah satu alat dapat mengarahkan pengguna ke jenis formulir tertentu, sedangkan alat lain harus mencocokkan kolom input dengan informasi pengguna. Berhati-hatilah agar tidak membuat alat yang tumpang-tindih, karena agen mungkin bingung tentang alat yang harus digunakan. Tanyakan pada diri Anda: dapatkah saya mencakup beberapa tugas dengan fungsi yang sama?
  • Mengelola pendaftaran alat. Daftarkan alat saat berguna dalam status halaman tertentu, lalu batalkan pendaftaran saat alat tidak lagi dapat digunakan.
    • Imperative API: Anda dapat mengelola pendaftaran secara dinamis dengan registerTool.
    • Declarative API: Anda dapat mengelola pendaftaran secara dinamis dengan menambahkan atau menghapus atribut alat pada formulir, dengan toolname dan tooldescription.
  • Mengurangi kompleksitas: Untuk sebagian besar aplikasi, pendaftaran statis harus menjadi pendekatan default.
  • Percayai agen untuk menyelesaikan tugas. Daripada menulis petunjuk yang kaku atau negatif, asumsikan agen dapat memahami apa yang diperlukan untuk menyelesaikan tugas, daripada mengharapkan agen mengelola alur langkah yang tepat.

Meskipun tidak ada jumlah maksimum alat yang diizinkan, setiap alat menggunakan sebagian jendela konteks dan menambah waktu penyelesaian. Makin banyak alat yang Anda berikan dan makin banyak alat yang tumpang-tindih, makin sulit bagi agen untuk memilih dengan benar. Bereksperimen untuk menentukan apa yang tepat untuk aplikasi Anda.

Hal ini membantu Anda membuat alat individual, tanpa tujuan yang tumpang-tindih, dan mengelola kapan alat ini tersedia.

Menggunakan bahasa yang jelas dan kode semantik

Gunakan bahasa yang jelas dan langsung untuk memberi nama alat dan mendeskripsikan penggunaannya. Hal ini membantu agen menemukan apa yang mereka butuhkan, memahami apa yang mereka temukan, dan menggunakan informasi tersebut seperti yang diharapkan developer.

Saat menulis nama alat, bedakan eksekusi dari inisiasi, dan gunakan kata kerja yang menjelaskan secara persis apa yang terjadi. Misalnya, create-event adalah alat untuk pembuatan peristiwa langsung, tetapi start-event-creation-process adalah alat yang mengarahkan pengguna ke formulir untuk membuat peristiwa.

Deskripsi yang jelas harus menjelaskan fungsi alat dan kapan sebaiknya digunakan. Mengandalkan bahasa dan preferensi positif, bukan bahasa negatif, seperti batasan.

Larangan

"Jangan gunakan alat ini untuk cuaca."

Batasan harus tersirat dalam deskripsi yang ditulis dengan baik.
Anjuran

"Alat ini dapat membuat acara kalender, yang dijadwalkan untuk tanggal dan waktu tertentu."

Meminimalkan komputasi kognitif

Sama seperti Anda harus meminimalkan beban kognitif bagi manusia yang menyelesaikan tugas kompleks, Anda juga harus meminimalkan komputasi kognitif untuk model:

  • Menerima input pengguna mentah. Hindari meminta agen melakukan perhitungan matematika atau mengubah string input. Misalnya, jika pengguna mengatakan, "11.00 hingga 15.00", alat ini akan menerimanya sebagai string. Jangan meminta model untuk menghitung selisih waktu dalam menit antara kedua waktu tersebut.
  • Deklarasikan jenis tertentu untuk parameter, seperti string, angka, atau enum.
  • Jelaskan alasan Anda membuat pilihan tertentu. Pilihan yang Anda buat harus dapat dipahami dengan sendirinya. Alasan membantu agen membuat pilihan yang lebih baik. Misalnya, jika Anda menjalankan toko e-commerce, nyatakan jenis pengiriman dengan bahasa alami, bukan menggunakan ID yang ambigu: shipping="Express", bukan shipping_id=1.

Memprioritaskan keandalan

Agen dan manusia mendapatkan manfaat dari alat yang berperilaku sesuai harapan:

  • Menetapkan kegagalan yang lancar untuk batas laju. Alat harus memungkinkan pengulangan yang wajar, seperti untuk perbandingan harga. Jika alat dibatasi lajunya, tampilkan error yang bermakna atau sarankan pengguna untuk melakukan tugas secara manual.
  • Perbarui status antarmuka setelah fungsi selesai. Agen dapat mengandalkan antarmuka untuk merencanakan langkah berikutnya, sementara fungsi mungkin memerlukan waktu lebih lama untuk diselesaikan daripada pemuatan antarmuka. Agen harus mengonfirmasi bahwa fungsi telah selesai setelah antarmuka diperbarui, atau meminta pembaruan lagi.
  • Validasi secara ketat dalam kode, secara longgar dalam skema. Batasan dan pengujian harus digunakan untuk fungsi dan kode yang memiliki logika biner. Meskipun batasan skema dapat membantu, batasan tersebut tidak dijamin. Tambahkan kesalahan deskriptif ke kode fungsi Anda agar model dapat mengoreksi diri sendiri dan mencoba lagi dengan parameter baru yang valid.

Pengujian dan proses debug evaluasi

Buat pengujian evaluasi dan sediakan alat Anda untuk proses debug. Tidak seperti pengujian unit deterministik, evaluasi tidak dapat dikodekan secara permanen, karena output dapat mengambil bentuk yang tidak terduga.

  • Mendefinisikan masalah. Anda dapat menyusun masalah Anda seperti kontrak API, termasuk jenis input, format output, dan batasan tambahan.
  • Tentukan hasil dasar dan hasil ideal. Terutama dengan input teks, penting untuk memahami jenis hasil yang dapat memberi Anda output yang Anda harapkan.
  • Tentukan cara output akan dievaluasi. Anda kemungkinan mengidentifikasi dan mengukur hasil kualitatif yang subjektif berdasarkan kualitas input, kegunaan, dan kemampuan untuk menyelesaikan tugas berikutnya. Ada sejumlah teknik yang dapat Anda gunakan untuk mengevaluasi output, termasuk pemeriksaan berbasis kode untuk output berbasis aturan (batas karakter) dan LLM-as-a-judge.

Hindari menambahkan aturan sempit untuk menambal masalah pada model tertentu. Misalnya, jika Anda menyertakan kolom pilihan untuk sebutan kehormatan, model dapat membuat pilihan yang salah. Daripada menambahkan aturan sempit untuk memperbaiki masalah ini, abstraksikan dan sesuaikan alat Anda. Sebaiknya tetapkan kolom ini sebagai opsional. Kemudian, minta agen untuk menanyakan kepada pengguna pilihan mana yang paling sesuai, untuk memastikan pengguna puas dengan hasilnya.

Berinteraksi dan memberikan masukan

WebMCP sedang dalam tahap pembahasan aktif dan dapat berubah sewaktu-waktu. Jika Anda mencoba API ini dan memiliki masukan, kami ingin mendengarnya.