Tool 정의와 JSON Schema 규율

Tool당 필수 필드 셋

Tool 정의는 필수 필드 셋 — name(snake_case 식별자), description(도구가 뭘 하나, 언제 쓰나), input_schema(args에 대한 JSON Schema). 모델이 description 읽고 도구 픽; input_schema 읽고 args 모양 잡음. 둘 다 중요; 한 개로 부족.

Description은 라벨 아니라 프롬프트

Description을 모델이 도구 호출 시점 결정 돕는 작은 프롬프트 fragment로 다뤄. 'Get the weather'는 너무 얇음; 'Get current weather and 24h forecast for a city. Use this when the user asks about temperature, rain, or what to wear today.'가 신뢰할 selection 모양.

required, types, enum 가진 스키마

Full JSON Schema 기능 사용 — required 배열, 고정 셋엔 enum, 제약 가진 type. 스키마가 풍부할수록 모델이 valid input 더 신뢰성 있게 생성. Trade-off — 스키마 매 바이트가 input 토큰 비용, 그래서 over-spec 금지.

원칙: Tool name + description이 selection; schema가 constraint. 둘 다 craft 받을 가치.

Code

상세 tool 정의·python

TOOLS = [
    {
        "name": "search_orders",
        "description": (
            "Search the orders database by customer email and optional status. "
            "Use when the user asks about their order history, refund status, "
            "or shipping. Do NOT use to create or modify orders."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "customer_email": {
                    "type": "string",
                    "format": "email",
                    "description": "Customer email exactly as registered.",
                },
                "status": {
                    "type": "string",
                    "enum": ["pending", "shipped", "delivered", "refunded"],
                    "description": "Optional status filter.",
                },
                "limit": {"type": "integer", "minimum": 1, "maximum": 50},
            },
            "required": ["customer_email"],
        },
    }
]

Invoke 전 모델 args validate·python

from jsonschema import Draft202012Validator

validator = Draft202012Validator(TOOLS[0]["input_schema"])

def invoke_tool(name: str, arguments: dict):
    spec = next(t for t in TOOLS if t["name"] == name)
    errors = list(Draft202012Validator(spec["input_schema"]).iter_errors(arguments))
    if errors:
        return {"error": "invalid arguments", "details": [e.message for e in errors]}
    return HANDLERS[name](**arguments)

Exercise

Ship한 tool 정의 하나 골라서 selection guidance 위해 description, missing constraint 위해 schema audit. Enum 하나, 숫자 bound 하나, rich description 문장 하나 최소 추가.

Hint

Description이 도구 NOT 쓸 때 언급 안 했으면 추가. Negative guidance가 잘못된 호출 줄여.

Tool 정의와 JSON Schema 규율

Tool당 필수 필드 셋

Description은 라벨 아니라 프롬프트

required, types, enum 가진 스키마

Code

External links

Exercise

Progress

댓글 0