Tool schema'ları

Bu modül için tahmini süre: 5 dakika

Genel bakış

Tool function’ınızı yazdıktan sonraki adım, fonksiyonun hangi argümanları beklediğini ve nasıl kullanılacağını Claude’a anlatan bir JSON schema oluşturmaktır. Bu schema, Claude’un tool’larınızı ne zaman ve nasıl çağıracağını anlamak için okuduğu dokümantasyon işlevi görür.

JSON Schema’yı anlamak

JSON Schema, AI veya tool calling’e özgü değildir — yıllardır kullanılan yaygın bir veri doğrulama spesifikasyonudur. AI topluluğu bunu benimsedi çünkü fonksiyon parametrelerini açıklamak ve veriyi doğrulamak için kullanışlı bir yol.

Tam tool specification’ın üç ana parçası vardır:

• name — Tool’unuz için açık, açıklayıcı bir isim (“get_weather” gibi)
• description — Tool’un ne yaptığı, ne zaman kullanılacağı ve ne döndürdüğü
• input_schema — Fonksiyonun argümanlarını açıklayan asıl JSON schema

Etkili description yazmak

Tool description’ınız, Claude’un fonksiyonunuzu ne zaman kullanacağını anlamasında kritiktir. Best practice’ler:

• Tool’un ne yaptığını açıklayan 3-4 cümleyi hedefleyin
• Claude’un bunu ne zaman kullanması gerektiğini tanımlayın
• Ne tür data döndüğünü açıklayın
• Her argüman için ayrıntılı description verin

Schema’ları oluşturmanın kolay yolu

JSON schema’ları sıfırdan yazmak yerine, bunları üretmek için Claude’u kullanabilirsiniz. Süreç şu şekildedir:

1. Tool function kodunuzu kopyalayın
2. Claude’a gidip tool calling için bir JSON schema yazmasını isteyin
3. Context olarak Anthropic’in tool use dokümantasyonunu dahil edin
4. Claude’un best practice’leri takip eden düzgün biçimlendirilmiş bir schema üretmesine izin verin

Prompt şu şekilde olabilir: “Write a valid JSON schema spec for the purposes of tool calling for this function. Follow the best practices listed in the attached documentation.”

Schema’yı kodda uygulamak

Claude schema’nızı ürettiğinde kod dosyanıza kopyalayın. İzlenecek iyi bir naming pattern:

def get_current_datetime(date_format="%Y-%m-%d %H:%M:%S"):
    if not date_format:
        raise ValueError("date_format cannot be empty")
    return datetime.now().strftime(date_format)

get_current_datetime_schema = {
    "name": "get_current_datetime",
    "description": "Returns the current date and time formatted according to the specified format",
    "input_schema": {
        "type": "object",
        "properties": {
            "date_format": {
                "type": "string",
                "description": "A string specifying the format of the returned datetime. Uses Python's strftime format codes.",
                "default": "%Y-%m-%d %H:%M:%S"
            }
        },
        "required": []
    }
}

Schema’larınızı düzenli tutmak ve karşılık gelen fonksiyonlarla eşleştirmek kolay olsun diye function_name’i takiben function_name_schema pattern’ini kullanın.

Type safety eklemek

Daha iyi type checking için Anthropic kütüphanesinden ToolParam type’ını import edip kullanın:

from anthropic.types import ToolParam

get_current_datetime_schema = ToolParam({
    "name": "get_current_datetime",
    "description": "Returns the current date and time formatted according to the specified format",
    # ... rest of schema
})

Bu işlevsel olarak şart olmasa da, schema’yı Claude’un API’siyle kullanırken type hatalarını önler ve kodunuzu daha sağlam kılar.

Temel çıkarımlar

• Bir tool schema üç parçadan oluşur: name, description, input_schema
• Description 3-4 cümle olmalı ve “ne yapar / ne zaman kullanılır / ne döner” sorularına yanıt vermeli
• JSON Schema AI’ya özgü değildir; tanıdık ve doğrulanabilir bir standarttır
• Schema’ları elle yazmak yerine Claude’a yazdırmak hızlı ve standartlara uygun bir yoldur
• function_name + function_name_schema adlandırma pattern’i kodu izlenebilir tutar
• ToolParam type’ı type-safety sağlar ve API kullanımında hata risklerini düşürür