AI 도구 호출 토큰 줄이기 — 켠다고 무조건 싸지지 않습니다

AI에게 도구를 여러 개 붙여 놓으면 도구가 돌려준 결과가 그대로 대화에 쌓여 요금이 불어납니다. 이걸 줄이는 방식이 있는데 — AI가 코드를 써서 도구를 부르고, 중간 결과는 맥락에 안 싣는 겁니다. 그런데 공식 문서가 자체 측정치를 공개해 뒀는데 아끼는 경우와 오히려 더 드는 경우가 갈렸습니다. 어디서 갈리는지 정리했습니다.

📌 30초 요약

• ★★중간 결과가 맥락에 안 들어갑니다 — 최종 출력만 들어가요.
• ★순차 작업에서는 오히려 더 듭니다 — 문서가 수치로 밝힙니다.
• ★답할 때 글을 같이 못 씁니다 — 결과 블록만 담아야 합니다.
• ⚠️ 기다리다 4분쯤에 시간 초과가 납니다.
• 못 쓰는 도구가 정해져 있습니다.
• 어디서 부를지 지정은 보안 경계가 아닙니다.

중간 결과가 맥락에 안 들어갑니다

동작 방식부터 보겠습니다. 도구가 필요하다고 판단되면 AI가 그 도구를 부르는 코드를 직접 써서 격리된 공간에서 돌립니다. 도구를 부르는 지점에서 코드가 잠깐 멈추고 내 쪽에 결과를 요청하죠. 결과를 돌려주면 코드가 이어서 돌고, 전부 끝난 뒤의 최종 출력만 AI가 받습니다.

핵심은 중간에 오간 도구 결과가 맥락에 안 실린다는 것입니다. 거르고 합치고 요약하는 처리가 모델 토큰을 안 쓰고 코드 안에서 끝나요. 도구를 열 번 부르는 작업이라면 직접 부를 때 대비 토큰이 크게 줄어드는 구조입니다. 게다가 도구들이 비동기 함수로 노출돼 여러 개를 한꺼번에 병렬로 부를 수도 있고요. 작업 절차서를 만들어 도구를 늘려가는 흐름이라면, 도구가 많아질수록 이 방식의 이득이 커집니다.

켠다고 무조건 싸지지 않습니다

문서가 자체 측정 결과를 세 가지나 공개해 뒀는데, 여기가 이 글의 핵심입니다. 한 경우에는 비용이 오히려 늘었어요.

어떤 작업	결과
도구를 일흔 개 넘게 붙인 업무 관리	입력 토큰 약 38% 감소, 정확도는 그대로
차례마다 한두 번씩 순서대로 부르는 작업	점수는 그대로, 비용은 약 8% 증가
도구 정의가 열 개~쉰 개쯤인 실제 요청들	보통 20~40% 절감
판단 기준	켜고 끄고 각각 재본 뒤 넓게 적용

둘째 줄이 이 방식의 성격을 말해줍니다. 앞 결과를 보고 AI가 생각해야 다음 호출을 정할 수 있는 작업이면, 코드로 감싸도 모델을 한 번 거치는 단계를 못 건너뜁니다. 이득은 없고 공간을 띄우고 코드를 짜는 비용만 남죠. 반대로 여러 항목에 한꺼번에 펼치는 작업, 큰 결과를 걸러 넣어야 하는 작업, 찾고 추리기를 반복하는 작업은 잘 맞습니다. 문서의 조언도 명확해요 — 확신이 없으면 대표 표본으로 켜고 끄고 각각 재본 뒤에 넓게 적용하라. 도구별 요금과 토큰 한도를 비교해 두었다면 이 측정을 붙이기가 훨씬 수월합니다.

답할 때 글을 같이 못 씁니다

구현할 때 바로 걸리는 제약입니다. 코드가 도구 결과를 기다리는 중이라면, 돌려보내는 메시지에 결과 블록만 담아야 하고 글은 한 줄도 못 붙입니다. "이제 뭐 할까?" 같은 말을 결과 뒤에 붙이면 거절돼요. 일반 도구 호출에서는 되던 것이라 더 헷갈립니다.

내용 형식도 좁습니다 — 글자만 됩니다. 이미지나 문서 같은 블록은 거부돼요. 그리고 시간 제약이 둘 있습니다. 코드가 결과를 기다리는 동안 4분쯤 지나면 시간 초과가 나고, 격리 공간 자체도 가만두면 5분쯤 뒤 회수됩니다. 결과를 돌려줄 때는 그 공간의 번호를 반드시 함께 보내야 하고요 — 평소엔 선택이지만 기다리는 중일 때는 없으면 거절됩니다.

⚠️ 결과가 코드로 해석된다는 뜻

도구가 돌려주는 값은 글자 그대로 코드 안으로 들어갑니다. 그래서 문서가 경고를 답니다 — 바깥에서 가져온 자료나 사용자 입력이 섞여 있다면, 그게 코드로 해석될 위험을 염두에 두고 검증하라는 것. 도구 결과를 한 번 걸러서 넘기라는 주입 방어 원칙이 여기서는 보안뿐 아니라 실행 안전 문제가 됩니다.

못 쓰는 도구가 정해져 있습니다

전부 되는 게 아닙니다. 연결기로 붙여 쓰는 외부 도구는 이 방식으로 못 부르고, 화면을 보고 조작하는 도구와 브라우저를 다루는 도구도 직접 호출만 됩니다. 틀을 엄격하게 강제하는 도구와도 병용이 안 되고, 특정 도구를 강제로 지정하는 것도, 병렬 호출을 끄는 설정도 못 씁니다.

입력 정의에도 조건이 있습니다. 자기 자신을 다시 가리키는 순환 구조가 들어 있으면 요청이 거절됩니다 — 흥미로운 건 직접 호출로는 같은 정의가 그대로 통과한다는 점이에요. 문서는 그 도구만 직접 호출로 남기거나, 순환을 정해진 깊이까지 펼치고 더 깊은 부분은 설명으로 적으라고 안내합니다.

마지막으로 오해하기 쉬운 것 하나. "이 도구는 코드에서만 부르게 하라"는 지정은 안내일 뿐 하드 차단이 아닙니다. 문서가 보안 경계로 삼지 말라고 명시해요. 강하게 유도되긴 하지만 직접 호출이 올 수 있으니, 내 프로그램은 어느 쪽이든 처리할 준비가 돼 있어야 합니다.

자주 묻는 질문 (FAQ)

Q. 중간 결과는 요금에 아예 안 잡히나요?

문서가 명시합니다 — 코드에서 부른 도구의 결과는 입력·출력 사용량에 안 들어가고, 최종 실행 결과와 이어지는 답변만 잡힙니다. 다만 코드를 돌리는 자체 비용은 별도로 붙습니다.

Q. 도구를 어떻게 만들어야 잘 맞나요?

코드가 결과를 풀어서 다뤄야 하니, 돌려주는 형식을 설명에 자세히 적고 기계가 읽기 좋은 구조로 주는 게 좋습니다. 그리고 필요한 것만 짧게 돌려주세요.

Q. 호출 횟수 제한은 어떻게 계산되나요?

코드에서 부른 것도 한 번씩 따로 셉니다. 일반 호출과 같은 제한이 적용돼요. 토큰은 아껴도 호출 수는 그대로라는 뜻이라, 여러 항목에 펼칠 때는 이쪽을 먼저 확인하세요.

Q. 어느 호출이 코드에서 나온 건지 구분되나요?

네. 호출마다 어디서 불렀는지 표시가 붙어 옵니다. 코드에서 나온 경우엔 어느 실행에서 나온 것인지 가리키는 값까지 있어서 짝을 맞출 수 있습니다.

✨ 정리하면

이 방식은 고정 비용을 조금 내고 도구 결과 토큰을 크게 아끼는 맞바꿈입니다. 그래서 도구가 많고 결과가 크고 여러 개를 한꺼번에 펼치는 작업에서 이득이 나고, 앞 결과를 보고 다음을 정해야 하는 순차 작업에서는 오히려 손해입니다. 켜기 전에 대표 표본으로 한 번 재보세요. 비용 설계 전체 흐름은 AI 지출 관리 허브에 단계별로 정리해 두었습니다.

출처: Claude 공식 문서 「코드에서 도구 부르기」 (2026-09-01 열람). 본문의 절감·증가 수치는 문서가 공개한 자체 평가 결과이며, 실제 효과는 작업 형태에 따라 달라집니다. 지원 모델과 플랫폼에 제한이 있습니다.