AI Ajanlarının Gerçek Sorunu Kod Değil, Açıklamalar: MCP Dünyasını Sarsacak Araştırma

Yeni akademik araştırma, 856 MCP aracının %97,1'inde kalite problemi bulunduğunu ortaya koyuyor. Tool Description'ların AI ajanlarının doğruluğunu, maliyetini ve karar mekanizmasını nasıl etkilediğini inceliyoruz.

Kodlar Kusursuz Olabilir. Peki Ya Yapay Zekâ Ne Okuyor?

Yazılım geliştirme dünyasında uzun yıllardır performans optimizasyonundan güvenlik açıklarına, kod kalitesinden mimari desenlere kadar sayısız konu tartışılıyor. Ancak üretken yapay zekâ çağının başlamasıyla birlikte gözden kaçan bambaşka bir katman ortaya çıktı.

Bugün artık birçok yazılım doğrudan insanlar tarafından değil, yapay zekâ ajanları tarafından kullanılıyor.

Bir geliştirici yeni bir API yazdığında, onun ilk kullanıcısı çoğu zaman başka bir yazılımcı değil; GPT, Claude, Gemini veya benzeri büyük dil modelleri oluyor.

İşte tam bu noktada kritik bir soru ortaya çıkıyor.

Yapay zekâ gerçekten sizin yazdığınız kodu mu görüyor?

Aslında hayır.

Bir MCP (Model Context Protocol) sunucusuna bağlanan yapay zekâ ajanı çoğu zaman kaynak kodunuzu hiç incelemiyor. Fonksiyonların nasıl çalıştığını bilmiyor. API'nin arkasındaki mimariyi analiz etmiyor.

Karar verirken yalnızca üç bilgiye bakıyor:

• Aracın adı
• Açıklaması (Tool Description)
• Parametre şeması

Başka bir ifadeyle, geliştiricinin çoğu zaman birkaç dakikada yazdığı açıklama metni, yapay zekânın bütün karar mekanizmasını şekillendiriyor.

Yeni yayımlanan akademik çalışma tam da bu görünmeyen probleme ışık tutuyor. Araştırmacılar, bugün hızla büyüyen MCP ekosistemindeki araç açıklamalarının gerçekten ne kadar kaliteli olduğunu ve bunun AI ajanlarının performansını nasıl etkilediğini bilimsel olarak incelemiş durumda. Sonuçlar ise düşündüğümüzden çok daha çarpıcı.

MCP Neden Bu Kadar Önemli Hale Geldi?

Geçtiğimiz yıl boyunca "AI Agent" kavramı yazılım sektörünün en hızlı büyüyen alanlarından biri oldu.

OpenAI, Anthropic, Microsoft, Google ve GitHub gibi şirketler artık yalnızca daha büyük modeller geliştirmiyor; bu modellerin gerçek sistemlerle konuşabileceği ortak standartlar oluşturuyor.

Bu standartlardan en önemlisi ise hiç kuşkusuz Model Context Protocol (MCP).

MCP'nin temel amacı oldukça basit:

Bir yapay zekâ ajanının farklı uygulamalarla aynı dili konuşmasını sağlamak.

Veritabanları...

Git depoları...

CRM sistemleri...

ERP uygulamaları...

Bulut servisleri...

Dosya sistemleri...

Bugün yüzlerce farklı sistem MCP üzerinden AI ajanlarına bağlanabiliyor.

Ancak burada önemli bir tasarım tercihi bulunuyor.

MCP, yapay zekâya kaynak kodu göndermiyor.

Onun yerine her araç için küçük bir "kimlik kartı" gönderiyor.

Bu kartta yalnızca;

• isim,
• açıklama,
• parametre bilgileri

bulunuyor.

Yani AI ajanı için Tool Description, aslında geliştiricinin düşündüğünden çok daha büyük bir anlam taşıyor.

Araştırmanın Çıkış Noktası

Makalenin yazarları oldukça basit görünen ama bugüne kadar kimsenin sistematik olarak cevaplamadığı bir soru soruyor:

"Tool Description gerçekten iyi yazılmazsa ne olur?"

İlk bakışta bu soru önemsiz gibi gelebilir.

Sonuçta birçok geliştirici açıklama alanını birkaç cümleyle geçiştiriyor.

Hatta bazı açık kaynak projelerde açıklama kısmı yalnızca tek satırdan oluşuyor.

Ancak araştırmacılar bunun aslında AI ajanlarının davranışını doğrudan etkileyen kritik bir mühendislik problemi olduğunu öne sürüyor.

Çünkü büyük dil modeli;

• hangi aracı kullanacağına,
• hangi parametreyi göndereceğine,
• başka bir araca ihtiyaç duyup duymadığına,

tamamen bu açıklamaları okuyarak karar veriyor.

Dolayısıyla eksik yazılmış birkaç cümle, onlarca gereksiz araç çağrısına veya tamamen yanlış sonuçlara neden olabiliyor.

856 Araçlık Dev Bir İnceleme

Bu çalışmayı değerli yapan nokta yalnızca fikri değil.

Araştırmacılar teorik öneriler sunmak yerine gerçek dünyadaki MCP ekosistemini analiz etmiş.

İncelenen veri seti:

• 103 farklı MCP sunucusu
• 856 farklı araç

Bu ölçek, bugüne kadar yayımlanan en kapsamlı MCP kalite analizlerinden biri olma özelliğini taşıyor.

Üstelik çalışma yalnızca açık kaynak projeleri değil, GitHub, Microsoft, PayPal ve Anthropic gibi resmi MCP sunucularını da kapsıyor.

Yani sonuçlar yalnızca amatör geliştiricileri değil, sektörün en büyük oyuncularını da ilgilendiriyor.

Sonuçlar Beklenenden Çok Daha Kötü

Araştırmanın ilk bulgusu gerçekten sarsıcı.

İncelenen Tool Description'ların %97,1'i en az bir kalite problemi içeriyor.

Başka bir ifadeyle;

Bugün kullandığımız MCP araçlarının neredeyse tamamında yapay zekâyı yanlış yönlendirebilecek açıklama eksiklikleri bulunuyor.

Araştırmacılar bununla da yetinmemiş.

Altı farklı kalite kriteri tanımlayarak her açıklamayı puanlamışlar.

En büyük problem ise oldukça ilginç.

Araçların %56'sı kendi amacını bile yeterince açık ifade edemiyor.

Yani yapay zekâ çoğu zaman yanlış karar vermiyor.

Sadece yeterince iyi yönlendirilmiyor.

Tool Description Artık Dokümantasyon Değil, Prompt'un Kendisi

Yazılım geliştirme dünyasında yıllardır dokümantasyon ikinci planda görüldü.

Kod çalışıyorsa açıklamaların eksik olması çoğu zaman büyük bir problem oluşturmadı. Çünkü dokümantasyonun hedef kitlesi insandı. Deneyimli bir geliştirici gerektiğinde kaynak kodu açıp ne olduğunu anlayabiliyordu.

Ancak üretken yapay zekâ ile birlikte bu paradigma değişmeye başladı.

Artık kodun ilk okuyucusu çoğu zaman bir insan değil.

Bir büyük dil modeli.

Ve büyük dil modelleri insanlar gibi davranmıyor.

Bir geliştirici gerektiğinde fonksiyonun içine girip mantığı çözebilir.

Bir AI ajanı ise bunu yapamaz.

O yalnızca kendisine verilen bağlam kadarını bilir.

İşte MCP'nin en kritik noktası burada ortaya çıkıyor.

Model;

• fonksiyonu çalıştırmadan önce
• API dökümantasyonunu incelemeden önce
• kaynak kodunu görmeden önce

yalnızca Tool Description'ı okuyor.

Bu nedenle araştırmacılar oldukça önemli bir tanım yapıyor:

Tool Description yalnızca açıklama değildir.

Aynı zamanda yapay zekâ için bir prompt görevi görür.

Bu bakış açısı MCP ekosistemini tamamen değiştirebilecek kadar önemli. Çünkü artık Tool Description yazmak teknik dokümantasyon işi değil, doğrudan Prompt Engineering disiplininin bir parçası haline geliyor.

Araştırmacılar Kaliteyi İlk Kez Ölçülebilir Hale Getiriyor

Bugüne kadar "iyi Tool Description nasıl yazılır?" sorusunun net bir cevabı yoktu.

Resmî dokümanlarda çeşitli öneriler bulunuyordu.

Topluluk forumlarında tavsiyeler vardı.

Fakat bunların hiçbiri bilimsel değildi.

Bu çalışma ise ilk kez kaliteyi ölçülebilir hâle getiriyor.

Araştırmacılar iyi bir Tool Description'ın altı temel bileşenden oluştuğunu belirliyor:

• Amacı açıkça anlatması
• Hangi durumda kullanılacağını açıklaması
• Kullanım sınırlarını belirtmesi
• Parametreleri ayrıntılı açıklaması
• Yeterince kapsamlı olması
• Örnek kullanım içermesi

Her bileşen beş puan üzerinden değerlendiriliyor.

Üç puanın altına düşen her alan ise bir "Tool Description Smell" olarak sınıflandırılıyor.

Bu yaklaşım oldukça dikkat çekici.

Çünkü yazılım mühendisliğinde yıllardır kullanılan "Code Smell" kavramı ilk kez MCP açıklamalarına uygulanmış oluyor.

%97,1 Ne Anlama Geliyor?

Makalenin en dikkat çekici bulgusu şu:

İncelenen açıklamaların %97,1'i en az bir kalite problemi içeriyor.

Bu oran ilk bakışta inanılmaz görünüyor.

Ancak biraz düşününce şaşırtıcı değil.

Bugün GitHub üzerindeki birçok MCP projesine baktığınızda Tool Description bölümü çoğunlukla birkaç satırdan oluşuyor.

Örneğin;

Retrieves stock data.

veya

Searches repository.

gibi son derece genel ifadeler oldukça yaygın.

Bir insan bunların ne yaptığını tahmin edebilir.

Fakat büyük dil modeli için bu açıklamalar çoğu zaman yeterli değil.

Model;

• hangi durumda bu aracı kullanacağını,
• hangi parametreyi göndereceğini,
• başka bir araca ihtiyaç olup olmadığını

çıkarım yapmak zorunda kalıyor.

İşte araştırmanın temel problemi tam olarak burada başlıyor.

Başarı Artıyor Ama Maliyet de Artıyor

Araştırmanın ikinci bölümü daha da ilginç.

Araştırmacılar mevcut Tool Description'ları yeniden yazıyor.

Eksik alanları tamamlıyor.

Daha ayrıntılı açıklamalar oluşturuyor.

Ardından aynı görevleri yeniden çalıştırıyor.

Sonuç gerçekten dikkat çekici.

Görev başarı oranı 5,85 puan artıyor.

Ara hedeflerin başarı oranı ise yaklaşık %15 yükseliyor.

İlk bakışta her şey mükemmel görünüyor.

Ancak burada beklenmeyen bir yan etki ortaya çıkıyor.

AI ajanları aynı görevi tamamlamak için yaklaşık %67 daha fazla işlem adımı gerçekleştiriyor.

Yani daha iyi açıklamalar daha doğru sonuç veriyor.

Ama bunun karşılığında;

• daha fazla düşünme,
• daha fazla araç çağrısı,
• daha fazla token,
• daha fazla API maliyeti

oluşuyor.

İşte makalenin en önemli katkısı burada.

Çünkü bugüne kadar çoğu kişi "daha ayrıntılı açıklama her zaman daha iyidir" varsayımıyla hareket ediyordu.

Bu çalışma ise bunun her zaman doğru olmadığını gösteriyor.

Doğruluk ile Maliyet Arasında Yeni Bir Denge

AI sistemlerinde artık yeni bir optimizasyon problemi var.

Eskiden yalnızca doğruluk önemliydi.

Bugün ise üç farklı değişken aynı anda optimize edilmeye çalışılıyor:

• Doğruluk
• Hız
• Token maliyeti

Tool Description bu üç değişkeni aynı anda etkileyen yeni bir parametreye dönüşüyor.

Çok kısa yazarsanız model yanlış karar verebilir.

Çok uzun yazarsanız bağlam penceresini gereksiz yere doldurabilirsiniz.

Dolayısıyla geleceğin en iyi Tool Description'ı;

en uzun açıklama değil, en fazla bilgi yoğunluğunu en az kelimeyle sunan açıklama olacak.

Bu da Prompt Engineering'in yeni bir alt disiplini olarak görülebilir.

OpenAI, Anthropic ve Diğerleri İçin Ne Anlama Geliyor?

Bu araştırmanın etkisi yalnızca akademik dünyayla sınırlı değil.

Önümüzdeki dönemde büyük AI platformlarının bu sonuçlardan etkilenmesi oldukça muhtemel.

Örneğin Anthropic, MCP'nin geliştiricisi olduğu için Tool Description standartlarını daha ayrıntılı hâle getirebilir.

OpenAI ise ChatGPT Agent ve Codex tarafında daha sıkı Tool Description doğrulama mekanizmaları geliştirebilir.

Cursor ve GitHub Copilot gibi geliştirme araçları ise yalnızca kod üretmekle kalmayıp, araç açıklamalarını da otomatik iyileştiren sistemler sunabilir.

Hatta yakın gelecekte IDE'lerde şu tür uyarılar görmek şaşırtıcı olmayacaktır:

"Bu Tool Description yapay zekâ tarafından yanlış yorumlanabilir."

Tıpkı bugün kod analiz araçlarının yaptığı gibi.

Kurumsal Şirketler İçin En Büyük Ders

Kurumsal ekiplerin önemli bir kısmı hâlâ MCP araçlarını klasik API mantığıyla geliştiriyor.

Fonksiyon doğru çalışıyorsa iş tamamlandı diye düşünülüyor.

Oysa AI çağında yeni bir teslim kriteri daha ortaya çıkıyor:

Yapay zekâ bu aracı doğru anlayabiliyor mu?

Bu soru artık kod inceleme süreçlerinin bir parçası olmak zorunda.

Çünkü gelecekte yalnızca çalışan API'ler değil, AI tarafından doğru anlaşılabilen API'ler rekabet avantajı sağlayacak.

Bu Makale Aslında Neyi Değiştiriyor?

Yapay zekâ alanında her hafta yüzlerce yeni araştırma yayımlanıyor.

Bunların büyük kısmı mevcut modelleri biraz daha hızlı çalıştırmayı, biraz daha doğru sonuç üretmeyi veya yeni bir benchmark'ta birkaç puan daha yüksek skor almayı hedefliyor.

Bu makale ise farklı bir yerde duruyor.

Çünkü modeli değiştirmiyor.

Prompt'u değiştirmiyor.

Yeni bir algoritma önermiyor.

Bunun yerine çok daha temel bir soruya odaklanıyor:

Yapay zekâya verdiğimiz bilgiler gerçekten yeterince kaliteli mi?

Bu soru ilk bakışta basit görünse de aslında Agentic AI'ın geleceğini şekillendirecek kadar önemli.

Bu Çalışmanın En Büyük Katkısı

Bana göre bu makalenin en büyük başarısı, Tool Description kavramını ilk kez ölçülebilir bir yazılım mühendisliği problemi haline getirmesi.

Bugüne kadar Tool Description yazımı büyük ölçüde geliştiricinin deneyimine bırakılmıştı.

Kimisi tek cümle yazıyordu.

Kimisi uzun uzun anlatıyordu.

Kimisi ise açıklama yazmaya bile gerek duymuyordu.

Bu araştırma ise ilk kez şunu söylüyor:

"İyi yazılmış Tool Description tesadüf değildir."

Ölçülebilir.

Puanlanabilir.

İyileştirilebilir.

Ve en önemlisi, sistem performansını doğrudan etkiler.

Bu bakış açısı önümüzdeki yıllarda "Tool Description Review" kavramını kod incelemeleri kadar önemli hâle getirebilir.

Prompt Engineering'in Yeni Adı: Context Engineering

Son iki yıldır teknoloji dünyasında en çok konuşulan kavramlardan biri Prompt Engineering oldu.

Ancak bu kavram artık sınırlarına ulaşıyor.

Çünkü gelişmiş AI ajanları tek bir prompt ile çalışmıyor.

Onlar;

• sistem promptlarını,
• kullanıcı isteklerini,
• geçmiş konuşmaları,
• hafızayı,
• araç açıklamalarını,
• parametre şemalarını,
• dış kaynaklardan gelen verileri

aynı anda değerlendiriyor.

Artık optimize edilen şey yalnızca prompt değil.

Bağlamın tamamı.

İşte bu nedenle son dönemde yeni bir kavram öne çıkmaya başladı:

Context Engineering.

Bu makale de tam olarak bu dönüşümün bilimsel kanıtlarından biri.

Tool Description artık bağımsız bir metin değil.

Modelin bağlamının ayrılmaz bir parçası.

Aslında Sorun LLM'lerde Değil

Son dönemde birçok şirket şu soruyu soruyor:

GPT-5 mi daha iyi?

Claude mu?

Gemini mi?

Llama mı?

Bence bu araştırmanın dolaylı olarak verdiği cevap oldukça ilginç.

Çoğu zaman problem model değil.

Problemi biz üretiyoruz.

Yetersiz açıklamalar...

Belirsiz parametreler...

Eksik kullanım senaryoları...

Tanımlanmamış sınırlar...

Sonra da modelin yanlış araç seçtiğini düşünüyoruz.

Oysa model, elindeki eksik bilgiyle mümkün olan en mantıklı kararı vermeye çalışıyor.

Bu, deneyimsiz bir mühendise yarım sayfalık doküman verip karmaşık bir sistemi yönetmesini istemeye benziyor.

Gelecekte Kod Review Yetmeyecek

Bugün modern yazılım ekiplerinde şu süreçler standart hâle geldi:

• Code Review
• Security Review
• Architecture Review
• Performance Review

Bence çok yakın zamanda bunlara bir başlık daha eklenecek:

AI Review

Bu inceleme sırasında yalnızca kod değil;

• Tool Name
• Tool Description
• Input Schema
• Examples
• Failure Cases

de değerlendirilecek.

Çünkü AI ajanı için bunların kalitesi, kodun kendisi kadar önemli.

Eksik Bıraktıkları Noktalar

Makale güçlü olmasına rağmen geliştirilmeye açık bazı alanlar da var.

1. Tool Name Etkisi

Araştırmacılar açıklamaları inceliyor.

Ancak araç isimlerini değerlendirmiyor.

Oysa aşağıdaki iki isim arasında büyük fark var:

get_data

ve

get_customer_invoice_history

Model, yalnızca isimden bile ciddi çıkarımlar yapabiliyor.

Gelecekte Tool Name kalitesinin de benzer şekilde ölçülmesi gerektiğini düşünüyorum.

2. JSON Schema

MCP'nin üçüncü ayağı olan Input Schema da davranışı etkiliyor.

Parametre isimleri...

Varsayılan değerler...

Zorunlu alanlar...

Enum tanımları...

Bunların hiçbiri ayrıntılı analiz edilmiyor.

Oysa Tool Description ile birlikte düşünülmeleri gerekiyor.

3. Runtime Öğrenme

Makale statik açıklamalar üzerinden çalışıyor.

Oysa geleceğin ajanları büyük ihtimalle şunu yapacak:

Tool başarısız oldu.

↓

Description yetersiz.

↓

Description'ı yeniden oluştur.

↓

Tekrar dene.

Yani Tool Description dinamik olarak değişebilecek.

Bu konu makalede yer almıyor.

4. Çoklu Model Davranışı

Çalışmada üç farklı model kullanılmış.

Ancak bugün çok daha güçlü modeller var.

GPT-5...

Claude Opus...

Gemini 2.5 Pro...

Bunların aynı açıklamaları nasıl yorumlayacağı önemli bir araştırma konusu olabilir.

Bence Asıl Devrim Burada Başlıyor

Bu makaleyi okurken aklıma sürekli aynı düşünce geldi.

Biz bugüne kadar yazılımları insanlar için geliştiriyorduk.

Artık ilk kullanıcı insan değil.

İlk kullanıcı çoğu zaman bir yapay zekâ.

Bu nedenle yazılım geliştirme kültürü de değişecek.

Eskiden şu soru soruluyordu:

Kod doğru çalışıyor mu?

Yakın gelecekte ise şu soru daha önemli olacak:

Yapay zekâ bu sistemi doğru anlayabiliyor mu?

İşte bu zihniyet değişimi, Agentic AI çağının en büyük dönüşümlerinden biri olabilir.

Bu makale yalnızca MCP hakkında değil.

Aslında yazılım mühendisliğinin geleceği hakkında.

Kod yazmaya devam edeceğiz.

API geliştirmeye devam edeceğiz.

Ancak artık bir sorumluluğumuz daha olacak.

Yapay zekânın bizi doğru anlayabileceği sistemler tasarlamak.

Kod çalıştıran bilgisayarlardan, kodu yorumlayan yapay zekâlara geçtiğimiz bu dönemde, birkaç satırlık Tool Description'ın milyonlarca dolarlık sistemlerin doğruluğunu ve maliyetini etkileyebileceğini görmek, belki de bu araştırmanın en önemli mesajı.