Ajanınıza iki araç verdiniz: `updateUser` ve `deactivateUser`. Bir destek talebinde "bu hesabı kapatın" yazıyor. Ajan `deactivateUser`'ı çağırdı. Geçen hafta, neredeyse aynı bir talep, `updateUser`'ı `status: "closed"` ile çağırmasına neden oldu, API'niz bunu kabul etti ve bu, akışın aşağısında biraz farklı bir anlama geliyordu. Hiçbir şey bozuk değildi. Model, açıklamaları hangisinin uygulanacağını söylemeyen iki makul seçenek arasında seçim yapıyordu. Araç seçimi, insanların modeli suçladığı ve şemada düzelttiği bir hata modudur, çünkü şema, modelin dayanabileceği tek şeydir. Bu rehber, modelin bir araç seçerken gerçekte ne okuduğunu, ayırt edici isimler ve açıklamalar yazmayı, parametre tasarımının hata oranını nasıl değiştirdiğini ve bir ifade değişikliğinin bunu sessizce bozmaması için seçimi nasıl test edeceğinizi kapsar. Araçlarınız, [bir OpenAPI belirtimini ajan araçlarına dönüştürme](https://apidog.com/tr/blog/openapi-spec-as-agent-tools) rehberimizde olduğu gibi bir spesifikasyondan oluşturulduğunda, bu, o spesifikasyona neyin gireceği sorusu haline gelir. Araçlarınız API tanımınızdan geliyorsa, açıklamalar [Apidog](https://apidog.com) adresinde bulunur, bu nedenle birini iyileştirmek hem dokümantasyonu hem de araçları birlikte iyileştirir.
Model ne görüyor
Seçim anında, modelin bir konuşma, sistem istemi ve bir araç tanımları listesi vardır. Her tanım bir isim, bir açıklama ve bir parametre şemasıdır. API belgeleriniz, kod yorumlarınız veya `updateUser`'ın eski olduğuna dair geleneksel bilginiz yoktur. Bu, her belirsizliğin tanımın kendisine yazılması gerektiği anlamına gelir. Hem [OpenAI işlev çağırma rehberi](https://platform.openai.com/docs/guides/function-calling) hem de [Anthropic araç kullanımı dokümantasyonu](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview) aynı noktaya değiniyor: açıklama, tüm tanımda en çok önem taşıyan metindir ve kısa olmaktan ziyade ayrıntılı olmalıdır. Seçim hataları dört şekilde ortaya çıkar ve her birinin farklı bir düzeltmesi vardır. İki tanım çakıştığında model benzer bir araç seçer. Her biri ne zaman kullanılmayacağını söyleyecek şekilde açıklamaları düzeltin. Hiçbir açıklama görevin diliyle eşleşmediğinde model hiçbir şey seçmez ve hafızasından yanıt verir. Kullanıcılarınızın kullandığı kelimeleri kullanarak düzeltin. Parametreler belirsiz olduğunda model doğru aracı yanlış argümanlarla seçer. Türler, enumlar ve birimlerle düzeltin. Sıra önemli olduğunda ve hiçbir şey belirtmediğinde model araçları kötü zincirler. Önkoşulu açıklamada belirterek düzeltin.
Araçlara yaptıkları işe göre ad verin
İsimler, uzunluklarından daha fazla sinyal taşır, çünkü model onları ilk okur. Tüm araç setinde aynı stilde `fiilİsim` kullanın: `createOrder`, `refundOrder`, `getOrderStatus`. Bireysel seçim kadar tutarlılık da önemlidir, çünkü `order_create`, `getOrder` ve `refund` karışımı bir set, her ismi biraz daha zor okunur hale getirir. Nesne hakkında belirli olun. `search` kötü bir araç ismidir. `searchCustomersByEmail` iyi bir isimdir ve modele hem neyi aradığını hem de nasıl aradığını söyler. Dahili jargonlardan kaçının. API'niz bir müşteriyi "varlık" ve bir aboneliği "enstrüman" olarak adlandırıyorsa, model bunları "müşteri" ve "plan" diyen bir taleple ilişkilendiremez. Araçları şema dilinde değil, görev dilinde adlandırın. Farklı bağlamlarda bir ismi asla yeniden kullanmayın. Farklı ad alanlarında `list` adlı iki araç, tek bir listede göründükleri anda belirsizliğe dönüşür.
Ayırt edici açıklamalar yazın
Faydalı bir açıklama dört soruyu yanıtlar: ne işe yarar, neyi değiştirir, ne zaman kullanılır ve ne zaman kullanılmaz. İşte zayıf bir çift: ```json { "name": "updateUser", "description": "Bir kullanıcıyı günceller." } { "name": "deactivateUser", "description": "Bir kullanıcıyı devre dışı bırakır." } ``` Ve gerçekten ayırt edici bir çift: ```json { "name": "updateUser", "description": "Ad, e-posta veya saat dilimi gibi aktif bir kullanıcının profil alanlarını günceller. Kullanıcı tarafından talep edilen düzeltmeler ve profil düzenlemeleri için kullanın. Hesap durumunu DEĞİŞTİRMEZ. Bir hesabı devre dışı bırakmak için bunun yerine deactivateUser kullanın. Bir hesabı kapatmak veya iptal etmek için kullanmayın." } { "name": "deactivateUser", "description": "Bir kullanıcı hesabını devre dışı bırakır, tüm oturumları iptal eder ve oturum açmayı engeller. reactivateUser ile geri alınabilir. Bir müşteri hesabını kapatmak, iptal etmek, duraklatmak veya askıya almak istediğinde kullanın. Verileri SİLMEZ. Kalıcı silme için deleteUser kullanın, bu geri alınamaz." } ``` Orada dört teknik iş görüyor. **Kardeşini adlandırın.** "Bunun yerine deactivateUser kullanın" doğrudan, modelin onları karşılaştırdığı anda belirsizliği giderir. **Kullanıcının kelime dağarcığını ekleyin.** "Kapat", "iptal et", "durdur" ve "askıya al" kelimeleri, bu kelimelerin taleplerde görünmesinden dolayı yer almıştır. Bu, yapabileceğiniz en yüksek getirili düzenlemedir ve neredeyse ücretsizdir. **Ne yapmadığını söyleyin.** Olumsuz ifadeler, olumlu olanlardan daha ayırt edicidir, çünkü iki komşu aracın olumlu iddiaları birbirine benzeme eğilimindedir. **Geri alınabilirliği işaretleyin.** Risk olduğunu söylediğinizde model risk hakkında mantık yürütür. Bu, gerçek korumanın ait olduğu [yapay zeka ajan korumaları](https://apidog.com/tr/blog/ai-agent-guardrails) hakkındaki yazımızdaki uygulama modelleriyle eşleşir. Uzunluk sorun değil. Yıkıcı bir uç noktaya yapılan bir yanlış çağrıyı önleyen yüz kelimelik bir açıklama ucuzdur.
Yanlış argümanların zor olması için parametreleri tasarlayın
Doğru araç seçildikten sonra, işlerin yanlış gidebileceği bir sonraki yer argümanlardır. JSON Şema burada ihtiyacınız olan kısıtlamaların çoğunu sağlar ve [JSON Şema doğrulama sözlüğü](https://json-schema.org/draft/2020-12/json-schema-validation), araç çağıran API'nizin desteklediği anahtar kelimeler için göz atmaya değerdir. **Kapalı setlerde her yerde enum kullanın.** Dize olarak yazılmış bir `status` parametresi buluşa davetiye çıkarır. Enum olarak yazıldığında, modeli API'nizin kabul ettiği değerlere kısıtlar. ```json "status": { "type": "string", "enum": ["pending", "paid", "refunded", "cancelled"], "description": "Sipariş durumu. 'cancelled' asla yerine getirilmedi anlamına gelir; 'refunded' yerine getirildi ve sonra tersine çevrildi anlamına gelir." } ``` **Birimleri isme koyun.** `amount` belirsizdir ve modeller dolar veya senti tutarsız bir şekilde tahmin edecektir. `amount_cents` asla değildir. Aynı şey `timeout_seconds`, `distance_meters` ve `duration_ms` için de geçerlidir. **Tarih formatlarına bir örnek verin.** `"description": "ISO 8601 formatında başlangıç tarihi, örneğin 2026-08-26"` yalnızca "başlangıç tarihi"ne göre çok daha sık doğru biçimlendirilmiş tarihler üretir. **Gerekli listeleri dürüst tutun.** Her şeyi isteğe bağlı işaretlemek hataları çalışma zamanına iter; API'nin varsayılan olarak akıllıca davrandığı şeyleri gerekli işaretlemek modelin değerler uydurmasına neden olur. Her ikisi de yaygındır ve her ikisi de [ajanlar için API hata tasarımı](https://apidog.com/tr/blog/api-error-messages-for-ai-agents) hakkındaki yazımızda ele alınan doğrulama hataları olarak ortaya çıkar. **İç içe yerine düz yapıyı tercih edin.** `{"customer": {"address": {"postal_code": "..."}}}` dolduran bir model, `customer_postal_code` üzerinde yapmadığı yapısal hatalar yapar. Araç sınırında düzleştirin ve yürütücünüzde yeniden birleştirin. **Aşırı yüklenmiş araçları bölün.** Her diğer alanın anlamını değiştiren bir `mode` parametresine sahip bir araç aslında iki araçtır. Bunu bölmek seçimi iyileştirir ve her iki şemayı da basitleştirir.
Önkoşulları ve sırayı belirtin
Model sırayı bilmediğinde çok adımlı çalışmalar başarısız olur. Bağımlı aracın açıklamasında bunu belirtin: ```json { "name": "captureCharge", "description": "Daha önce yetkilendirilmiş bir ödemeyi yakalar. authorizeCharge'dan bir authorization_id gerektirir. Halihazırda yoksa önce authorizeCharge'ı çağırın. Yetkilendirilmiş miktardan daha fazlasını yakalayamaz." } ``` İki satır, ve sıralama sorunu modelin zaten okuduğu yerde ele alınmış olur. Bu, tüm sınıf için geçerlidir: güncellemeden önce oluştur, işlemden önce yükle, yakalamadan önce yetkilendir. Bağımlı bir adımın açıklaması kendisinden önceki adımı adlandırmazsa, modelin onu atlamasını bekleyin. Sıra birden fazla çağrı yerine birden fazla ajanı kapsadığında, [alt ajanlar arasında bağlam geçirme](https://apidog.com/tr/blog/agent-handoff-context-passing) hakkındaki yazımızdaki devir kuralları geçerlidir.
Seçimi diğer davranışlar gibi test edin
Açıklamalar koddur ve gerilerler. Birisi bir stil rehberine uymak için birini kısaltır ve ajan ertesi Salı günü yanlış uç noktayı seçmeye başlar. Küçük bir seçim paketi oluşturun. Yirmi ila elli istem, her biri beklediğiniz araçla. Bunları çalıştırın, modelin hangi aracı seçtiğini kaydedin ve yalnızca isme göre doğrulayın. Argümanlar her çalıştırmada değişir; seçim değişmemelidir. Bu, [deterministik olmayan yapay zeka ajanlarını test etme](https://apidog.com/tr/blog/testing-non-deterministic-ai-agents) rehberimizdeki yaklaşımın pratik şeklidir. Kırılması en olası durumlarla besleyin: * Setinizdeki en benzer iki araç, her birine yönlendirmesi gereken istemlerle. * API kelime dağarcığı yerine müşteri kelime dağarcığı kullanan istemler. * Hiçbir şeyle eşleşmemesi gereken bir istem, burada doğru davranış bir çağrıyı zorlamak yerine sormaktır. * Yanlış bir seçimin gerçek maliyeti olan yıkıcı bir araç. Her istemi birkaç kez çalıştırın. Beş vakanın dördünde kazanan bir araç, üretimde bir yazı tura atışıdır ve açıklamanın üzerinde çalışılması gerekir. Seçim testi canlı verilere asla dokunmasın diye çalıştırmaları sahte verilere yönlendirin. [Ajanları üretim yerine sahte verilere karşı çalıştırma](https://apidog.com/tr/blog/ai-agents-mock-apis-not-production) hakkındaki yazımız kurulumu kapsar ve [Apidog](https://apidog.com), araçlarınızın oluşturulduğu aynı tanımdan bu sahte verileri sunabilir, bu da şema ve davranışı uyumlu tutar.
Aynı şekilde yanlış giden üç set
**CRUD seti.** Bir API, `getUser`, `listUsers`, `searchUsers` ve `queryUsers`'ı ifşa eder, hepsi yıllar içinde büyüyen uç noktalardan oluşturulmuştur. Bir model için bunlar tek bir fikir için dört isimdir. Çözüm dördü üzerinde daha iyi açıklamalar değil; bunlardan birini ajana ifşa etmek ve diğerlerini araç listesinin dışında bırakmaktır. Küratörlü bir set, eksiksiz bir seti her zaman yener. **Yönetici seti.** Okuma araçları ve yıkıcı araçlar aynı tonda yan yana durur: `getInvoice`, `voidInvoice`, `deleteInvoice`. Metinde bunlardan ikisinin kariyerleri bitirdiğine dair hiçbir sinyal yoktur. Sonucu açıklamaya ekleyin, onay için işaretleyin ve uygulamayı yürütücüde tutun, ifadeye güvenmek yerine. Katmanlı yaklaşım, [ajanların API'nizi yok etmesini önleme](https://apidog.com/tr/blog/prevent-ai-agents-nuking-apis) hakkındaki yazımızda yer almaktadır. **Eski set.** İki uç nokta aynı işi yapar, biri kullanımdan kaldırılmıştır. Spesifikasyon hala ikisini de listeler, bu yüzden jeneratör ikisini de üretir ve ajan zamanın yaklaşık yarısında eskiyi seçer. Ya kullanımdan kaldırılan işlemi oluşturulan araçlardan çıkarın ya da açıklamasını "Kullanımdan kaldırıldı. Bunun yerine createOrderV2 kullanın." kelimeleriyle başlatın. Modeller bu satırı ilk sırada olduğunda onurlandırır, ancak sonunda gömülü olduğunda göz ardı eder.
Açıklamalar paylaşılan yapılandırmadır
Araç açıklamalarının davranışı yönlendirdiğini kabul ettiğinizde, sonraki soru bunların kime ait olduğudur. Çoğu takımda cevap tesadüfidir: ajanı ilk kuran kişinin makinesindeki bir dosyada. Bunun yerine araç setini, diğer arayüzler gibi incelenen paylaşılan bir yapıt olarak ele alın. Ajan çalışmaları etrafında inşa edilmiş platformlar bunu genellikle doğrudan modeller. Bir [Sharkly](https://sharkly.ai) Ajansı, talimatları, Çalışma Zamanını, Becerileri ve depolama alanlarını kapsayan kaydedilmiş bir yapılandırmadır ve onu bir Alan'da paylaşmak, bir kişinin çalışma kurulumunu takım tarafından yeniden kullanılabilir hale getirir. Değer, depolama değildir. Önemli olan, bir açıklama değişikliğinin, bir geliştiricinin ajanını diğerlerinden farklı davranmasına neden olan sessiz bir yerel ayar değişikliği yerine, herkesi etkileyen gözden geçirilebilir bir düzenleme haline gelmesidir.
Kullanıcıların getirdiği kelimeleri izleyin
En yaygın boşluk kelime dağarcığıdır. API'niz `abonelik` derken, müşterileriniz `plan`, `üyelik` ve `faturalama` der. API'niz `devre dışı bırak` derken, onlar `iptal et`, `kapat` ve `kapat` der. Gerçek dili toplayın. Destek taleplerinden, arama günlüklerinden veya başarısız ajan çalıştırmalarının metinlerinden en çok kullanılan ifadeleri çekin, sonra bunları eşleşmesi gereken araçların açıklamalarına ekleyin. Bu bir saat sürer ve genellikle şema ayarlamalarından daha fazla seçim doğruluğunu artırır. Başarısızlıklara da dikkat edin. Bir ajan hiçbir şey seçmez ve kendi bilgisinden yanıt verirse, bu bir kelime dağarcığı eksikliğidir, bir muhakeme hatası değildir. Görev dili araç metniyle asla çakışmadığından, araç görünmezdi.
Bir araç seti için kontrol listesi
* İsimler tek bir `fiilİsim` kuralına uyar ve belirli bir nesneyi adlandırır. * Her açıklama neyin değiştiğini, ne zaman kullanılacağını ve ne zaman kullanılmayacağını söyler. * Çakışan araçlar birbirlerini açıkça adlandırır. * Açıklamalar sadece dahili terimleri değil, kullanıcıların gerçekten kullandığı kelimeleri içerir. * Yıkıcı ve geri döndürülemez eylemler açıklamada belirtilmiştir. * Her kapalı set için enumlar bildirilmiştir. * Birimler ve formatlar parametre adlarında veya açıklamalarında, örneklerle birlikte yer alır. * Gerekli listeler, API'nin gerçekten uyguladığıyla eşleşir. * Bağımlı araçlar önkoşullarını adlandırır. * Bir seçim paketi CI'da sahte verilere karşı çalışır. Model, sizin yazdığınız metne karşı bir desen eşleştirme yapar. Yanlış seçtiğinde, bakılacak ilk yer metindir ve genellikle değiştirmeniz gereken tek yerdir. Açıklamaları, sahte verileri ve testleri tek bir projede istiyorsanız [Apidog'u indirin](https://apidog.com/download).
Sıkça sorulan sorular
**Bir araç açıklaması ne kadar uzun olmalı?** Belirsizliği giderecek kadar uzun, bu genellikle iki ila beş cümledir. Açıklamalar bağlamı kaplar, bu yüzden belirsiz olmayan araçlar için olanları kısaltın ve birbirine yakın araçlar için boşluk bırakın. **Açıklamaya örnekler koymalı mıyım?** Evet, formatlar ve birimler için, bir örnek tüm hata sınıfını ortadan kaldırır. Uzun kullanım örneklerini atlayın, çünkü bunlar bağlam maliyetlidir ve seçimi nadiren değiştirirler. **Çok sayıda dar araç mı yoksa az sayıda esnek araç mı daha iyidir?** Bir noktaya kadar dar araçlar. Her biri tek bir iş yaptığı için daha güvenilir seçilir. Birkaç düzineden sonra, listenin kendisi sorun haline gelir ve [OpenAPI'den ajan araçları oluşturma](https://apidog.com/tr/blog/openapi-spec-as-agent-tools) hakkındaki yazımızda ele alındığı gibi filtreleme veya alma yaparsınız. **Seçimi bunun yerine sistem isteminde düzeltebilir miyim?** Kısmen ve bir veya iki bilinen karışıklık için makul bir geçici çözümdür. Ölçeklenmez, çünkü istem tüm araçlar arasında paylaşılırken açıklama ona ihtiyaç duyan araçla birlikte gider. **Model parametre değerleri uydurmaya devam ederse ne olur?** Türü kısıtlayın, bir enum ekleyin ve açıklamada değerin oluşturulmak yerine önceki bir çağrıdan gelmesi gerektiğini belirtin. Hala devam ederse, sarmalayıcıda doğrulama yapın ve izin verilen değerleri adlandıran bir hata döndürün. **Bu kurallar MCP sunucuları için de geçerli mi?** Evet. Bir MCP sunucusu, isimleri, açıklamaları ve şemaları aynı şekilde ifşa eder, bu nedenle aynı ifade kuralları geçerlidir. [MCP'nin ne olduğu](https://apidog.com/tr/blog/what-is-mcp-model-context-protocol) hakkındaki açıklayıcımız protokolün kendisini kapsar.