Praktik terbaik WebMCP

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

Dipublikasikan: 18 Mei 2026

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 mem-build, buat strategi alat.
  • Gunakan bahasa yang jelas dan HTML semantik.
  • Desain skema dan tangani input.
  • Buat alat yang andal.
  • Uji dan debug.

Membuat strategi alat

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

  • Setiap alat harus terdiri dari satu fungsi. Misalnya, 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 akan digunakan. Tanyakan pada diri Anda: dapatkah saya mencakup beberapa tugas dengan fungsi yang sama?
  • Kelola pendaftaran alat. Daftarkan alat saat alat tersebut berguna dalam status halaman tertentu, lalu batalkan pendaftaran saat alat tidak lagi dapat digunakan.
    • Imperative API: Anda dapat mengelola pendaftaran secara dinamis dengan registerTool dan unregisterTool.
    • API Deklaratif: Anda dapat mengelola pendaftaran secara dinamis dengan menambahkan atau menghapus atribut alat pada formulir, dengan toolName dan toolDescription.
  • Kurangi kompleksitas: Untuk sebagian besar aplikasi, pendaftaran statis harus menjadi pendekatan default.
  • Percayakan pada agen untuk menyelesaikan tugas*. Daripada menulis petunjuk yang kaku atau negatif, asumsikan agen dapat memahami apa yang diperlukan untuk menyelesaikan tugas, bukan 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. Semakin banyak alat yang Anda berikan dan semakin banyak alat yang tumpang-tindih, semakin sulit bagi agen untuk memilih dengan benar. Bereksperimenlah untuk menentukan hal yang tepat bagi aplikasi Anda.

Hal ini membantu Anda mem-build 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 menjelaskan 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 dengan tepat apa yang terjadi. Misalnya, create-event adalah alat untuk pembuatan acara langsung, tetapi start-event-creation-process adalah alat yang mengalihkan pengguna ke formulir untuk membuat acara.

Deskripsi yang jelas harus menjelaskan fungsi alat dan kapan sebaiknya digunakan. Gunakan 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:

  • Terima input pengguna mentah. Hindari meminta agen untuk melakukan perhitungan matematika atau mengubah string input. Misalnya, jika pengguna mengatakan, "11:00 hingga 15:00", alat harus menerima ini sebagai string. Hindari meminta model untuk menghitung menit antara waktu ini.
  • Deklarasikan jenis tertentu untuk parameter, seperti string, angka, atau enum.
  • Jelaskan alasan Anda membuat pilihan tertentu. Pilihan yang Anda buat harus dapat dijelaskan sendiri. Alasan membantu agen membuat pilihan yang lebih baik. Misalnya, jika Anda menjalankan toko e-commerce, deklarasikan jenis pengiriman dengan bahasa alami, bukan menggunakan ID yang ambigu: shipping="Express" dan bukan shipping_id=1.

Memprioritaskan keandalan

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

  • Tetapkan kegagalan yang baik untuk batas frekuensi. Alat harus memungkinkan pengulangan yang wajar, seperti untuk perbandingan harga. Jika alat dibatasi frekuensinya, tampilkan error yang bermakna atau sarankan pengguna untuk melakukan tugas secara manual.
  • Perbarui status antarmuka setelah fungsi selesai. Agen mungkin 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 error 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.

  • Tentukan masalahnya. Anda dapat menyusun masalah seperti kontrak API, termasuk jenis input, format output, dan batasan tambahan apa pun.
  • Tentukan nilai dasar dan hasil ideal. Terutama dengan input teks, penting untuk memahami jenis hasil yang dapat memberi Anda output yang diharapkan.
  • Tentukan cara output akan dievaluasi. Anda mungkin mengidentifikasi dan mengukur hasil subjektif dan kualitatif 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 dengan model tertentu. Misalnya, jika Anda menyertakan kolom pilihan untuk gelar kehormatan, model mungkin membuat pilihan yang salah. Daripada menambahkan aturan sempit untuk menambal masalah ini, abstrakkan dan sesuaikan alat Anda. Anda mungkin akan mendapatkan hasil terbaik dengan menetapkan kolom ini sebagai opsional. Kemudian, minta agen untuk bertanya kepada pengguna pilihan mana yang masuk akal, untuk memastikan pengguna puas dengan hasilnya.

Berinteraksi dan berbagi masukan

WebMCP sedang dalam diskusi aktif dan dapat berubah di masa mendatang. Jika Anda mencoba API ini dan memiliki masukan, kami ingin mendengarnya.