AI Ajanları İçin Etkili Araç Tasarımı: API Yazmaktan Farkı Ne?

Anthropic'in mühendislik blogundaki Writing effective tools for AI agents yazısının ana iddiası net: ajanların başarısı, onlara verdiğiniz araçların kalitesi kadar. Üstelik bu araçlar geleneksel API'lerden farklı tasarlanmalı, çünkü ajanlar API tüketicisi gibi davranmıyor.

Yazıdan birebir alıntıyla özetlemek gerekirse: "agents are only as effective as the tools we give them."

Temel ayrım: deterministik API vs ajan-dostu araç

Klasik yazılım, deterministik sistemler arasında sözleşme kurar. getWeather("NYC") çağrısı her zaman aynı tipte cevap döner.

Ajan farklı çalışıyor. Aynı görev için ajan:

• Aracı kullanabilir
• Genel bilgisinden cevap verebilir
• Aracı yanlış parametrelerle çağırabilir
• Aracın varlığını fark etmeyip soruyu hiç sormayabilir

Yani arayüz tasarımcısının uğraşı sadece "doğru veriyi dönmek" değil, modelin doğru aracı doğru parametrelerle bulup çağırmasına zemin hazırlamak. Anthropic'in işaret ettiği güzel detay: ajanlar için ergonomik olan araçlar, çoğu zaman insanlar için de daha sezgisel oluyor.

İlke 1: Her endpoint'i tool yapma, konsolide et

Yaygın hata: bir SaaS'ın 40 endpoint'i varsa, hepsini 40 ayrı tool olarak ajanın önüne koymak. Sonuç: ajan boğuluyor, yanlış araç seçiyor, görev gecikiyor.

Anthropic önerisi: ilişkili operasyonları tek tool altında birleştir. Örneğin list_users, list_events, create_event yerine; uygunluk kontrolünü kendi içinde yapan tek bir schedule_event tool'u.

E-ticaret bağlamında karşılığı: Trendyol'un sipariş, stok ve kargo endpoint'lerini 15 ayrı tool olarak vermek yerine, "iş akışı odaklı" 3-4 tool tasarlamak — get_order_with_full_context, update_inventory_atomic gibi.

İlke 2: Namespacing — araç gruplarına önek

Bir sistemde 30+ tool varsa, isim çakışmaları ve karışıklığı kaçınılmaz. Anthropic'in çözümü: ortak önekler. asana_projects_search ve asana_users_search gibi.

Yazı bu konuda net bir bulgu paylaşıyor: önek/sonek bazlı namespace seçimleri değerlendirmelerde "non-trivial effects" yaratmış. Yani bu kozmetik değil, ölçülebilir bir performans değişkeni.

Shobi gibi çok-pazaryerli mimaride doğal şekilde uygulanabilir: trendyol_orders_list, hepsiburada_orders_list, n11_inventory_update. Hem ajan için ayırt edici, hem geliştirici için okunabilir.

İlke 3: Anlam dön, UUID dönme

Önemli bir nokta: ajanın gözünde a1b2c3d4-e5f6-... ile Kırmızı Spor Ayakkabı aynı değil. UUID'ler ajan için gürültü. Anthropic'in tavsiyesi: "semantic meaning over technical identifiers."

Bu sadece estetik değil — yazıdaki bulgu net: keyfi alfanumerik UUID'leri anlamlı dile çözümlemek modelin doğruluk oranını ciddi şekilde artırıyor.

Pratik öneri: tool yanıtlarında name ve image_url dön, uuid ve 256px_image_url dönme. UUID'ye gerçekten ihtiyaç varsa opsiyonel parametre yap.

Ek olarak, verbosity kontrolü sun. Detaylı/kısa yanıt için bir enum parametre. Yazıda verilen örnekte detaylı yanıt 206 token, kısa yanıt sadece 72 token — ajan ihtiyacına göre seçsin.

İlke 4: Token ekonomisi araç tasarımının kalbi

Tool tasarımı bir token-ekonomisi disiplini. Anthropic'in önerileri:

• Pagination: Büyük sonuç kümelerinde varsayılan sayfa boyutu mantıklı (10-20 öğe), sayfa numarası parametresi ile genişle.
• Range selection: Tüm 10.000 satırı dönmek yerine, "satır 100-200" gibi aralık desteği.
• Filtreleme: Server tarafında filtre, sonra dön.
• Truncation default: Claude Code 25.000 token sınırı uyguluyor. Sınır aşıldığında yanıtın içine ajana yön gösteren uyarı ekleniyor: "Daraltılmış arama yap."

E-ticaret tarafında bu çok kritik. Bir pazaryeri 5.000 ürün dönerse ajan boğulur. Tool tasarımcısı sayfalama, kategori filtresi, fiyat aralığı parametrelerini en baştan koymalı.

İlke 5: Hata mesajları aracın bir parçası

Klasik API'de hata mesajı geliştiriciye yönelik. Ajan-dostu tool'da hata mesajı ajanın bir sonraki denemesini düzeltecek içerikte olmalı.

İyi hata: "Tarih formatı YYYY-MM-DD olmalı. Verilen: '15 Mayıs 2026'. Tekrar dene: '2026-05-15'." Kötü hata: "Error 400: Invalid date format."

Bu fark, ajan açısından "1 deneme daha + 1 retry" arasındaki farkı belirliyor.

İlke 6: Tool açıklamaları = prompt mühendisliği

Yazının belki en pratik bulgusu burada. Tool açıklamasını yazmak bir prompt engineering disiplini, salt dokümantasyon değil:

• Yeni bir takım üyesine anlatır gibi yaz.
• Implicit bağlamı explicit hâle getir.
• Parametre isimleri tek anlamlı olsun: user değil user_id, date değil start_date_iso.

Anthropic'in deneyimi: "even small refinements to tool descriptions can yield dramatic improvements." Tek bir parametrenin açıklamasını netleştirmek tüm bir görevin başarısını değiştirebiliyor.

Değerlendirme: tek doğru yol yok, ama yol var

Yazı şu uyarıyı veriyor: tool tasarımı kalitesini "doğru görüyor muyum?" diye gözle ölçemezsiniz. Sistematik değerlendirme gerekiyor.

Önerilen yaklaşım:

1. Gerçek iş akışlarına dayalı değerlendirme setleri kur (sandbox'lı senaryolar değil).
2. Basit bir agentic loop ile programatik testler çalıştır.
3. Sadece doğruluk değil; runtime, token tüketimi, hata oranı da topla.
4. Ajanın eksik bıraktıklarına dikkat et — yazıya göre "what agents omit in their feedback can often be more important than what they include."

İlginç bir öneri: tool açıklamalarını iyileştirme görevinde Claude'a kendi başarısızlık transkriptlerini analiz ettir. Ajan, eksik kalan parametre/yanlış yorumlanan açıklamayı çoğu zaman doğru tespit ediyor.

Shobi açısından sonuç

Çoklu pazaryeri AI agent'ı kuruyorsanız bu yazıdan damıtılacak operasyonel dersler:

1. Her pazaryeri endpoint'ini tool yapmayın. Konsolide edin — "tüm sipariş bağlamını getir" gibi iş-akışı odaklı tool'lar yazın.
2. Pazaryerini önek yapın. trendyol_*, hepsiburada_*, meta_ads_* — ajan için ayırt edici, geliştirici için okunabilir.
3. Ürün/sipariş ID yerine isim+kısa özet dönün. UUID kullanım sırasını minimize edin.
4. Sayfalama ve filtre varsayılan olsun, ajan boğulmasın.
5. Hata mesajlarını ajan-okuryazar yazın — sonraki denemeyi düzeltsin.
6. Tool açıklamalarını markdown dosyada tutun, değerlendirme döngüsüne sokun, iteratif iyileştirin.

Tool tasarımı UX disiplini hâline geliyor. Geleneksel API'leri kullanıcının insan olduğu varsayımıyla yazmıştık; artık kullanıcının model olduğu bir dünyaya geçiyoruz. Bu geçiş, "API ekibi" ile "ML ekibi"nin aynı masaya oturmasını gerektiriyor.

---

Kaynak: Writing effective tools for AI agents — Anthropic