---
title: 도구 사용 문제 해결
url: https://platform.claude.com/docs/ko/agents-and-tools/tool-use/troubleshooting-tool-use
description: 증상별 해결 방법 진단 표를 통해 가장 흔한 도구 사용 오류를 해결합니다.
---

증상이나 오류를 찾은 다음, 해당 항목에 나열된 해결 방법을 적용하세요.

## 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`, 사고 구성 또는 `output_config.effort`가 요청마다 달라짐 | `tool_choice`를 일정하게 유지하거나 `cache_control` 중단점을 변동 지점 앞에 배치하세요. 캐시된 대화가 유지되는 동안 사고 구성과 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`가 사용자 메시지의 첫 번째 콘텐츠 블록이 아님 | 어시스턴트 응답의 모든 `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 ... block` | 후속 요청이 대기 중인 서버 도구의 실행을 막음 | [서버 도구 호출에 결과 블록이 없음](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/troubleshooting-tool-use#a-server-tool-call-has-no-result-block)을 참조하세요. |
| `Unsupported regex feature in pattern field: ...` | strict 도구의 `pattern`이 역참조, 단어 경계 또는 큰 `{n,m}` 범위와 같이 strict 모드에서 컴파일할 수 없는 정규식 기능을 사용함 | 패턴을 단순화하세요. [JSON Schema 제한 사항](https://platform.claude.com/docs/ko/build-with-claude/structured-outputs#json-schema-limitations)을 참조하세요. |
| `Invalid regex in pattern field: ...` | strict 도구의 `pattern`에 전방 탐색(lookahead), 후방 탐색(lookbehind) 또는 구문 오류가 있음 | 전방 탐색이나 후방 탐색을 제거하고 구문 오류를 수정하세요. [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`를 설정하면 안 됩니다. |

### 서버 도구 호출에 결과 블록이 없음

[서버 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/server-tools)의 `server_tool_use` 또는 `mcp_tool_use` 블록에 결과 블록이 없으면 해당 도구는 아직 실행을 기다리고 있는 것입니다. `was found without a corresponding ... block` 오류는 후속 요청이 대기 중인 도구의 실행을 막고 있다는 의미입니다. 오류 메시지와 이전 `stop_reason`을 보면 그 이유를 알 수 있습니다. 일치하는 첫 번째 경우를 사용하세요:

* **메시지가 ``but no `<name>` tool was provided`` 또는 `is not available after the last message`로 끝나는 경우:** 여기서 `<name>`은 `web_search`와 같은 도구의 이름입니다. 요청에서 더 이상 해당 도구를 정의하지 않습니다. 이전과 동일한 `tools` 배열을 보내고, MCP 도구의 경우 동일한 `mcp_servers`도 보내세요.
* **이전 `stop_reason`이 `tool_use`였던 경우:** 사용자 메시지에서 `tool_result` 블록 뒤에 콘텐츠가 있었습니다. 각 클라이언트 `tool_use` 블록마다 하나씩, `tool_result` 블록만 보내세요.
* **이전 `stop_reason`이 `pause_turn`이었던 경우:** 사용자 메시지를 추가했습니다. 요청이 일시 중지된 응답을 `assistant` 메시지로 하여 끝나도록 해당 메시지를 제거하세요.

전체 단계는 [서버 도구가 아직 대기 중인 경우](https://platform.claude.com/docs/ko/build-with-claude/handling-stop-reasons#when-a-server-tool-is-still-waiting) 및 [`pause_turn` 중지 이유](https://platform.claude.com/docs/ko/build-with-claude/handling-stop-reasons#pause-turn)를 참조하세요.

## 오류: 사고 블록은 수정할 수 없음

도구 호출 후 대화를 이어갈 때 요청이 400 `invalid_request_error`로 실패하고 그 메시지에 `` `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified ``가 포함되어 있다면, 애플리케이션이 어시스턴트의 사고 블록을 다시 보내기 전에 변경하고 있는 것입니다. 어시스턴트 메시지 전체를 변경 없이 그대로 다시 보낸 다음 `tool_result`를 덧붙이세요.

전체 오류와 해결 단계는 [사고 블록은 수정할 수 없음](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()`로 파싱하세요. 직렬화된 입력에 대해 원시 문자열 매칭을 절대 하지 마세요. |

## 다음 단계

<CardGroup cols={3}>
  <Card title="도구 정의" href="https://platform.claude.com/docs/ko/agents-and-tools/tool-use/define-tools">
    Claude를 올바른 도구로 이끄는 스키마와 설명을 작성하세요.
  </Card>

  <Card title="도구 호출 처리" href="https://platform.claude.com/docs/ko/agents-and-tools/tool-use/handle-tool-calls">
    도구를 실행하고 필요한 메시지 형식으로 결과를 반환하세요.
  </Card>

  <Card title="도구 레퍼런스" href="https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-reference">
    Anthropic이 제공하는 도구와 해당 버전 문자열의 전체 목록입니다.
  </Card>
</CardGroup>
