--- title: 도구 사용 문제 해결 url: https://platform.claude.com/docs/ko/agents-and-tools/tool-use/troubleshooting-tool-use description: 증상별 해결 방법 진단 표를 통해 가장 흔한 도구 사용 오류를 해결합니다. --- 가장 흔한 "tool use"(도구 사용) 오류에 대한 증상별 해결 방법 표입니다. 각 해결 방법은 해당 기능을 다루는 페이지를 상호 참조합니다. ## Claude가 잘못된 도구를 호출함 | 증상 | 가능한 원인 | 해결 방법 | | ---------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 도구 B를 원했는데 Claude가 도구 A를 호출함 | 설명의 모호성 | 설명을 더 명확하게 다듬으세요. 도구가 무엇을 하는지(WHAT)뿐만 아니라 언제 사용하는지(WHEN)로 도구를 구분하세요. [도구 정의](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/define-tools)를 참조하세요. | | Claude가 도구를 전혀 호출하지 않음 | 도구 이름 충돌 또는 지나치게 일반적인 스키마 | 도구 목록 전체에서 중복된 이름이 있는지 확인하세요. 의도한 사용법을 구체적으로 보여주도록 `input_examples`를 추가하세요. | | Claude가 잘못된 매개변수 타입으로 호출함 | 모호한 스키마에 대해 모델이 추측함 | `strict: true`를 추가하거나(스키마가 지원되는 하위 집합에 속하는 경우) `input_examples`를 추가하세요. | ## Claude가 도구 매개변수를 지어냄 | 증상 | 가능한 원인 | 해결 방법 | | ------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | 스키마에 존재하지 않는 매개변수 | strict 모드 없이 모델이 과도하게 생성함 | 스키마가 [지원되는 하위 집합](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/strict-tool-use)에 속하는 경우 `strict: true`를 추가하세요. | | enum 범위를 벗어난 매개변수 값 | strict 모드 누락 또는 너무 큰 enum | enum을 줄이거나 유효한 선택지를 보여주는 `input_examples`를 추가하세요. | ## 병렬 도구 호출이 작동하지 않음 | 증상 | 가능한 원인 | 해결 방법 | | ---------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 병렬이 더 나은 상황에서 Claude가 도구를 순차적으로 호출함 | 메시지 기록 형식 | 여러 `tool_result` 블록을 턴마다 하나씩이 아니라 하나의 user 메시지에 담아 보내세요. [병렬 도구 사용](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/parallel-tool-use)을 참조하세요. | | `disable_parallel_tool_use`가 무시되는 것처럼 보임 | 대화에서 너무 늦게 설정됨 | `tool_use`를 반환하는 요청에 설정해야 합니다. 이후 요청에 설정하면 이전 도구 호출에는 아무 영향이 없습니다. | ## 캐시가 계속 무효화됨 | 증상 | 가능한 원인 | 해결 방법 | | ---------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 모든 요청이 캐시 미스임 | `tool_choice`, thinking 구성 또는 `output_config.effort`가 요청마다 달라짐 | `tool_choice`를 일정하게 유지하거나 `cache_control` 중단점을 변동 지점 앞에 배치하세요. 캐시된 대화가 유지되는 동안 thinking 구성과 effort 수준을 일정하게 유지하세요. [프롬프트 캐싱과 함께 도구 사용](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-use-with-prompt-caching) 및 [사고와 프롬프트 캐싱](https://platform.claude.com/docs/ko/build-with-claude/thinking#thinking-and-prompt-caching)을 참조하세요. | | 대화 중간에 도구를 추가하면 캐시가 깨짐 | 도구가 tools 배열 앞쪽에 추가됨 | 배열의 앞부분을 수정하는 대신 도구 검색과 함께 `defer_loading: true`를 사용하여 도구를 인라인으로 뒤에 추가하세요. | ## 요청 시점의 오류 | 오류 | 원인 | 해결 방법 | | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tool_use ids were found without tool_result blocks immediately after` | 일부 `tool_use` id에 대한 `tool_result`가 누락되었거나, `tool_result`가 user 메시지의 첫 번째 콘텐츠 블록이 아님 | 어시스턴트 응답의 모든 `tool_use` 블록마다 하나의 `tool_result`를 반환하세요. `tool_result` 블록을 모든 텍스트보다 앞에 두세요. [도구 호출 처리](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/handle-tool-calls) 및 [병렬 도구 사용](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/parallel-tool-use)을 참조하세요. | | `was found without a corresponding _tool_result block` | 이전 어시스턴트 턴에 결과 블록이 없는 `server_tool_use` 블록이 있고(대부분 Claude가 클라이언트 도구와 함께 호출한 경우), 다음 user 메시지가 해당 턴을 종료했거나(예: `tool_result` 블록 뒤에 텍스트가 있는 경우) 재개 요청에서 해당 서버 도구를 더 이상 정의하지 않음(이 경우 메시지는 `but no tool was provided`로 끝남) | 클라이언트 `tool_use` id에 대한 `tool_result` 블록만 포함하는 user 메시지를 보내고 동일한 `tools` 배열을 유지하세요. [중지 이유와 폴백](https://platform.claude.com/docs/ko/build-with-claude/handling-stop-reasons#tool-use)을 참조하세요. | | `Unsupported regex feature in pattern field: ...` | strict 도구의 `input_schema`에 있는 `pattern`이 역참조, 전후방 탐색(lookaround), 단어 경계 또는 큰 `{n,m}` 범위와 같이 strict 모드에서 컴파일할 수 없는 정규식 기능을 사용함 | 패턴을 단순화하세요. 기본 수량자, 문자 클래스, 그룹을 사용하는 앵커된 패턴은 지원됩니다. [JSON Schema 제한 사항](https://platform.claude.com/docs/ko/build-with-claude/structured-outputs#json-schema-limitations)을 참조하세요. | | `All tools have defer_loading: true` | 모델에 보이는 도구가 없음 | 최소 하나의 도구는 즉시 로드되어야 합니다. 도구 검색 도구 자체에는 절대 `defer_loading: true`를 설정하면 안 됩니다. | ## 오류: thinking 블록은 수정할 수 없음 도구 호출 후 대화를 이어갈 때 요청이 400 `invalid_request_error`로 실패하고 그 메시지에 `` `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified ``가 포함되어 있다면, 애플리케이션이 어시스턴트의 thinking 블록을 다시 보내기 전에 변경하고 있는 것입니다. 어시스턴트 메시지 전체를 변경 없이 그대로 다시 보낸 다음 `tool_result`를 덧붙이세요. 전체 오류와 해결 단계는 [thinking 블록은 수정할 수 없음](https://platform.claude.com/docs/ko/api/errors#thinking-blocks-cannot-be-modified)을 참조하세요. ## Claude가 도구 결과를 프롬프트 인젝션으로 표시함 | 증상 | 가능한 원인 | 해결 방법 | | ------------------------------------------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Claude가 도구 결과에 따라 행동하기를 거부하거나, 도구 결과에서 나온 지시 사항을 사용자에게 확인해 달라고 요청함 | 사용자 자신의 지시 사항이 `tool_result` 콘텐츠 안에 담겨 전달되고 있음 | Claude는 도구 결과 안의 지시 사항을 잠재적으로 신뢰할 수 없는 제3자 콘텐츠로 취급하도록 학습되어 있습니다. 지시 사항을 도구 결과 밖으로 옮기세요. `tool_result` 블록 뒤의 `user` 턴에서 보내거나, 지원되는 모델에서는 [대화 중간 시스템 메시지](https://platform.claude.com/docs/ko/build-with-claude/mid-conversation-system-messages)로 보내세요. 도구 결과에는 데이터만 담으세요. [탈옥 및 프롬프트 인젝션 완화](https://platform.claude.com/docs/ko/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks#indirect-prompt-injection)를 참조하세요. | ## 모델 버전 간 JSON 이스케이프 차이 | 증상 | 원인 | 해결 방법 | | ----------------------------- | ---------------------------------- | -------------------------------------------------------------------------- | | 최신 모델에서 도구 입력에 대한 문자열 비교가 실패함 | 유니코드 및 슬래시(/) 이스케이프 방식이 모델 버전마다 다름 | `json.loads()` 또는 `JSON.parse()`로 파싱하세요. 직렬화된 입력에 대해 원시 문자열 매칭을 절대 하지 마세요. | ## 다음 단계 Claude를 올바른 도구로 이끄는 스키마와 설명을 작성하세요. 도구를 실행하고 필요한 메시지 형식으로 결과를 반환하세요. Anthropic이 제공하는 도구와 해당 버전 문자열의 전체 목록입니다.