도구 스키마 — 정의, 루프, 호출 패턴

도구 사용에서 가장 흔한 오해는 Claude가 직접 도구를 실행한다고 생각하는 것입니다. 실제로는 조금 다릅니다. Claude는 건네받은 도구 정의를 읽고, 상황에 맞는 도구를 고른 다음, 어떤 입력으로 무엇을 실행할지 애플리케이션에 알려 줍니다. 실제 실행은 코드가 하고, 그 결과를 다시 Claude에 돌려주면, Claude가 그 결과를 받아 이어 갑니다.

이 주고받음은 프로덕션(실서비스 환경)에서 특히 중요합니다. 애플리케이션이 결과를 제대로 되돌려 주지 않으면 Claude는 요청한 데이터를 끝내 받지 못하고, 루프가 거기서 끊깁니다. Claude가 맡는 일과 코드가 맡는 일의 경계 — 도구 사용에서 생기는 버그 대부분이 바로 이 경계에서 나옵니다.

아래 여섯 단계를 눌러 가며 각 단계에서 무슨 일이 일어나는지 확인해 보세요.

도구 사용 대화는 일반 텍스트가 아니라 구조화된 블록으로 이뤄집니다. 어시스턴트 턴과 사용자 턴은 각각 블록의 목록이고, 도구 사용 세션에서는 네 가지 블록이 일을 나눠 맡습니다.

• text 블록 — Claude의 자연어 응답이 담깁니다.
• tool_use 블록 — 도구 호출이 담깁니다. 도구 이름, 고유 ID, 입력값이 함께 들어갑니다.
• tool_result 블록 — 코드가 도구를 실행한 뒤 되돌려 준 결과가 담깁니다.
• thinking 블록 — Claude의 내부 추론이 담깁니다. 확장 사고(extended thinking)를 켰을 때만 나타납니다.

API는 이 블록들 사이의 짝짓기를 강제합니다. 어시스턴트 턴의 tool_use 블록마다, 바로 다음 사용자 턴에 같은 ID를 지닌 tool_result 블록이 답으로 와야 합니다. ID가 맞지 않거나, 결과가 빠지거나, 턴 순서가 어긋나면 요청은 검증에서 실패합니다. 이건 프롬프트를 손봐서 해결할 수 있는 문제가 아니라 구조의 문제라서, 매 요청마다 코드가 이 순서를 정확히 만들어야 합니다.

BLOCK RULES — 블록별로 코드가 지켜야 할 규칙

스키마는 도구 하나를 정의하는 세 부분으로 이뤄집니다 — 이름(name), 설명(description), 입력 형식(input_schema). 이 중에서 Claude가 도구를 맞게 고르는지 아닌지를 가르는 것은 설명입니다.

SCHEMA · THREE PARTS — 스키마의 세 부분

스키마는 Claude가 어떤 도구를 부를지, 어떤 인자를 넘길지, 답하기에 충분한 정보가 있는지를 판단하며 읽는 자료입니다. 스키마가 모호하거나 설명이 부족하거나 필수 필드가 빠져 있으면, 문법상으로는 멀쩡해 보여도 엉뚱한 도구를 고르거나 잘못된 입력을 넘기거나 불필요하게 루프를 반복하는 호출이 나옵니다. 아래 다섯 가지 판단이 실제 조건에서 구현이 예측 가능하게 동작할지를 가릅니다. 순차 호출과 병렬 호출이 갈리는 지점도 함께 적었습니다.

FIVE DECISIONS — 스키마 설계의 다섯 가지 판단

한 개발자가 도구 두 개를 등록합니다 — search_knowledge_base와 get_cached_result. 이름은 서로 다르지만, Claude의 도구 선택은 설명에 크게 기웁니다. 설명이 겹치면 이름만으로는 구분되지 않습니다.

두 도구 모두 설명이 "use this to find information"으로 시작했고, 제외 조건이 없다 보니 개발 중 테스트에서 애매한 입력에 대해 Claude가 자주 엉뚱한 도구를 골랐습니다. 문제는 선택을 판단하는 그 지점에서 두 설명이 Claude에게 똑같아 보인다는 데 있습니다. 해결은 각 설명에 한 문장씩을 더하는 것입니다.

각 설명에 제외 조건 한 문장을 더한 버전

search_knowledge_base:
"Use this to search the knowledge base when the user asks a
question that requires looking up current information. Do not
use this if the result of a prior search in this session
already covers the question."

get_cached_result:
"Use this to retrieve a result that was already fetched during
this session. Only use this if search_knowledge_base was called
earlier in this conversation for the same query."

제외 조건은 Claude에게 똑같아 보이던 두 선택지 대신 판단 규칙을 줍니다. 다만 이 조건은 매 요청에 대화 기록 전체가 함께 넘어온다는 전제에 기댑니다. 앞선 턴이 잘리거나 빠지면 Claude가 그 조건을 확인할 수 없고, 제외 논리도 조용히 작동하지 않게 됩니다.

등록하는 도구가 하나 늘 때마다 Claude가 따져야 할 범위도 넓어집니다. 그래서 이 방식은 도구들이 실제로 서로 다를 때에만 효과가 있습니다.

앞의 내용은 전부 스키마를 직접 쓴다는 전제였습니다 — 이름, 설명, 입력 형식, 그리고 Claude가 tool_use 블록을 낼 때 실행되는 함수까지. 그런데 많은 연동에서는 그럴 필요가 없습니다. MCP(Model Context Protocol)는 도구 정의와 실행을 애플리케이션 코드 밖 전용 서버로 옮기는 표준 통신 방식입니다. 원하는 서비스의 MCP 서버가 이미 있다면, 연동을 직접 만드는 대신 그 서버에 연결하면 됩니다.

GitHub 연동을 예로 들어 보겠습니다. GitHub은 저장소, 풀 리퀘스트, 이슈, 프로젝트 등 여러 기능을 제공합니다. 이 모듈에서 배운 스키마 방식으로 전체 연동을 만들려면, 기능 하나하나에 스키마와 실행 함수를 쓰고 GitHub API가 바뀔 때마다 유지해야 합니다. GitHub용 MCP 서버는 그 일을 이미 해 두었습니다. 애플리케이션은 서버에 연결해 사용 가능한 도구 목록 전체를 받고, Claude는 지금까지 다뤄 온 것과 똑같은 설명 기반 방식으로 그중에서 도구를 고릅니다. 작동하는 방식 자체는 같습니다. 달라지는 것은 그 도구 정의의 작성자와 소유자입니다.

이 모듈 앞에서 만든 루프는 MCP를 들여도 바뀌지 않습니다. Claude는 여전히 tool_use 블록을 내고, 애플리케이션은 여전히 도구를 실행해 tool_result를 돌려주며, 블록 짝짓기 규칙도 그대로 적용됩니다. 달라지는 건 준비 단계뿐입니다. 직접 쓴 스키마를 등록하는 대신, MCP 클라이언트가 서버에 ListToolsRequest를 보내 도구 목록 전체를 받아 Claude에 전달합니다. Claude가 보기에 이 도구들은 직접 쓴 도구와 구분되지 않습니다.

API MCP 커넥터를 쓴다면, 도구 배열의 mcp_toolset 객체로 로딩 비용을 조절합니다. mcp_toolset에는 서버의 모든 도구에 적용되는 default_config 블록이 있고, 도구 이름을 키로 한 설정으로 개별 도구를 덮어쓸 수 있습니다. 컨텍스트 비용과 관련해 두 가지 설정이 중요합니다.

• defer_loading — default_config나 개별 도구 항목에 두는 불리언 값으로, 모델이 필요로 할 때까지 도구 정의를 미룹니다. 도구가 많은 서버를 연결할 때 처음 드는 컨텍스트 비용을 줄여 줍니다.
• enabled — 개별 도구를 켜고 끄는 불리언 값으로, 서버는 등록하되 모델에 보이는 도구는 원하는 것만 남길 수 있습니다.

MCP 커넥터를 쓰려면 요청에 mcp-client-2025-11-20 베타 헤더를 설정해야 합니다. 이 헤더가 없으면 여기 설명한 대로 mcp_toolset 설정이 적용되지 않습니다.

이 단계에서 알아 둘 나머지 하나는, 클라이언트가 서버와 실제로 이야기를 주고받는 방식입니다. MCP는 두 가지 전송 방식(transport) 중 하나로 통신하고, 어느 쪽을 쓰는지는 서버가 어디에 있는지에 달려 있습니다.

• 로컬 서버는 stdio를 씁니다. 애플리케이션이 서버를 하위 프로세스로 띄우고 표준 입출력으로 주고받습니다.
• 원격 서버는 Streamable HTTP를 씁니다. 애플리케이션이 네트워크로 연결해, 클라이언트→서버 메시지는 POST로 보내고 서버가 먼저 보내는 메시지는 GET 기반 SSE 스트림(선택)으로 받습니다.

예전의 SSE 전용 전송 방식도 있지만 지원이 종료되는 중이라, 새 연동은 Streamable HTTP를 씁니다. Anthropic의 API MCP 커넥터를 쓴다면 짚어 둘 제약이 하나 있습니다 — 커넥터로는 HTTP로 노출된 서버만 지원되고, stdio 서버는 SDK로 MCP 클라이언트 연결을 직접 관리해야 합니다. 연결이 맺어지고 도구 정의를 받고 나면, 그다음부터 애플리케이션 코드는 두 전송 방식을 똑같이 다룹니다.

WHEN TO USE WHICH — 언제 무엇을 쓸까

스키마가 멀쩡해 보이는데도 실패하는 경우가 있습니다. 파라미터에 타입이 잡혀 있고 정상 경로 테스트를 통과했다면 구조가 유효하다는 것까지는 알 수 있습니다. 하지만 설명이 겹치는 두 도구의 경계에 가까운 입력이 들어왔을 때, Claude가 둘 중 하나를 안정적으로 고를 수 있는지까지는 알려 주지 않습니다. 바로 이 지점이 초기 테스트에서 놓치기 쉽고, 프로덕션에서 드러날 가능성이 가장 큰 실패 유형입니다.

한 개발자가 코드 리뷰를 하던 중, 아침부터 붙들고 있던 잘못된 도구 선택 문제를 디버그 세션에 붙여 넣습니다. 시니어 개발자가 던진 한 가지 질문이 문제 전체를 다시 보게 합니다.

아래 세션 기록은 에이전트가 도구를 부르고, 결과를 받고, 다음 요청에서 API 검증 오류로 실패하는 과정을 보여 줍니다. 스키마는 유효하고, 도구 설명도 구체적이며, 도구 결과 내용도 맞습니다. 무엇이 문제일까요?

SESSION TRACE — 검증 오류로 끝나는 세션 기록

Turn 1: User:
  [text]: "What is the current balance for account A-4471?"

Turn 2: Assistant:
  [text]: "I'll look that up."
  [tool_use]: id="toolu_01", name="get_account_balance",
              input={"account_id": "A-4471"}

Turn 3: User (tool result):
  [tool_result]: tool_use_id="toolu_02", content="Balance: $1,240.18"

Turn 4: API response:
  Error: invalid_request_error
  "tool_result block references unknown tool_use_id"

기록을 읽고, 어떤 블록이 빠졌거나 순서가 어긋났는지 짚어 보고, 깨진 규칙이 무엇인지 이름 붙여 본 다음, 아래 보기에서 알맞은 수정을 골라 보세요. 정답을 먼저 떠올려 본 뒤 고르면 좋습니다. 맞히면 설명이 나옵니다.