9장. 도구를 쓰는 LLM 과 Agentic Workflow

도구 설명 쓰기

새로 온 직원에게 "이 서류함은 계약서용이고, 영수증은 넣지 마세요"처럼 쓸 때와 쓰지 않을 때를 함께 알려 주면 헷갈리지 않습니다. 모델도 도구의 설명을 읽고 고르므로, 설명이 곧 사용 설명서입니다.

흐린 설명과 또렷한 설명을 견준 두 카드. 또렷한 설명은 언제 쓰는지, 인자의 꼴, 예를 적는다

왼쪽은 "회의실 도구"처럼 흐린 설명, 오른쪽은 하는 일(빈 방 목록을 돌려준다), 인자의 꼴(HH:MM), 언제 쓰는지(예약 전에 먼저)를 적은 또렷한 설명입니다. 프로젝트에서 보겠지만, 흐린 설명과 짧은 지시로는 작은 모델이 없는 방 이름을 지어내고 시각을 틀리게 적습니다. 여기서 서류함의 쪽지가 도구 설명입니다.

설명에 넣을 것

넣을 것	흐린 예	또렷한 예
하는 일	회의실 도구	날짜와 시간에 비어 있는 회의실 이름 목록을 돌려준다
언제 쓰나	(없음)	예약하기 전에 반드시 먼저 쓴다
인자의 꼴	시간	시작 시각 HH:MM(24시간, 오후 2시는 14:00)
고를 수 있는 값	장비	화상회의, TV, 화이트보드 가운데 하나. 없으면 빈 글자

오류도 설명이다

도구가 돌려주는 오류 문구도 모델이 읽습니다. 무엇이 틀렸는지와 어떻게 고칠지를 적어 주면 모델이 다시 시도합니다.

Python

ROOMS = ["바다", "하늘", "숲", "들판", "별빛", "구름"]

def book_room(room, start, end):
    """설명용 예약 도구: 오류 문구에 고치는 법을 함께 적는다"""
    if room not in ROOMS:
        return {"오류": f"'{room}' 라는 방은 없습니다. 방 이름은 {', '.join(ROOMS)} 가운데 하나입니다."}
    if start >= end:
        return {"오류": f"시작 {start} 가 끝 {end} 보다 늦거나 같습니다. 24시간 꼴(오후 3시 = 15:00)로 적으세요."}
    return {"예약됨": room}

print(book_room("회의실A", "14:00", "15:00"))
print(book_room("숲", "16:00", "16:00"))

첫 줄은 "방 이름은 바다, 하늘, … 가운데 하나입니다", 둘째 줄은 "24시간 꼴로 적으세요"라는 고치는 법이 함께 나옵니다. 그냥 "실패"라고만 돌려주면 모델은 무엇을 고칠지 모릅니다.

코드에 나오는 함수

코드	쉬운 뜻
`"""설명용 예약 도구: ..."""`	함수 첫 줄의 설명 글(docstring, 문서 글자)이다. 사람이 읽는 메모다
`room not in ROOMS`	방 이름이 목록에 없으면 `True` 다
`', '.join(ROOMS)`	join 은 "잇다"라는 뜻이다. 목록의 이름들을 쉼표와 빈칸으로 이어 한 줄 글로 만든다
`start >= end`	시각 글자 둘을 견준다. 시작이 끝보다 늦거나 같으면 `True` 다
`return {"오류": ...}`	실패를 사전으로 돌려준다. 이 글이 그대로 tool 메시지가 되어 모델이 읽는다

이 코드가 뜻하는 것

은행 창구에서 서류를 냈는데 돌려받는 장면입니다. "안 됩니다"만 들으면 무엇을 고칠지 모르지만, "도장 칸이 비었습니다. 여기에 찍어 오세요"라고 들으면 바로 고칩니다. 여기서 창구 직원이 book_room, 돌려받는 말이 {"오류": ...} 의 글입니다.

줄	하는 일	쉽게 말하면
`ROOMS = [...]`	있는 방 이름 여섯 개	창구에 붙은 "받는 서류 목록"
`if room not in ROOMS:`	없는 방이면 오류와 방 이름 목록을 돌려준다	"그런 서류는 없어요. 이 가운데 고르세요"
`if start >= end:`	시각이 거꾸로면 오류와 바른 꼴을 돌려준다	"날짜를 거꾸로 쓰셨어요. 이렇게 쓰세요"
`return {"예약됨": room}`	문제가 없으면 예약한다	서류를 받아 처리한다
`print(book_room("회의실A", ...))`	없는 방으로 시험한다	틀린 서류를 일부러 내 본다

두 출력 모두 무엇이 틀렸는지와 바른 값이 함께 나옵니다. 모델은 이 글을 읽고 "회의실A" 대신 목록의 이름으로 다시 부를 수 있습니다.

시각을 글자로 견줄 때

start >= end 는 숫자가 아니라 글자를 견줍니다. 글자는 앞에서부터 한 글자씩 견주므로 적는 꼴이 중요합니다.

Python

# 시각을 글자로 견줄 때: 글자는 앞에서부터 한 글자씩 견준다
print("14:00" < "15:00")   # 두 자리로 맞춰 적으면 시각 순서와 같다
print("9:00" < "14:00")    # '9' 와 '1' 을 먼저 견주므로 틀린 답이 나온다
print("09:00" < "14:00")   # 앞에 0 을 붙여 두 자리로 맞추면 바르게 나온다

출력

True
False
True

결과	읽는 법
첫 줄 `True`	14시는 15시보다 이르다. 바른 답이다
둘째 줄 `False`	9시가 14시보다 이른데 `False` 가 나왔다. 첫 글자 '9' 가 '1' 보다 뒤라서다
셋째 줄 `True`	"09:00" 으로 적으면 첫 글자 '0' 과 '1' 을 견주어 바르게 나온다

그래서 도구 설명에 "시작 시각 HH:MM(24시간)"처럼 두 자리 꼴을 적어 둡니다. HH 는 시(hour) 두 자리, MM 은 분(minute) 두 자리라는 뜻입니다.

주의할 점

도구가 너무 잘게 나뉘면(방 목록, 빈 시간 확인, 예약이 따로) 작은 모델이 순서를 놓칩니다. 자주 함께 쓰는 일은 도구 하나로 묶는 편이 낫습니다.
도구 설명이 길어질수록 프롬프트가 길어집니다. 도구를 수십 개 주기보다 그 일에 필요한 몇 개만 줍니다.