Gevşek şemalar ve belirsiz tool tanımları: yapay zeka ajanlarını rayından çıkaran iki MCP başarısızlığı

Aynı gün dev.to'da yayımlanan, ikisi de Jeff PDC imzalı ve MCP sunucuları kurmayla ilgili bir dizinin parçası olan iki yazı, yapay zeka ajanları gerçek araçları çağırmaya başladığında ortaya çıkan iki başarısızlık modunu ayrıntılarıyla inceliyor: geçersiz argümanların geçişine izin verecek kadar gevşek input şemaları ve modelin yanlış işlemi seçmesine yol açacak kadar belirsiz tanımlar. Her iki durumda da sunucu kağıt üzerinde doğru görünür — şema doğrulanır, izinler yerindedir — buna karşılık ajan, bir model sınırlılığı olarak yanlış teşhis edilmesi kolay biçimlerde yanlış davranır.

Gevşek şemalar doğrulamayı upstream API'ye itiyor

Bir MCP aracı argümanlarını JSON Schema olarak bildirir ve bu şema, model bir çağrı oluştururken okuduğu sözleşmedir. İlk yazıya göre araçlar çoğu zaman aceleyle sarılıyor: her parametre string olarak tiplendirilmiş, zorunlu alanlar işaretlenmemiş ya da gerçek bir şekil yerine tiplendirilmemiş tek bir object kullanılmış. Ajan tesadüfen kabul edilebilir argümanlar gönderdiği için mutlu yol hâlâ çalışır. Başarısızlık daha sonra gelir: bir istek bir alanı atlar ya da API'nin ISO tarih string'i beklediği yerde sayı gönderir ve hata, upstream servisten gelen bir 400 olarak döner — onu tetikleyen koddan çok uzakta.

Temel sav, modelin kendisine hiç verilmemiş kısıtlamalara uyunca sayamayacağıdır. Önerilen şema disiplini şunları içerir:

• her yerde string yerine açık tipler
• zorunlu alanları adlandıran bir required dizisi
• kabul edilen kümenin kapalı olduğu her yerde enum'lar, örneğin para birimi kodları
• minimum, pattern veya maxLength gibi upstream API'yi yansıtan kısıtlar
• false olarak ayarlanmış additionalProperties ve catch-all yerine tiplendirilmiş iç içe objeler

Yazıya göre doğrulama ayrıca araç sınırında çalışmalı; böylece geçersiz argümanlar, ihlal edilen kısıtı adlandıran yerel ve yapılandırılmış bir hatayla hızlıca başarısız olur — modelin üzerinde harekete geçebileceği bir şey, tam bir gidiş-dönüşe mal olan anlaşılmaz bir upstream hatası yerine. API nihai otorite olmayı sürdürür; yerel kontroller yalnızca hataları ucuzlatır. Şemayı sıkılaştırmak ajanın yapabileceklerini azaltmaz, çünkü yalnızca upstream API'nin zaten uyguladığı sınırları dayatır.

Belirsiz tanımlar araç seçimini tahmine dönüştürüyor

İkinci yazı aynı kökten gelen bir başarısızlığı ele alıyor. Model araçlar arasında seçim yaparken adlarını ve tanımlarını okur; dolayısıyla bir sunucu her işlemi doğru şekilde açığa çıkarabilir ve yine de başarısız olabilir, çünkü seçim sunucunun yayımladığı metnin gücüne göre gerçekleşir.

Yazıya göre üç anti-pattern öne çıkıyor: metod adını yankılamak (getInvoice'in "Get invoice" olarak tanımlanması), birbirine neredeyse özdeş işlemler arasında tek bir cümleyi tekrarlamak (list ile search) ve ilgili eylemleri ayıran sınırı atlamak (create ile update, draft ile publish).

Gözlemlenebilir belirtiler: kullanıcı bir faturayı güncellemesini isterken ajan createInvoice'e uzanır ya da bir list endpoint'i seçip farklı bir kaynağa ait bir ID geçirir. Yazı bunun bir yetenek sorunu değil, bir sinyal sorunu olduğunu vurguluyor — tanımları düzeltmeden modeli keskinleştirmek, yalnızca tahmini daha kendinden emin hale getirir.

Öneri, bir tanımın bir-iki cümlede üç soruyu yanıtlaması gerektiği: araç ne yapar, ne zaman kullanılır ve ne zaman kullanılmaz. "Kullanmayın" ifadesi en yüksek değerli bölüm olarak adlandırılıyor, çünkü modele yanlış çağrıyı önleyen olumsuz koşulu verir. Yazı ayrıca bir gözden geçirme döngüsü öneriyor: her tanımı adı olmadan okuyup kullanım senaryosunun hâlâ net olup olmadığını kontrol edin; birbirine neredeyse özdeş her çift için ayırt edici koşulu yazın; daha önce başarısız olan belirsiz istekleri yeniden oynatın; ve iki işlem gerçekten ayırt edilemiyorsa, ikisini birden açığa çıkarmak yerine birleştirmeyi düşünün.

İki yazı da OpenAPI spec'ten üretimde buluşuyor

El ile bakılan wrapper'lar sapmanın geri sızdığı yerdir, ikisi yazı da bunu savunuyor. MCP aracı ve input şeması bir OpenAPI belgesinden üretildiğinde ve CI'da sözleşme doğrulaması yapıldığında, zorunlu hale gelen bir alan ya da yeni bir değer kazanan enum otomatik olarak yayılır. Tanımlar da aynı şekilde MCP katmanında ayrı ayrı bakım yapmak yerine spec içinde zenginleştirilmelidir; böylece modelin seçim yaptığı metin, gerçek davranışa ve parametrelere bağlı kalır.

Neden önemli

Her iki başarısızlık modu da geleneksel entegrasyon testlerine görünmezdir: araç çalışır, şema doğrulanır, ajanın izni vardır ve yine de yanlış davranır. Bu yazıların yakaladığı şey, ajana yönelik araçlar için şema ve tanımın dokümantasyon cilası olmadığı — modelin üzerinde akıl yürüttüğü arayüz olduğudur. Bunları düzeltmek model değiştirmeye kıyasla ucuzdur ve yanlış araç başarısızlık modu gerçek yan etkilere sahiptir: create ile update'i ya da cancel ile refund'u karıştırmak, hiçbir retry döngüsünün geri alamayacağı bir hatadır. Daha fazla servis MCP sunucularıyla sarıldıkça, araç tanımlarına birinci sınıf sözleşme eserleri gibi davranmak, ara sıra tahmin eden bir ajan ile istenileni güvenilir biçimde yapan bir ajan arasındaki fark olabilir.