제미나이 API 툴 리트리벌 사용법 — 도구 스키마는 쓸 때만, 별도 요금은 없다
Google added Tool Retrieval to the Gemini API in preview on November 19, 2026. It works only in the Interactions API (v1beta): add a tool_search tool and set defer_loading: true on function tools or a remote MCP server, and the model sees just each tool's name and description until it asks for a full schema. There is no surcharge, but loaded schemas are billed as input for the rest of the conversation and the tools array must be resent on every request. Google published no token-savings, accuracy or latency figures at launch.
제미나이 API의 툴 리트리벌(Tool Retrieval)은 에이전트에 단 도구의 매개변수 스키마를 처음부터 다 보내지 않고, 모델이 필요하다고 판단한 도구만 요청 시점에 불러오는 기능이다. 구글이 2026년 11월 19일 프리뷰로 공개했고 Interactions API(v1beta)에서만 동작한다. 켜는 방법은 두 가지다. tools 배열에 tool_search 도구를 넣고, 미뤄 둘 함수 도구나 원격 MCP 서버에 defer_loading: true를 준다. 별도 요금은 없고 호출한 모델의 표준 입력·출력 토큰 요금이 그대로 적용된다. 다만 공짜는 아니다. 한 번 불러온 스키마는 대화가 끝날 때까지 입력 토큰으로 과금되고, tools 배열은 요청마다 다시 보내야 한다. 구글은 출시 시점에 토큰 절감률, 정확도, 지연 시간 수치를 공개하지 않았다.
3줄 요약
- 켜는 법 — Interactions API(v1beta) 요청의 tools에 tool_search를 넣고, 미룰 함수나 원격 MCP 서버에 defer_loading: true. generateContent에서는 지원하지 않는다
- 비용 — 별도 요금 없이 표준 토큰 요금. 불러온 스키마는 대화 끝까지 입력으로 과금되고 내릴 수 없다. tools 배열은 매 요청 다시 보낸다
- 한계 — 프리뷰이며 정식 출시일 미정. 구글은 절감률·정확도·지연 수치를 내지 않았다. 도구가 적거나 대부분을 매번 쓰는 에이전트는 이득이 없을 수 있다
핵심 질문
- 제미나이 API 툴 리트리벌 사용법
- **Interactions API 요청의 tools에 `tool_search` 도구를 넣고, 미뤄 둘 도구에 `defer_loading: true`를 준다.** | 단계 | 할 일 | 비고 | |---|---|---| | 1 | API 확인 | Interactions API, v1beta. generateContent는 미지원 | | 2 | 검색 도구 추가 | tools에 type이 tool_search인 항목 하나 | | 3 | 미룰 도구 표시 | 함수 도구마다 defer_loading: true | | 4 | MCP 서버 통째로 미루기 | mcp_server 도구에 defer_loading: true. 원격 서버만 | | 5 | 자주 쓰는 도구 | 미루지 않고 그대로 둔다(구글 권고) | | 6 | 결과 확인 | interaction.steps에서 tool_search_call, tool_search_result, function_call 순서를 본다 |
- 제미나이 툴 리트리벌 가격
- **별도 요금은 없다. 호출한 모델의 표준 입력·출력 토큰 요금이 적용된다. 다만 토큰을 안 쓰는 기능은 아니다.** | 비용 항목 | 내용 | 근거 | |---|---|---| | 기능 사용료 | 없음 | 구글 블로그 | | tool_search 블록 | 작은 고정 토큰. 크기 미공개 | 구글 블로그 | | 미룬 도구의 목록 줄 | 도구마다 이름과 짧은 설명. 초기 시험에서 약 26토큰 | PPC랜드가 문서를 인용(단일 출처) | | 불러온 스키마 | 그 뒤 대화 끝까지 입력 토큰으로 과금 | 네 출처 일치 | | 서버 측 검색 | 추가 모델 호출 1회분. total_tool_use_tokens로 집계, 입력 요금 | 아이스쿠프·PPC랜드 |
- 툴 리트리벌 지원 모델
- **구글 블로그는 제미나이 3.6 이상과 제미나이 4 전 모델이라고 적었다. 문서에 적힌 모델 코드는 네 개라는 보도가 있어 목록이 엇갈린다.** | 출처 | 지원 모델 표기 | |---|---| | 구글 블로그(2026-11-19) | 제미나이 3.6 이상, 제미나이 4 전 모델 포함 | | PPC랜드가 인용한 문서 | gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash, gemini-3.6-flash. 그 밖의 모델은 400 오류 | | 아이스쿠프 | 3.6 플래시, 3.8 플래시, 제미나이 4 네 종(하이드로젠·네온·아르곤·카본) | | 이 기사의 판단 | 미해결. 쓰려는 모델 코드로 직접 호출해 확인할 것 |
제미나이 API의 툴 리트리벌(Tool Retrieval)은 에이전트에 단 도구의 스키마를 처음부터 다 보내지 않고, 모델이 쓰겠다고 한 도구만 그때 불러오는 기능이다. 구글이 2026년 11월 19일 프리뷰로 공개했다. 켜는 방법은 요청의 tools 배열에 tool_search 도구를 넣고, 미뤄 둘 도구에 defer_loading: true를 주는 것이다. 별도 요금은 없다.
도구가 5개인 에이전트에는 필요 없는 기능이다. 도구가 100개, 200개로 늘어난 에이전트에서 문제가 생긴다. 도구마다 붙는 매개변수 정의(스키마)가 요청마다 통째로 입력에 들어가기 때문이다. 쓰지도 않는 도구의 설명서를 매번 돈 내고 읽히는 셈이다. 이 글은 어떻게 켜는지, 얼마나 줄어드는지, 그리고 언제 오히려 손해인지를 구글 블로그 글과 이를 분석한 보도 세 곳을 대조해 정리한다. 구글이 밝히지 않은 숫자와 출처끼리 엇갈리는 대목은 따로 표시했다.
1. 어떻게 켜나 — tool_search 하나와 defer_loading: true
구글 블로그 글과 PPC랜드, 아이스쿠프, 알파시그널 네 곳이 같은 설정을 적었다.
| 항목 | 값 | 설명 |
|---|---|---|
| 공개일 | 2026년 11월 19일 | 프리뷰. 정식 출시일은 없다 |
| 쓸 수 있는 API | Interactions API | v1beta 버전. generateContent는 지원하지 않는다(PPC랜드·아이스쿠프) |
| 검색 도구 | tools에 type이 tool_search인 항목 | 요청당 하나만(PPC랜드) |
| 미룰 함수 | 함수 도구에 defer_loading: true | 모델에는 이름과 설명만 보인다 |
| 미룰 MCP 서버 | mcp_server 도구에 defer_loading: true | 그 서버의 도구 전부가 미뤄진다. 원격 서버만 |
| 짧은 설명 | short_description (선택) | 목록에 전체 설명 대신 이 문장이 들어간다(PPC랜드) |
| 호출 | client.interactions.create(model, input, tools) | 샘플의 모델은 gemini-4-hydrogen |
| 글쓴이 | 루시아 로어(제미나이 API 제품 매니저), 노라 카스너(구글 딥마인드 연구원) | 구글 블로그 |
아래는 출처들이 보여 준 공식 샘플을 요약한 형태다. tool_search, defer_loading, mcp_server 외의 필드는 자리 표시이므로 그대로 실행되는 코드가 아니다.
요청의 tools 배열에는 네 가지가 들어간다.
- 검색 도구:
{"type": "tool_search"}. 이것이 있어야 미룬 도구를 불러온다 - 자주 쓰는 함수 도구:
"type": "function"에name,description,parameters만 적고 미루지 않는다 - 가끔 쓰는 함수 도구: 같은 선언에
"defer_loading": True를 더해 스키마를 미룬다 - 원격 MCP 서버:
"type": "mcp_server"선언에"defer_loading": True를 주면 그 서버의 도구 전부를 미룬다(주소 등 나머지 필드는 문서 참조)
호출은 client.interactions.create(model="gemini-4-hydrogen", input=..., tools=tools) 형태다.
요청을 보내면 한 번의 요청 안에서 다음이 일어난다.
| 순서 | 누가 | 무엇을 | steps에 남는 이름 |
|---|---|---|---|
| 1 | 개발자 | tool_search와 미룬 도구를 담아 요청 | — |
| 2 | 모델 | 미룬 도구의 이름과 설명만 본다. 매개변수는 보지 못한다 | — |
| 3 | 모델 | 필요한 도구를 지목해 검색을 요청. 인자는 함수 이름 목록 형태 | tool_search_call |
| 4 | API | 지목된 도구의 전체 선언(매개변수 포함)을 돌려준다 | tool_search_result |
| 5 | 모델 | 불러온 스키마에 맞춰 함수를 호출 | function_call |
| 6 | 개발자 코드 | 함수를 실행하고 결과를 돌려준다 | function_result |
3~5번은 요청 하나 안에서 끝나고, 모든 단계가 interaction.steps에 남는다. PPC랜드는 문서에 적힌 '검색'이 실제로는 모델이 이미 들고 있는 목록에서 고르는 선택에 가깝다고 짚었다. 모델이 보는 목록의 한 줄은 도구 이름과 short_description, 그것이 없으면 설명의 첫 문장이다. 그래서 설명의 첫 문장이 그 도구가 선택되느냐를 좌우한다. 도구 설명을 "주문 관련 함수" 식으로 뭉뚱그려 쓴 조직은 이 기능을 켜기 전에 설명부터 고쳐야 한다.
검색을 구글 서버가 아니라 내 쪽에서 돌리는 방식도 있다.
| 구분 | 서버 측(기본) | 클라이언트 측 |
|---|---|---|
| 설정 | {"type": "tool_search"} | tool_search에 "execution": "client"와 name, description, parameters를 함께 정의 |
| 검색을 돌리는 곳 | 구글 | 내 애플리케이션 |
| 준비할 것 | 없음. 색인을 만들거나 띄울 필요가 없다 | 도구를 찾아 돌려주는 조회 로직 |
| 할 수 있는 것 | 크고 변하지 않는 도구 묶음에 적합 | 사용자별 접근 권한 적용, 대화 도중 도구 추가 |
| 대가 | 검색마다 추가 모델 호출(아이스쿠프·PPC랜드) | 검색마다 왕복 한 번이 더 든다 |
| MCP 서버 통째로 미루기 | 가능 | 불가(아이스쿠프) |
| 섞어 쓰기 | 한 요청에서 두 방식을 섞을 수 없다 | 같음 |
알파시그널은 클라이언트 측 방식을 쓰더라도 도구를 실행하는 시점의 권한 확인과 감사 기록은 따로 필요하다고 덧붙였다. 목록에서 안 보이게 하는 것과 실행을 막는 것은 다른 일이다.
2. 얼마나 줄어드나 — 구글은 숫자를 내지 않았다
먼저 확인된 것과 아닌 것을 가른다. 구글은 출시 시점에 토큰 절감률, 도구 선택 정확도, 지연 시간의 측정값을 하나도 공개하지 않았다. 돌아다니는 숫자는 출처가 제각각이다.
| 숫자 | 누가 말했나 | 성격 |
|---|---|---|
| 유휴(미룬) 도구 하나당 약 26토큰 | PPC랜드가 구글 문서의 초기 시험 수치로 인용 | 단일 출처. 구글 블로그 글에는 없다 |
| 도구 100개를 미루면 요청당 약 2,600토큰, 약 0.004달러 | PPC랜드 | 위 26토큰에 입력 100만 토큰당 1.50달러를 곱한 자체 계산 |
| 도구 150개 예시 240,000 → 19,800토큰, 92% 감소 | 아이스쿠프 필자 | 구글 수치가 아닌 자체 계산. 필자의 가정으로 재계산해도 정확히 재현되지 않았다 |
| 도구 5개 예시 8,000 → 8,100토큰 | 아이스쿠프 필자 | 자체 계산. 작은 에이전트는 오히려 늘 수 있다는 예 |
| 도구 스키마 하나 평균 300~600토큰 | 아이스쿠프가 제3자(Unblocked, 2026년 5월) 인용 | 구글과 무관한 추정 |
| MCP 서버 5개의 도구 정의 약 55,000토큰 | 아이스쿠프가 앤트로픽 추정치로 인용 | 타사 수치 |
26토큰과 2,600토큰의 관계는 검산이 된다. 26 × 100 = 2,600토큰이고, 100만 토큰당 1.50달러면 2,600 × 1.50 ÷ 1,000,000 = 0.0039달러다.
감을 잡기 위해 직접 계산해 본다. 아래는 이 기사가 가정을 세워 한 산수이며 실측이 아니다. 가정은 넷이다. 도구 150개, 스키마 하나 400토큰(위 300~600 추정의 중간), 미룬 도구의 목록 줄 26토큰, 대화 4턴 동안 도구 2개를 첫 턴에 불러와 끝까지 쓴다. 크기가 공개되지 않은 tool_search 블록과 검색에 드는 추가 모델 호출은 뺐다.
| 항목 | 전부 미리 보낼 때 | 전부 미룰 때 |
|---|---|---|
| 요청당 도구 정의 | 150 × 400 = 60,000토큰 | 목록 150 × 26 = 3,900토큰 |
| 4턴 합계 | 60,000 × 4 = 240,000토큰 | 3,900 × 4 = 15,600토큰 |
| 불러온 스키마 2개 | 위에 포함 | 2 × 400 × 4 = 3,200토큰 |
| 합계 | 240,000토큰 | 18,800토큰 + 검색 블록·검색 호출분 |
| 입력 요금(100만 토큰당 1.50달러 가정) | 0.36달러 | 약 0.03달러 + α |
이 가정에서는 도구 정의에 드는 입력이 92% 안팎 줄어든다. 아이스쿠프의 92%와 방향은 같다. 다만 이 표가 보여 주는 것은 절감률이 아니라 절감이 어디서 나오는가다. 이득은 "안 불러온 스키마"에서만 나온다. 150개 가운데 2개를 쓰는 대화라서 큰 것이고, 150개 가운데 100개를 쓰는 대화라면 표의 오른쪽 열은 왼쪽과 비슷해지고 검색 비용만 더해진다. 구글도 같은 말을 한다. 불러오지 않은 스키마가 불러온 것보다 많을 때 이득이 나며, 실제 트래픽으로 재 보라는 것이다.
캐싱과의 관계도 짚어 둘 만하다. 구글 블로그와 알파시그널은 스키마를 미루면 프롬프트 앞부분이 요청마다 같게 유지돼 프리픽스 캐싱이 계속 먹힌다고 적었다. 반대 방향의 주의도 있다. 아이스쿠프는 중간 크기 프롬프트에서 스키마를 미루면 전체 길이가 캐싱 최소 길이 밑으로 내려가 캐시 할인을 못 받게 될 수 있다고 지적했다. 캐시 할인의 원리는 2026년 9월 5일 자 「프롬프트 캐싱이란 — 두 번째부터 입력이 40분의 1 값이 된다」에서 다뤘다.
3. 가격 — 별도 요금은 없지만 네 군데서 토큰이 나간다
네 출처가 일치하는 것은 "기능 자체의 요금은 없고, 호출한 모델의 표준 입력·출력 요금이 적용된다"는 점이다. 그 표준 요금이 붙는 자리가 네 곳이다.
| 토큰이 나가는 곳 | 언제 | 얼마나 | 근거 |
|---|---|---|---|
| tool_search 블록 | 매 요청 | 작은 고정 크기. 숫자 미공개 | 구글 블로그 |
| 미룬 도구의 목록 줄 | 매 요청 | 도구 수 × 약 26토큰 | PPC랜드(문서 인용) |
| 불러온 스키마 | 불러온 뒤 대화 끝까지 매 요청 | 스키마 크기 그대로 | 네 출처 일치 |
| 서버 측 검색 | 검색할 때마다 | 추가 모델 호출 1회분. total_tool_use_tokens로 보고되고 입력 요금으로 과금 | 아이스쿠프·PPC랜드 |
세 번째 줄이 이 기능의 요금 구조에서 가장 중요하다. 한 번 불러온 스키마는 내릴 수 없다(PPC랜드). 처음부터 선언한 도구와 똑같이 남은 대화 내내 입력으로 계산된다. 대화가 길어지면서 이 도구 저 도구를 하나씩 불러오다 보면 후반부 요청은 미루지 않은 것과 비슷해진다. 긴 대화를 하는 에이전트일수록 절감률은 초반 몇 턴의 숫자보다 낮게 나온다.
네 번째 줄은 출처 사이에 온도 차가 있다. 구글 블로그 글은 검색이 "한 번의 API 호출 안에서" 일어난다고만 적었고 추가 호출 비용은 언급하지 않았다. 아이스쿠프와 PPC랜드는 문서를 근거로 서버 측 검색마다 모델 호출이 한 번 더 들어간다고 적었다. 사용량 응답의 total_tool_use_tokens 값을 직접 확인하는 것이 가장 확실하다.
제미나이 4 하이드로젠의 토큰 단가는 2026년 11월 16일 자 「제미나이 4 하이드로젠 가격 — 무료로 쓰지만 고를 수는 없다, API는 3.8 플래시의 2배」에 정리해 두었다.
4. 언제 손해인가 — 켜기 전에 볼 다섯 가지
툴 리트리벌은 켠다고 무조건 이득인 스위치가 아니다. 출처들이 짚은 손해 구간과 함정을 모았다.
| 상황 | 왜 손해인가 | 누가 말했나 |
|---|---|---|
| 도구가 몇 개뿐인 에이전트 | 미뤄서 아끼는 양보다 검색 블록과 검색 호출이 더 크다. 함수 4개짜리는 이득을 보기 어렵다 | 알파시그널, 아이스쿠프(5개 예시) |
| 안정적인 도구가 20개 미만 | 그냥 다 선언하는 편이 낫다 | 아이스쿠프의 권고 |
| 대화마다 도구 대부분을 쓰는 에이전트 | 어차피 다 불러오게 되고 검색 비용만 얹힌다 | 아이스쿠프 |
| 자주 쓰는 도구까지 미룬 경우 | 매 대화에서 검색을 한 번 더 거친다 | 구글 블로그(자주 쓰는 도구는 미루지 말라) |
| 클라이언트 측 검색 | 검색마다 왕복이 한 번 늘어 응답이 느려진다 | 네 출처 일치 |
맞는 형태는 반대쪽이다. 알파시그널이 든 예는 핵심 도구 5개에 가끔 쓰는 도구 50개가 붙은 에이전트다. 핵심 5개는 그대로 두고 50개만 미룬다.
비용 말고 동작에서 걸리는 함정도 있다.
| 함정 | 무슨 일이 생기나 | 대처 |
|---|---|---|
| tools 배열 재전송 | previous_interaction_id로 대화를 이어도 도구 선언은 다음 요청으로 넘어가지 않는다 | 요청마다 tools 배열 전체를 다시 보낸다(PPC랜드가 문서를 인용) |
| 시스템 지시문에 이름이 적힌 도구 | 모델이 검색 없이 곧장 호출하려 들고, 다음 요청이 Server side tool call context must be circulated로 시작하는 오류로 실패한다 | 시스템 지시문이나 다른 도구의 출력에 이름이 나오는 도구는 미루지 않는다 |
| 검색 결과 없음 | 구조화된 오류가 아니라 글로 된 응답이 돌아온다 | 오류 코드가 아닌 본문으로 판별해야 한다 |
| 불러온 스키마 | 내릴 수 없다 | 긴 대화는 세션을 나누는 설계를 검토한다 |
| 프리뷰 | 정식 출시 전에 API 형태가 바뀔 수 있다 | 운영 코드에 넣을 때 변경 가능성을 감안한다 |
| 지원 밖 모델 | 400 오류(PPC랜드가 문서를 인용) | 쓰려는 모델 코드로 먼저 호출해 본다 |
지연 시간에 대해서는 구글 블로그 글 안에서도 표현이 갈린다. 요약 상자는 이 기능이 지연을 줄인다고 적었고, 본문은 도구가 많을수록 지연이 늘어난다는 일반론을 적었다. 측정값은 어느 출처에도 없다. 입력이 줄면 처리가 빨라지는 쪽과 검색 단계가 하나 더 끼는 쪽이 서로 반대 방향으로 작용하므로, 결과는 재 봐야 안다.
5. MCP 서버와 지원 모델 — 서버째 미룰 수 있고, 모델 목록은 엇갈린다
MCP(모델 컨텍스트 프로토콜) 서버는 도구를 묶음으로 내놓는 표준 창구다. 서버 하나를 붙이면 도구 수십 개가 한꺼번에 따라온다. 도구 스키마가 불어나는 가장 흔한 경로가 이것이다. 원리는 2026년 8월 28일 자 「MCP란 — AI에게 도구를 연결하는 표준, 왜 USB-C에 비유되나」에서 다뤘다.
툴 리트리벌은 mcp_server 도구에 defer_loading: true를 주면 그 서버의 도구 전부를 미룬다. 조건이 둘 있다. 원격 MCP 서버만 되고(네 출처 일치), 서버 측 검색에서만 된다(아이스쿠프). 아이스쿠프에 따르면 이 경우 도구 실행도 API가 직접 하고 mcp_server_tool_call과 mcp_server_tool_result 단계로 보고한다. PPC랜드는 Interactions API의 원격 MCP 지원 자체가 2026년 7월 7일에 추가됐다고 적었다.
지원 모델은 출처가 엇갈린다.
| 출처 | 표기 | 빠지거나 더해진 것 |
|---|---|---|
| 구글 블로그 | 제미나이 3.6 이상, 제미나이 4 전 모델 포함 | 모델 코드 없음 |
| 알파시그널 | 구글 블로그와 같음 | — |
| PPC랜드(문서 인용) | gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash, gemini-3.6-flash | 제미나이 4 카본, 3.7 플래시가 없다. 그 밖의 모델은 400 오류 |
| 아이스쿠프 | 3.6 플래시, 3.8 플래시, 제미나이 4 네 종 | 네온과 카본을 포함해 적었다 |
"제미나이 4 전 모델"이라는 블로그 표현과 "코드 네 개"라는 문서 인용은 그대로는 양립하지 않는다. 제미나이 4 네온 같은 새 모델이 문서 목록에 아직 반영되지 않았을 수도 있고, 블로그 표현이 넓게 쓰인 것일 수도 있다. 어느 쪽인지 이 기사는 확인하지 못했다. 쓰려는 모델 코드로 직접 호출해 400이 나는지 보는 것이 가장 빠르다.
6. 앤트로픽·오픈AI와 비교 — 같은 플래그, 구글이 세 번째
구글 블로그 글은 다른 회사를 언급하지 않았다. 아래 비교는 PPC랜드와 아이스쿠프가 정리한 것이다.
| 회사 | 기능 | 공개 시점 | 미루는 플래그 | 회사가 밝힌 수치 |
|---|---|---|---|---|
| 앤트로픽 | Tool Search Tool | 2025년 11월 24일(베타) | defer_loading: true | 토큰 85% 감소(약 77,000 → 8,700). 도구 선택 정확도 오퍼스 4 49% → 74%, 오퍼스 4.5 79.5% → 88.1% |
| 오픈AI | tool search | 2026년 3월 5일(GPT-5.4와 함께) | 같은 플래그 | MCP 서버 36개, 과제 250개에서 토큰 47% 감소 |
| 구글 | Tool Retrieval | 2026년 11월 19일(프리뷰) | defer_loading: true | 공개하지 않음 |
세 가지를 읽어야 한다. 첫째, 세 회사가 같은 이름의 플래그를 쓴다. 한 회사용으로 정리한 도구 목록과 설명을 다른 회사 API로 옮기기가 그만큼 쉬워졌다. 둘째, 표의 수치는 각 회사가 자기 시험으로 낸 것이어서 서로 직접 비교할 수 없다(PPC랜드). 오픈AI의 47%는 출처에 따라 설명도 다르다. 아이스쿠프는 정확도가 같은 조건의 벤치마크 결과로, PPC랜드는 내부 시험 결과로 적었다. 셋째, 눈여겨볼 것은 절감률보다 정확도 숫자다. 앤트로픽의 수치대로라면 도구를 수십 개씩 한꺼번에 보여 줄 때 모델은 절반 가까이 엉뚱한 도구를 골랐다는 뜻이 된다. 도구 지연 로딩은 비용 기능이기 전에 모델이 헷갈리지 않게 하는 장치다. 구글이 이 정확도 수치를 내지 않은 것이 이번 발표에서 가장 큰 빈칸이다.
모델이 한 번에 볼 수 있는 분량이 왜 넉넉해도 다 쓰면 안 되는지는 2026년 8월 14일 자 「컨텍스트 윈도우란 — 100만 토큰을 다 읽지는 않는다」에서 다뤘다.
7. 자주 묻는 질문
generateContent를 쓰고 있다. 그대로 쓸 수 있나. 쓸 수 없다. PPC랜드와 아이스쿠프에 따르면 툴 리트리벌은 Interactions API(v1beta)에서만 동작하고 generateContent는 지원하지 않는다. 이 기능을 쓰려면 호출부를 Interactions API로 옮겨야 한다.
무료인가. 기능 사용료는 없다. 하지만 토큰이 들지 않는다는 뜻은 아니다. 검색 블록, 미룬 도구의 목록 줄, 불러온 스키마, 서버 측 검색 호출에 표준 토큰 요금이 붙는다.
도구가 몇 개부터 켜는 게 좋은가. 구글이 제시한 기준 개수는 없다. 아이스쿠프는 안정적인 도구가 20개 미만이면 그냥 다 선언하라고 권했고, 알파시그널은 함수 4개짜리 에이전트는 이득을 보기 어렵다고 적었다. 구글의 기준은 개수가 아니라 비율이다. 불러오지 않는 스키마가 불러오는 것보다 많아야 한다.
어떤 도구를 미루고 어떤 도구를 남기나. 자주 쓰는 도구는 남긴다(구글 권고). 시스템 지시문이나 다른 도구의 출력에 이름이 나오는 도구도 남긴다. 미뤄 두면 모델이 검색을 건너뛰고 호출하려다 오류가 난다. 가끔 쓰는 긴 꼬리 도구가 미룰 대상이다.
대화 중간에 도구 목록을 바꿀 수 있나. 클라이언트 측 검색이면 대화 도중 도구를 추가할 수 있다. 사용자마다 접근 권한이 다른 서비스도 이 방식이 맞다. 서버 측 검색은 크고 변하지 않는 도구 묶음에 맞는다.
불러온 스키마를 대화 중에 다시 내릴 수 있나. 없다. 한 번 불러오면 그 대화가 끝날 때까지 입력으로 계산된다.
previous_interaction_id로 대화를 이으면 tools를 안 보내도 되나. 안 된다. PPC랜드가 인용한 문서에 따르면 도구 선언은 요청 사이에 이어지지 않는다. 요청마다 tools 배열 전체를 다시 보내야 한다.
로컬에서 띄운 MCP 서버도 미룰 수 있나. 출처들이 확인한 것은 원격 MCP 서버뿐이다. 그것도 서버 측 검색에서만 된다.
운영 서비스에 넣어도 되나. 프리뷰 단계이고 정식 출시일이 없다. PPC랜드는 정식 출시 전에 API 형태가 바뀔 수 있다고 적었다. 넣는다면 켜고 끄는 스위치를 두고, 켜기 전후의 입력 토큰과 도구 선택 오류율을 같은 트래픽으로 비교하는 것이 순서다.
8. 남은 것과 확인되지 않은 것
| 항목 | 확인된 것 | 확인되지 않은 것 |
|---|---|---|
| 공개 | 2026년 11월 19일 프리뷰, Interactions API 전용 | 정식 출시일 |
| 설정 | tool_search 추가, defer_loading: true (네 출처 일치) | 구글 문서 원문과의 직접 대조 |
| 지원 모델 | 블로그: 3.6 이상과 제미나이 4 전 모델 | 문서의 코드 네 개와 왜 다른지. 카본·네온·3.7 플래시의 실제 동작 |
| 유휴 도구 비용 | 약 26토큰이라는 PPC랜드의 문서 인용 | 구글 블로그에는 없는 숫자. 도구 설명 길이에 따른 편차 |
| 절감률 | 구글 발표 수치 없음 | 92%는 아이스쿠프 자체 계산, 이 기사의 표도 가정에 따른 산수 |
| 정확도 | 구글 발표 수치 없음 | 제미나이에서 도구 선택이 얼마나 나아지는지 |
| 지연 | 측정값 없음 | 입력 감소와 검색 단계 추가 가운데 어느 쪽이 큰지 |
| 검색 방식 | 모델이 이름과 설명을 보고 지목한다 | 서버 측 매칭의 내부 방식. 알파시그널만 의미 검색이라고 적었다 |
| 검색 비용 | 추가 모델 호출로 집계된다는 두 곳의 문서 인용 | 구글 블로그는 언급하지 않았다 |
| 검색 블록 크기 | 작은 고정 블록 | 토큰 수 |
| 도구 수 상한 | 명시된 상한 없음 | 실제 한계 |
| 타사 수치 | 앤트로픽 85%·오픈AI 47%라는 보도 | 두 회사 원문. 서로 비교 가능한 조건인지 |
정리하면 순서는 이렇다. 호출부가 Interactions API인지 확인한다. 도구를 자주 쓰는 것과 가끔 쓰는 것으로 나눈다. 가끔 쓰는 쪽에만 defer_loading: true를 주고 tool_search를 넣는다. 각 도구 설명의 첫 문장을 그 도구가 무엇을 하는지 한 줄로 알 수 있게 고친다. 그리고 켜기 전후의 입력 토큰과 total_tool_use_tokens를 실제 트래픽으로 비교한다. 구글이 숫자를 내지 않았으므로 절감률은 각자 재는 수밖에 없다.
에이전트에게 도구를 쥐여 준다는 것이 무슨 뜻인지는 2026년 8월 26일 자 「AI 에이전트란 — 도구를 쥐여주면 무엇이 달라지나」에서, 도구를 묶어 내놓는 표준은 2026년 8월 28일 자 「MCP란 — AI에게 도구를 연결하는 표준, 왜 USB-C에 비유되나」와 2026년 8월 30일 자 「A2A 프로토콜이란 — MCP가 도구를 붙인다면, 이건 에이전트끼리 붙인다」에서, 필요할 때만 지침을 불러오는 같은 발상의 다른 표준은 2026년 10월 24일 자 「에이전트 스킬(Agent Skills)이란 — 폴더 하나로 AI에게 업무를 가르치는 표준, 리눅스재단으로 갔다」에서 다뤘다.
출처
- Google — Introducing Tool Retrieval in the Gemini API (Lucia Loher·Nora Kassner, 2026-11-19)
- PPC Land — Google shrinks idle tools in Gemini agents to about 26 tokens each (Luis Rijo, 2026-11-19)
- i-SCOOP — Gemini's Tool Retrieval loads an agent's tools only when needed, and the tool catalogue is now something to manage
- AlphaSignal — Google's Gemini API Drops Schema Overhead for Agents With Hundreds of Tools (2026-11-19)