Bir LLM'in doğru kullanabileceği tool'lar tasarlamak
Bir modele tool verdiğinizde aslında bir API yayınlıyorsunuz. Yalnız bu API'nin tüketicisi alışılmadık biri. Kaynak kodunuzu hiç okumuyor, dokümantasyon sitesini hiç açmıyor, bir parametrenin ne anlama geldiğini bir meslektaşına sormuyor. Elinde sadece bir isim, bir paragraf açıklama ve bir JSON Schema var; tool'u çağırıp çağırmayacağına, ne zaman ve hangi değerlerle çağıracağına bunlara bakarak karar vermek zorunda.
API tasarımı hakkında doğru bildiğim her şey burada da geçerli. Fark şu: belirsizliğe tolerans kalmıyor. Bir parametreyi yanlış anlayan geliştirici bunu code review'da öğrenir; model ise production'da öğrenir, tabii öğrenirse.
Açıklama, sözleşmenin tamamı
Tüketici bir insan olduğunda imza sözleşmenin başlangıcıdır; gerisini dokümantasyon, örnekler ve tip sistemi tamamlar. Model için ise tool tanımı her şeydir. Tool hakkında bildiğiniz ama yazmadığınız her şeyi model bilmez.
Bu, "yeterince iyi"nin anlamını değiştiriyor. Implementasyona tek tıkla gidebildiğiniz bir kod tabanında
search(query) gayet yeterli. Bir model için ise bütün soruları açık bırakıyor: neyi arıyor, hangi
kapsamda, kaç sonuç dönüyor, hangi sırayla, sonuç çok fazlaysa ne yapmalı?
İşe yarayan bir test: tool listesini, başka hiçbir şey açık değilken, tam olarak modelin gördüğü haliyle okuyun. Hangi tool'u seçeceğinizi ya da ne geçeceğinizi bilemiyorsanız, model de bilemez. Sadece daha emin bir tavırla tahmin eder.
Her tool'a tek bir iş
Bir mode ya da action parametresine göre birkaç farklı iş yapan tool'u iyi kullanmak zordur. create,
close, comment ve delete seçenekleri olan bir manage_issue(action, ...), dört ayrı sözleşmeyi tek
bir ismin arkasına saklar; bir işlem için anlamlı olan parametreler diğerleri için gürültü, hatta tuzak
olur. Bir schema "action değeri comment ise body zorunludur" diyebilir, ama her modelin güvenilir
biçimde uyacağı bir şekilde değil.
Bölün: create_issue, close_issue, add_comment. Her birinin tek bir davranışı anlatan açıklaması,
hepsi anlamlı parametreleri ve kendi yetkileri olur. Sonuncusu göründüğünden daha önemli. delete_issue
ayrı bir tool olunca, diğerlerine dokunmadan onu tamamen dışarıda bırakabilir ya da onaya
bağlayabilirsiniz.
İsimler ve açıklamalar model için yazılır
İsimler ne olacağını söylemeli: get_invoice, list_invoices, void_invoice. Şirket içi jargon,
kısaltma ya da arkadaki servis sınıfının adı değil. İki tool'un adı birbirine benziyorsa model onları
karıştırır; birinin adını değiştirin ya da ikisini birleştirin.
Açıklama, dikkatli bir çağıranın soracağı soruları cevaplamalı:
- Ne yapıyor, neyi yapmıyor?
- Benzer bir tool yerine ne zaman bu kullanılmalı?
- Ne dönüyor, ne kadarını dönüyor?
- Herhangi bir şeyi değiştiriyor mu?
Kısa ve olgusal tutun. Açıklama her uç durumu sıralamanın yeri değil; bunun doğru çağrı olup olmadığına
karar verdiren iki üç bilginin yeri. Bir parametrenin belli bir formatı varsa bunu örnekle söyleyin:
"ISO 8601 tarih, örn. 2026-10-11", "tarih" demekten çok daha değerli.
Parametreleri kısıtlayın
Her serbest metin alanı tahmine davetiyedir. Bir parametrenin beş geçerli değeri varsa onu enum yapın.
Bir sayının aralığı varsa aralığı yazın ve uygulayın. Bir metin bir kimlikse, nereden geldiğini söyleyin
("list_invoices'ın döndürdüğü id"); böylece model bir tane uydurmak yerine gidip getirir.
.NET'te Microsoft.Extensions.AI schema'yı metodun imzasından çıkarıyor, yani kısıtlar sıradan C#
kodunda yaşıyor:
using System.ComponentModel;
using Microsoft.Extensions.AI;
public enum IssueState { Open, Closed, All }
public sealed record IssueSummary(int Number, string Title, IssueState State);
public sealed record IssuePage(IReadOnlyList<IssueSummary> Items, string? NextCursor);
public sealed class IssueTools(IIssueStore store)
{
[Description("Searches issues in the current repository by text in the title or body. " +
"Returns summaries only, newest first. Use get_issue to read one in full.")]
public Task<IssuePage> SearchIssuesAsync(
[Description("Words to look for, e.g. \"login timeout\".")] string query,
[Description("Which issues to include.")] IssueState state = IssueState.Open,
[Description("How many results to return, 1 to 50.")] int limit = 20,
[Description("The nextCursor of a previous result. Omit for the first page.")] string? cursor = null,
CancellationToken cancellationToken = default)
=> store.SearchAsync(query, state, Math.Clamp(limit, 1, 50), cursor, cancellationToken);
}
var tools = new IssueTools(store);
var options = new ChatOptions
{
Tools = [AIFunctionFactory.Create(tools.SearchIssuesAsync, name: "search_issues")],
};
Metodun üzerindeki [Description] tool'un açıklaması oluyor, parametrelerin üzerindekiler de
parametreleri anlatıyor. Kütüphanenin varsayılan serializer ayarları enum'ları metin olarak yazdığı için
enum modele izin verilen değerlerin listesi olarak ulaşıyor. Varsayılan değeri olan parametreler
opsiyonel; CancellationToken'ı ise kütüphane kendisi bağlıyor ve schema'ya hiç koymuyor. Modelin tam
olarak ne göreceğini merak ediyorsanız fonksiyonun JsonSchema'sını yazdırın.
Math.Clamp'e dikkat. Açıklama bir ricadır, garanti değil. Schema, modelin göndermesi muhtemel değerleri
daraltır; modelin gerçekte ne gönderdiğini yine sizin kodunuz kontrol etmek zorunda. Bunun adı input
validation ve yeri, diğer bütün API sınırlarında olduğu gibi, tool'un kendisi.
Bir sonraki adımı söyleyen hatalar
Bir tool başarısız olduğunda, modelin sonraki adımına karar verirken elindeki tek şey hata mesajıdır. "Error: 404" aynı argümanlarla tekrar denemeye ya da kullanıcıdan özür dilemeye götürür. "Bu repoda #4121 numaralı issue yok. Doğru numarayı bulmak için search_issues kullanın." ise doğru bir ikinci çağrıya.
Hataları, kodu göremiyor olsaydınız nasıl görmek isterdiyseniz öyle yazın: ne yanlıştı, hangi değer buna yol açtı, onun yerine ne işe yarardı. "Argümanların yanlış", "bizim tarafta bir şey bozuldu" ve "bunu yapmaya yetkin yok" durumlarını birbirinden ayırın; çünkü doğru tepkiler farklı: düzelt ve tekrar dene, bekle ya da vazgeç, dur.
Microsoft.Extensions.AI'da bilmeye değer bir ayrıntı var. Bir fonksiyon exception fırlattığında
FunctionInvokingChatClient modele varsayılan olarak genel bir hata gönderiyor; exception mesajı modele
ancak IncludeDetailedErrors açıksa ulaşıyor ve dokümantasyon bunun iç ayrıntıları açığa
çıkarabileceği konusunda uyarıyor. Beklenen hatalar için yönlendirmeyi taşıyan bir sonuç dönmeyi,
exception'ları gerçekten istisnai durumlara saklamayı tercih ederim.
Yan etkiler: idempotency ve dry run
Modeller çağrıları tekrarlar. Bir cevap yarıda kesilir, bir timeout tetiklenir, bir döngü bir adım fazla döner ve aynı çağrı iki kez gelir. Okuma için bunun bedeli token'dır. "Faturayı gönder" için bedeli ikinci bir faturadır.
Yan etkisi olan tool'lar iki kez çağrıldığında güvenli olmalı. Bunun yolları HTTP'dekiyle aynı: bir idempotency key kabul edin ya da işlemi doğası gereği idempotent yapın. Bir durumu tersine çevirmek yerine belirli bir duruma getirin; "etiket ekle" yerine "etiketin var olduğundan emin ol".
Pahalı ya da geri alınması zor işlemler için ne olacağını döndüren bir dryRun parametresi hem ucuz hem
çok kullanışlı. Model planı gösterir, bir insan okur, gerçek çağrı ondan sonra gelir. Geri alınamaz
işlemler ise bir parametreden fazlasını hak ediyor: modelin atlayamayacağı bir onay adımı. Bunu
Prompt injection bir input sorunu yazısında anlattım.
Context window'u koruyun
Bir tool'un döndürdüğü her şey modelin context'ine giriyor; o context de sınırlı ve modelin aklında tutması gereken diğer her şeyle paylaşılıyor. On bin satır döndüren bir tool yardımcı olmuyor, asıl işi görüş alanının dışına itiyor.
Bu yüzden sonuçlar varsayılan olarak sınırlı olmalı:
- Sayfalayın. Yukarıdaki örnekteki gibi bir sayfa ve bir cursor dönün; varsayılan sayfa küçük olsun.
- Önce özet, istenirse ayrıntı. Listeleme tool'u id ve başlık döner; getirme tool'u kaydın tamamını.
- Dürüstçe kırpın. Uzun bir metni kestiyseniz bunu sonuçta söyleyin: ne kadarı dışarıda kaldı ve geri kalanı nasıl alınır. Sessizce kırpılmış bir sonuç hatadan kötüdür, çünkü model onu eksiksiz sanar.
- Modelin kullanamayacağını dışarıda bırakın. İç anahtarlar, audit kolonları ve kimsenin istemediği iç içe nesneler sadece token'dır.
Az tool, çok tool'dan iyidir
Tool tanımları her istekle birlikte gönderiliyor ve her ek tool, yanlış seçilebilecek bir seçenek daha. Açıklamaları birbirine karışan yirmi tool'u kullanmak, birbirinden açıkça farklı altı tool'u kullanmaktan zordur.
Uyması en zor kural bu, çünkü her tool tek başına makul görünür. Sorulacak soru "bu işe yarayabilir mi?" değil, "model bunların arasından her seferinde doğru olanı seçer mi?". İki tool neredeyse hep birlikte çağrılıyorsa birleştirin. Bir tool'a nadiren ihtiyaç duyuluyorsa varsayılan setin dışında tutun, sadece kullanıldığı yerde ekleyin. Bir tool tehlikeliyse, onu hiç sunmamak çağrılmayacağının en güçlü garantisidir.
Bunların hiçbiri yeni değil. Hepsi, bir insan okuyucunun güvenlik ağı olmadan yapılan sıradan API tasarımı: net isimler, dar sözleşmeler, doğrulanmış input, işe yarar hatalar, sınırlı output. Model ona verdiğiniz her kelimeyi okuyor ve başka hiçbir şeyi okumuyor; o kelimeleri dikkatle seçmeye değer.
