Gemini API, 도구 검색 프리뷰 공개

구글은 11월 19일 Gemini API에 Tool Retrieval(도구 검색) 프리뷰를 내놓았다. 에이전트에 수십~수백 개의 도구를 연결한 경우, 개발자는 요청마다 모든 도구의 파라미터 스키마를 넣을 필요가 없다. 모델은 처음에는 도구 이름과 설명만 보고, 쓰려는 도구가 정해지면 이름으로 전체 정의를 가져온 뒤 같은 요청 안에서 함수 호출을 보낸다.

이 기능은 현재 Interactions API에서만 쓸 수 있고, Gemini 3.6 이상과 모든 Gemini 4 모델을 지원한다. 구글이 블로그에서 밝힌 취지는 단순하다. 도구가 많아지면 요청마다 전체 스키마를 보내느라 입력 토큰과 지연 시간이 늘고, 후보 도구가 많을수록 모델이 알맞은 도구를 고를 확률도 낮아진다는 것이다.

Illustration: only one drawer opens to reveal a wrench, showing how Gemini loads tool definitions on demand.

가져오는 방법은 두 가지

기본값은 서버 측 검색이다. 개발자는 tools에 {"type": "tool_search"} 항목을 추가하고, 자주 쓰지 않는 도구에 defer_loading을 지정한다. 자주 쓰는 도구는 기존처럼 직접 선언한다. 검색은 구글 서버에서 실행되므로 인덱스를 직접 만들거나 호스팅할 필요가 없다. 디버깅할 때는 interaction.steps에서 tool_search_call, tool_search_result, function_call 세 종류의 단계를 볼 수 있어, 도구 이름과 설명 중 어느 쪽이 불분명한지 가려내기 쉽다.

다른 하나는 클라이언트 측 검색이다. tool_search를 선언할 때 "execution": "client"를 추가하면, 모델이 검색 요청을 보낸 뒤 애플리케이션이 직접 도구 레지스트리를 조회하고 일치하는 스키마를 함수 결과로 돌려준다. 검색할 때마다 왕복이 한 번 늘어나지만, 그 대신 도구를 미리 선언하지 않아도 되고, 대화 도중에 새 도구를 추가할 수 있으며, 사용자 권한에 따라 걸러내거나 자체 벡터 인덱스를 연결할 수도 있다.

원격 MCP 서버에도 같은 방식이 적용된다. mcp_server 도구에 defer_loading: true를 설정하면 해당 서버가 노출하는 모든 도구가 필요할 때 불러오는 방식으로 바뀐다. 구글은 지연 로딩되는 스키마를 프롬프트 맨 앞에 두지 않고, 나중에 로드된 스키마는 대화 뒤쪽에 덧붙이기 때문에 여러 턴에 걸친 프리픽스 캐시가 무효화되지 않는다고도 설명했다.

"Tool Retrieval has no separate charge. Input and output tokens are billed at the standard rates for the model you call."

절약 여부는 도구 라이브러리 규모에 달렸다

tool_search를 켜면 입력 토큰이 소량 고정으로 늘어난다. 구체적인 양은 블로그에 나와 있지 않다. 모델이 로드한 스키마는 미리 선언한 도구와 마찬가지로 이후 대화에서 계속 입력으로 과금된다. 구글의 설명에 따르면 로드되지 않는 스키마가 로드되는 스키마보다 많을 때 토큰을 아낄 수 있으며, 대규모 도구 라이브러리는 대체로 여기에 해당한다. 구글은 개발자에게 실제 트래픽으로 직접 테스트해 볼 것을 권한다. 반대로 도구가 많지 않거나 매 턴 대부분의 도구를 쓰는 앱이라면 켜도 이득이 아닐 수 있다.

같은 발상, 한발 앞선 앤트로픽

이 방식은 Claude 개발자 플랫폼이 작년 11월에 이미 선보였다. 앤트로픽은 이를 Tool Search Tool이라 부르며, 지연 로딩 파라미터 이름도 같은 defer_loading이고 MCP 서버도 필요할 때 불러오는 대상에 포함한다. 두 회사의 차이는 내놓은 근거에 있다. 앤트로픽은 당시 내부 테스트에서 나온 토큰 절감 폭과 도구 선택 정확도를 공개했지만, 구글은 이번에 작동 방식과 과금만 설명했을 뿐 효과를 보여주는 데이터는 하나도 내놓지 않았다.

이미 Claude나 OpenAI API로 에이전트를 만든 팀에게 이번 진입 장벽은 주로 API 자체에 있다. 도구 검색은 Interactions API에서만 쓸 수 있어, 아직 구 API를 쓰는 Gemini 프로젝트는 먼저 마이그레이션해야 켤 수 있다. 프리뷰 종료 후의 할당량과 속도 제한도 구글은 아직 공개하지 않았다.

참고 출처: Google 개발자 블로그, CocoLoop, Google AI Studio 도구 검색 문서, Anthropic 개발자 문서. 지원 모델 버전, 두 가지 검색 모드, MCP 지연 로딩, 과금 규칙을 확인했다.