도구 선택은 설명이, 입력 제약은 스키마가 맡아

정의 하나에는 세 필드가 필요해

도구 정의는 snake_case 식별자인 name, 무엇을 언제 하는지 적는 description, 인자 모양을 정하는 input_schema로 이뤄져. 모델은 이름만 보고 결정하지 않아. 설명으로 도구의 쓰임을 고르고 스키마로 호출 인자를 구성하므로 셋 모두 계약의 일부야.

설명은 작은 선택 프롬프트야

“Get the weather”처럼 기능 이름만 반복하면 언제 호출해야 하는지 알 수 없어. 현재 날씨와 24시간 예보를 돌려주며 온도·비·옷차림 질문에 쓰라고 적으면 선택 기준이 생겨. 설명에는 결과 범위와 사용 조건을 넣되 내부 경로나 비밀은 넣지 마.

스키마에는 실제 제약을 써

필수값은 required, 고정된 후보는 enum, 자료형은 type으로 드러내. 스키마가 구체적일수록 유효한 입력이 나올 가능성이 커져. 다만 정의 전체가 매 요청의 입력 토큰이 되므로 쓰지 않는 세부까지 과하게 늘리지는 마.

원칙: 이름과 설명은 도구 선택을, JSON Schema는 입력 제약을 맡아. 둘 다 프롬프트처럼 다듬어.

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

배포한 도구 정의 하나를 골라 설명의 선택 지침과 빠진 스키마 제약을 감사해. enum 하나, 숫자 범위 하나, 충실한 설명 문장 하나를 최소로 추가해.

Hint

도구를 쓰지 말아야 할 조건이 설명에 없다면 넣어. 부정 지침도 잘못된 호출을 줄여.

정의 하나에는 세 필드가 필요해

설명은 작은 선택 프롬프트야

스키마에는 실제 제약을 써

Code

External links

Exercise

Progress

댓글 0