툴 콜링

LLM이 외부 함수나 API를 어떤 인자로 부를지 호출 요청만 정해진 형식으로 적어 주고, 실제 실행은 개발자 코드가 맡는 기능이다. 최신 정보 조회, 계산, DB 검색, 파일 수정처럼 모델 혼자서는 못 하는 일을 맡길 때 쓴다.

예를 들어 모델은 "get_weather를 location=서울로 불러 주세요"라고 적기만 하고, 실제 API는 개발자 코드가 부른다.

요청과 결과가 한 번씩 오간다

요청의 tools에 도구마다 이름, 설명, 입력 형식(input_schema)을 넣어 보낸다. 모델이 도구가 필요하다고 보면 stop_reason이 tool_use가 되고, 코드가 함수를 실행한 뒤 같은 호출 ID로 tool_result를 보낸다. 모델은 결과를 읽고 답을 쓰거나 다른 도구를 또 부른다.

실행이 실패해도 오류 내용을 tool_result에 담고 is_error로 표시해 돌려주면 모델이 인자를 고쳐 다시 시도한다. "서울과 부산 날씨 비교"처럼 서로 독립적인 호출은 한 번에 여러 개 요청하는 병렬 호출로 처리된다. 이 왕복을 목표를 이룰 때까지 반복하면 AI 에이전트가 된다.

설명을 자세히 써야 도구를 잘 고른다

도구 성능을 가장 크게 좌우하는 건 설명이다. 무엇을 하는지, 언제 쓰고 언제 쓰면 안 되는지, 인자 뜻과 돌려주는 값까지 적어야 비슷한 도구끼리 헷갈리지 않는다. 도구가 많으면 github_list_prs처럼 서비스 이름을 앞에 붙이고, 비슷한 동작은 하나로 묶는다. 날짜처럼 까다로운 인자는 input_examples에 예시를 넣는다.

특정 도구를 강제로 부르게 하는 옵션은 일부 최신 Claude 모델에서 지원하지 않으니 auto와 strict: true를 함께 쓴다. 도구 정의도 매 요청 입력 토큰으로 과금되므로, 도구가 수십 개라면 필요한 것만 찾아 불러오는 도구 검색 기능을 쓴다.

내 서버 도구, 제공사 도구, 그리고 MCP

직접 정의해 내 서버에서 돌리는 클라이언트 도구가 기본이고, 웹 검색·코드 실행처럼 제공사 인프라에서 돌아가 결과만 받는 서버 도구도 있다. Claude Code가 파일을 읽고 셸 명령을 실행하는 것도 모두 도구 호출이다.

실행 권한은 내 코드에 있다

실행 권한이 늘 개발자 코드에 있다는 점을 안전장치로 써야 한다. 모델이 고른 인자는 검증하고, 결제나 삭제처럼 되돌릴 수 없는 작업은 사람이 확인하게 한다. 도구 결과로 들어오는 웹 페이지나 문서 속 프롬프트 인젝션에 대비하고, 모델에게는 작업에 꼭 필요한 도구와 권한만 준다.

대화만 하던 모델에 손발을 붙일 때 쓴다

가장 흔한 건 모델이 직접 찾아보고, 조회하고, 실행해야 하는 앱에 도구 몇 개를 붙이는 방식이다. 읽기 도구는 자유롭게 열어 두고, 무언가를 바꾸는 도구만 사람 확인을 거치게 하는 구성이 많다.