Tool Interface Tasarımı

Bu derste Claude’un bir tool’u ne zaman, hangi sırayla, hangi gerekçeyle seçtiğini konuşuyoruz. Sınav tool_choice, input_schema ve “tool budget” kavramlarını sıkça sorar; çoğu yanlış cevap description kalitesinden değil, description’ın seçim mekanizması olduğunu unutmaktan gelir.

Neden bu konu sınavda çıkıyor

Domain 2 sınavın %18’i. Pratik senaryolardan “Code Generation” ve “Agentic AI Tools” tool tasarımı soruları içerir. Sınavda klasik format şu: bir tool seti verilir, description’lardaki belirli bir belirsizlik gösterilir, “hangi tool çağrılır?” diye sorulur — doğru cevap ya description’da yapılacak tek satırlık düzeltmedir ya da tool_choice parametresidir. Bu yüzden tool tasarımı “iyi yazılmış kod” değil, “iyi yazılmış seçim dokümanı” meselesidir.

Temel kavramlar

Tool definition anatomisi

Bir tool çağrısının JSON şeması üç parçadır: name, description, input_schema. Claude bir tool’u seçerken yalnızca description ve name alanlarını görür. input_schema yalnızca tool seçildikten sonra doğrulama için kullanılır — seçim kararına girmez.

{
  "name": "search_issues",
  "description": "GitHub repo'da issue ara. Kullanıcı bir bug veya feature hakkında 'şu çalışmıyor' derse, repo'da mevcut issue olup olmadığını sorgula. 'list_recent_commits' ile karıştırma; bu tool issue'lar içindir, commit geçmişi için değil.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query":  { "type": "string", "description": "Arama metni, örn. 'login 500 error'" },
      "state":  { "type": "string", "enum": ["open", "closed", "all"], "default": "open" },
      "limit":  { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }
    },
    "required": ["query"]
  }
}

Kritik gözlem: description iki iş yapıyor — (1) tool’un ne yaptığını söylüyor, (2) benzer tool’lardan farkını söylüyor. İkinci cümle sınavda en çok puan kazandıran kısım.

Schema design kalıpları

input_schema ve structured-output şemaları için rehberin sınav kapsamında vurguladığı üç kalıp:

• Nullable alanlar: Veri her zaman mevcut olmayacaksa "type": ["string", "null"] yaz. Model null döner; uydurma değer üretmez.
• Enum’a "other" + ayrı detail alanı: Önceden tanımlı kategoriler dışındaki veriyi kaybetmemek için enum’a "other" ekle ve yanına serbest metin taşıyan category_detail gibi ayrı bir alan aç.
• Enum’a "unclear" değeri: Model bir kategoriden emin değilse dürüst "unclear" dönmesi, yanlış kategori seçmesinden iyidir. Bu sınavda “model halüsinasyon yapmaktan kaçınır” sorularının cevabı.

Neden required alanlar tehlikeli: bir alanı required işaretlemek, modeli o alan her zaman varmış gibi davranmaya iter. Kaynakta veri yoksa model uydurur. Kural: her zaman mevcut olmayan alanı optional yap, gerekirse nullable kombinasyonu kullan.

Description iyi vs kötü

İki versiyonu yan yana koy. Aynı tool, farklı yazım:

Kötü:

"Fetches repository data."

İyi:

"Fetch repository metadata: stars, forks, description, default branch.
PR'lara veya issue'lara dokunmaz — sadece repo bilgisini okur.
'get_repo_issues' veya 'list_pull_requests' kullan, eğer PR/issue istiyorsan."

Kötü versiyon list_repos, get_repo_info, fetch_repo_data üç tool arasında seçim yapamaz — hepsi aynı description’a sahip. Claude context’ten tahmin etmek zorunda kalır ve misroute eder. İyi versiyon kullanıcı niyetine göre kendini diğerlerinden ayırır.

Built-in vs MCP tool tercihi

Agent, benzer işlevli built-in tool’u (Read, Grep) MCP tool’una tercih edebilir. Bu, MCP tool’un description’ı built-in kadar tanıdık gelmediğinde doğal bir sonuçtur. Çözüm: MCP tool description’ında built-in’in sağlayamayacağı somut avantajı (benzersiz veri, ek bağlam, kurum-spesifik semantik) açıkça vurgula. Aksi halde model, her seferinde önce built-in tool’u dener, MCP tool’u “ikinci tercih” olarak kalır.

tool_choice üçlüsü

API’de tool_choice parametresi Claude’un tool seçim davranışını kontrol eder:

Değer	Davranış	Uygun senaryo
"auto"	Claude karar verir; tool çağırabilir ya da düz metin dönebilir	Genel agent’lar, çok adımlı iş
"any"	Tool çağırmak zorunda (hangisini seçerse)	Zorunlu tool akışı (örn. her turda kayıt)
{"type": "tool", "name": "X"}	Sadece X tool’u seçilebilir	Predefined tek adımlı iş, JSON extraction

Sınav tuzağı: sıkça tool_choice: "any" doğru cevap gibi gösterilir ama bu sadece “tool çağrısı zorunlu” demektir. Eğer “hangi tool?” soruluyorsa {"type": "tool", "name": "..."} gerekir. "any" + birden fazla tool = Claude hangisini seçeceğine yine kendisi karar verir.

import anthropic

client = anthropic.Anthropic()

# Senaryo A: tool zorunlu, hangisini seçerse
r1 = client.messages.create(
    model="claude-sonnet-4-6",
    tools=[search_issues, list_recent_commits],
    tool_choice={"type": "any"},
    messages=[{"role": "user", "content": "Son activity nedir?"}],
)

# Senaryo B: sadece issue araması, başka tool yok
r2 = client.messages.create(
    model="claude-sonnet-4-6",
    tools=[search_issues, list_recent_commits],
    tool_choice={"type": "tool", "name": "search_issues"},
    messages=[{"role": "user", "content": "Bug var mı kontrol et"}],
)

Tool budget ve scoped access

Bir agent’a 18 tool vermek güvenilirliği düşürür, artırmaz. Sınavda bu net: rehbere göre 4-5 tool güvenilir eşik; tool sayısı arttıkça (örn. 18) seçim güvenilirliği düşer (“attention dilution”). Üst sınır kuralı: agent başına role-relevant tool + sınırlı cross-role tool.

Multi-agent mimaride bu doğal olarak çözülür: coordinator’ın allowedTools’unda Task, Read, Glob, Grep yeter; subagent’lar kendi tool setini alır (kod review agent → Read, Grep, Bash; veri analiz agent → Read, Bash + MCP query). Handoff’ta hangi tool setinin aktarılacağı explicit olmalı.

Coordinator:  Task, Read, Glob, Grep           (yönetsel)
Code-Review:  Read, Grep, Bash                 (salt okunur + çalıştırma)
Data-Analyst: Read, Bash, mcp__postgres__*     (DB erişimli)
Doc-Writer:   Read, Write                      (dosya yazan)

Bu tabloyu .claude/agents/<name>.md frontmatter’ında tools: alanına yazarsın. Sınavda “least privilege” sorusunun cevabı her zaman bu scoped erişimdir — mümkünse yazma yetkisi subagent’lara bırakılır; least privilege gereği aksi gerekmedikçe coordinator’a Bash veya Write verilmez.

System prompt’taki yanlış ilişkilendirme

Bir başka tuzak: system prompt’ta “use search_docs for code questions” yazıp sonra search_docs description’ında “kullanıcı kütüphane kullanımı soruyorsa çağır” demek. Bu iki katmanlı çağrı, Claude’un kafasını karıştırır. Tek doğru kaynak olmalı: ya system prompt’ta araç eşlemesi yap ya da description’da — ikisinde birden, çelişkili ifadelerle değil.

Sınav tuzakları

• “Aynı description’a sahip iki tool” seçeneği cazip gelir. Yanlış çünkü seçim mekanizması description’dır — aynı description = rasgele seçim. Doğru: description’lardan birine “benzer tool’lardan fark” cümlesi eklemek.
• Coordinator’a Bash vermek “daha güçlü” gibi görünür. Yanlış çünkü hub-and-spoke’ta coordinator’ın yaptığı iş dispatch’tir; Bash’le dosya silerse audit trail bozulur. Doğru: scoped tool listesi, yazma yetkisi subagent’lara — coordinator’a Bash/Write vermek least privilege’a aykırıdır.
• tool_choice: "any" ile “tek tool zorla” karıştırmak sınavda sıkça karşımıza çıkar. "any" tool sayısını sınırlamaz, sadece “tool çağrısı zorunlu” der. Doğru: {"type": "tool", "name": "X"} ile belirli tool’a pinle.
• 18 tool hepsi tek agent’ta “daha fazla esneklik” gibi pazarlanır. Yanlış çünkü her ek tool description, attention dilution yaratır; rehbere göre 4-5 tool güvenilir eşiktir, üzerine çıkıldıkça seçim güvenilirliği düşer. Doğru: domain decomposition + role-specific tool seti.
• input_schema’da default value eksikliği test sorusu gibi gelir. Doğru yaklaşım: sık kullanılan alanlara default ver, böylece Claude her seferinde belirtmek zorunda kalmaz (örn. limit: 10).

Hands-on

Bir code review agent’ı için minimal ve net tool seti:

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: >
  Use this agent when the user asks for a code review of a PR or file.
  Reads files, greps for patterns, runs linters. Does NOT write code.
tools: Read, Grep, Glob, Bash
model: claude-sonnet-4-6  # 📝 *Rehber kapsamı dışında:* rehberin AgentDefinition alanları name/description/system_prompt/allowed_tools; `model` alanı bu dörtlünün dışında (örnek Agent SDK kullanımı olarak gösterilmiştir).
---

Sen güvenlik ve kalite odaklı bir code reviewer olarak çalışıyorsun.

Görevin:
1. Verilen dosya(lar)ı oku (Read, Glob ile keşfet)
2. Pattern tara (Grep)
3. Lint ve test çalıştır (Bash — sadece read-only komutlar)
4. Bulgu başına: dosya:satır, severity (CRITICAL/HIGH/MEDIUM/LOW), kategori, önerilen düzeltme.

Yazma yetkin yok. Bulduğun sorunun çözümünü PR'a yazma; sadece raporla.

Gözlem: tools alanı sadece 4 tool. description hem ne yaptığını hem ne yapmadığını (“does NOT write code”) söylüyor. Bu “self-selection guard” sınavda örnek gösterilir.

Bir diğer hands-on: tool description audit’i. Mevcut tool’un description alanını şu checklist’ten geçir:

1. Ne yapar? — Tek cümle, fiil ile başlar.
2. Benzer tool’lardan farkı nedir? — Yan yana karışabilecek en az bir tool’a açık referans.
3. Ne zaman çağrılır / çağrılmaz? — Tetikleyici ifade örneği.
4. Hangi argümanlar zorunlu, hangileri opsiyonel? — input_schema’ya geçmeden ipucu.

Özet

• Tool description, tool’un tek seçim dokümanıdır — Claude onu okuyarak karar verir, kodunu değil.
• Aynı/örtüşen description = misrouting. Her tool “kendini rakiplerinden ayıran” bir cümle taşımalı.
• tool_choice: "auto" (Claude seçer veya cevap yazabilir), "any" (tool zorunlu, hangisi serbest), {"type":"tool","name":"X"} (sadece X).
• Agent başına rehbere göre 4-5 tool güvenilir eşik; tool sayısı arttıkça (örn. 18) seçim güvenilirliği düşer (attention dilution).
• Coordinator’ın allowedTools’u sadece yönetsel olmalı (Task, Read, Glob, Grep); yazma subagent’lara.
• System prompt ve description aynı tool eşlemesini çelişkisiz söylemeli — tek doğru kaynak prensibi.

Kaynaklar

• Anthropic Docs — Tool Use Overview: https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/overview
• Anthropic Docs — Tool Choice: https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/implement-tool-use#tool-choice-parameter
• Anthropic Docs — Subagent Tool Scoping: https://docs.anthropic.com/en/docs/agents-and-tools/agent-sdk/subagents