도구 선언의 비용 — 도구는 매 호출마다 실려 간다

한 줄 요약

모델이 도구의 이름과 설명을 읽고 고른다는 말은, 모든 도구의 선언이 매 호출의 입력에 들어간다는 뜻입니다. 입력은 토큰이고 토큰은 비용입니다. 도구를 하나 더 붙이는 결정은 기능을 더하는 일이면서 모든 호출에 고정비를 더하는 일입니다.

2장에서 토큰(token) 은 모델이 글을 세는 단위이고, 요금이 토큰 수로 매겨진다는 것을 봤습니다.

도구와 아무 상관이 없는 인사 한마디를 세 가지 방식으로 보내고 입력 토큰을 쟀습니다. 이 교재를 준비하며 기본 모델로 잰 값입니다.

고객이 보낸 글은 세 번 모두 "안녕하세요" 다섯 글자입니다. 그런데 도구 네 개를 붙이자 입력이 2토큰에서 402토큰이 되었습니다. 늘어난 400토큰은 전부 도구의 이름과 독스트링입니다.

모델은 이 인사에 도구를 하나도 부르지 않습니다. 부르지 않아도 선언은 실려 갑니다. 도구를 쓸지 말지 판단하려면 읽어야 하기 때문입니다.

이 측정은 「실습문제와 해답」의 문제 1에서 직접 해 봅니다. 숫자는 독스트링의 길이에 따라 달라집니다.

위 표에서 도구 하나는 대략 100토큰입니다. 숫자 하나로는 작아 보입니다. 곱해 봅니다.

게다가 문의 한 건이 호출 한 번으로 끝나지 않습니다. 6장에서 본 것처럼 도구를 한 번 쓰면 모델을 두 번 부릅니다(도구 요청을 받는 호출, 결과를 넣어 답을 받는 호출). 두 번 모두 선언이 실려 갑니다.

도구가 늘면 고르는 일도 어려워집니다. 선택지가 넷일 때와 마흔일 때, 비슷한 설명이 섞여 있을 가능성이 다릅니다.

Gemini API 공식 문서는 한 번에 모델에게 보여 주는 도구를 10~20개 이내로 두라고 권합니다(2026년 10월 기준, 함수 호출 안내의 권장 사항).

지금 할 수 있는 일과 나중에 할 일을 나눕니다.

지금 — 필요한 도구만 만듭니다. "있으면 좋을 것 같은" 도구는 붙이지 않습니다. 이번 장의 도구는 네 개이고, 넷 모두 1장의 문의 로그에 나온 유형에 답하기 위한 것입니다.

나중에 — 도구가 계속 늘면 한 상담원에게 모든 도구를 주지 않습니다. 주문을 맡는 에이전트, 정책을 맡는 에이전트처럼 일을 나누고 각자에게 자기 일에 필요한 도구만 줍니다(21장). 여러 에이전트로 나누는 이유 중 하나가 이 토큰 비용입니다.

도구를 붙일 때는 "이 도구가 답하게 해 줄 질문이 실제로 들어오는가"를 먼저 묻습니다. 들어오지 않는 질문을 위한 도구는 매 호출의 비용만 됩니다.