도구 사용 문제 해결

증상별 해결 방법 진단 표를 통해 가장 흔한 도구 사용 오류를 해결합니다.

가장 흔한 "tool use"(도구 사용) 오류에 대한 증상별 해결 방법 표입니다. 각 해결 방법은 해당 기능을 담당하는 페이지를 상호 참조합니다.

Claude가 잘못된 도구를 호출함

증상	가능한 원인	해결 방법
도구 B를 원했는데 Claude가 도구 A를 호출함	설명의 모호성	설명을 더 명확하게 다듬으세요. 도구가 무엇을 하는지뿐만 아니라 언제 사용해야 하는지로 도구를 구분하세요. 도구 정의를 참조하세요.
Claude가 도구를 전혀 호출하지 않음	도구 이름 충돌 또는 지나치게 일반적인 스키마	도구 목록 전체에서 중복된 이름이 있는지 확인하세요. 의도한 사용법을 구체적으로 보여주도록 `input_examples`를 추가하세요.
Claude가 잘못된 매개변수 타입으로 호출함	모호한 스키마에 대해 모델이 추측함	`strict: true`를 추가하거나(스키마가 지원되는 하위 집합에 속하는 경우) `input_examples`를 추가하세요.

Claude가 도구 매개변수를 지어냄

증상	가능한 원인	해결 방법
스키마에 존재하지 않는 매개변수	strict 모드 없이 모델이 과잉 생성함	스키마가 지원되는 하위 집합에 속하는 경우 `strict: true`를 추가하세요.
enum 범위를 벗어난 매개변수 값	strict 모드 누락 또는 너무 큰 enum	enum을 줄이거나 유효한 선택지를 보여주는 `input_examples`를 추가하세요.

병렬 도구 호출이 작동하지 않음

증상	가능한 원인	해결 방법
병렬이 더 나은 상황에서 Claude가 도구를 순차적으로 호출함	메시지 기록 형식	여러 `tool_result` 블록을 턴마다 하나씩이 아니라 하나의 user 메시지에 담아 보내세요. 병렬 도구 사용을 참조하세요.
`disable_parallel_tool_use`가 무시되는 것처럼 보임	대화에서 너무 늦게 설정됨	`tool_use`를 반환하는 요청에 설정해야 합니다. 이후 요청에 설정하면 이전 도구 호출에는 아무 영향이 없습니다.

캐시가 계속 무효화됨

증상	가능한 원인	해결 방법
모든 요청이 캐시 미스임	`tool_choice`, thinking 구성 또는 `output_config.effort`가 요청마다 달라짐	`tool_choice`를 안정적으로 유지하거나 `cache_control` 중단점을 변동 지점 앞에 배치하세요. 캐시된 대화가 유지되는 동안 thinking 구성과 effort 수준을 일정하게 유지하세요. 프롬프트 캐싱과 함께 도구 사용 및 사고와 프롬프트 캐싱을 참조하세요.
대화 중간에 도구를 추가하면 캐시가 깨짐	도구가 tools 배열 앞쪽에 추가됨	배열의 앞부분을 수정하는 대신 도구 검색과 함께 `defer_loading: true`를 사용하여 도구를 인라인으로 뒤에 추가하세요.

요청 시점의 오류

오류	원인	해결 방법
`tool_use ids were found without tool_result blocks immediately after`	일부 `tool_use` id에 대한 `tool_result`가 누락되었거나, `tool_result`가 user 메시지의 첫 번째 콘텐츠 블록이 아님	assistant 응답의 모든 `tool_use` 블록마다 하나의 `tool_result`를 반환하세요. `tool_result` 블록을 모든 텍스트보다 앞에 두세요. 도구 호출 처리 및 병렬 도구 사용을 참조하세요.
`was found without a corresponding <name>_tool_result block`	이전 assistant 턴에 결과 블록이 없는 `server_tool_use` 블록이 있고(대부분 Claude가 클라이언트 도구와 함께 호출한 경우), 다음 user 메시지가 해당 턴을 종료했거나(예: `tool_result` 블록 뒤에 텍스트가 있는 경우) 재개 요청에 해당 서버 도구가 더 이상 정의되어 있지 않음(이 경우 메시지는 `but no <name> tool was provided`로 끝남)	클라이언트 `tool_use` id에 대한 `tool_result` 블록만 포함하는 user 메시지를 보내고 동일한 `tools` 배열을 유지하세요. 중지 사유 및 폴백을 참조하세요.
`Unsupported regex feature in pattern field: ...`	strict 도구의 `input_schema`에 있는 `pattern`이 역참조, 전후방 탐색(lookaround), 단어 경계 또는 큰 `{n,m}` 범위와 같이 strict 모드에서 컴파일할 수 없는 정규식 기능을 사용함	패턴을 단순화하세요. 기본 수량자, 문자 클래스, 그룹을 사용하는 앵커된 패턴은 지원됩니다. JSON Schema 제한 사항을 참조하세요.
`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가 포함되어 있다면, 애플리케이션이 assistant의 thinking 블록을 다시 보내기 전에 변경하고 있는 것입니다. assistant 메시지 전체를 변경 없이 그대로 다시 보낸 다음 tool_result를 덧붙이세요.

전체 오류 및 해결 단계는 thinking 블록은 수정할 수 없음을 참조하세요.

Claude가 도구 결과를 프롬프트 인젝션으로 표시함

증상	가능한 원인	해결 방법
Claude가 도구 결과에 따라 행동하기를 거부하거나, 도구 결과에서 나온 지시를 사용자에게 확인해 달라고 요청함	여러분 자신의 지시가 `tool_result` 콘텐츠 안에 담겨 전달되고 있음	Claude는 도구 결과 안의 지시를 잠재적으로 신뢰할 수 없는 제3자 콘텐츠로 취급하도록 학습되어 있습니다. 지시를 도구 결과 밖으로 옮기세요. `tool_result` 블록 뒤의 `user` 턴에 보내거나, 지원되는 모델에서는 대화 중간 시스템 메시지로 보내세요. 도구 결과에는 데이터만 담으세요. 탈옥 및 프롬프트 인젝션 완화를 참조하세요.

JSON 이스케이프 차이 (Opus 4.6+)

증상	원인	해결 방법
최신 모델에서 도구 입력에 대한 문자열 비교가 실패함	유니코드 및 슬래시(/) 이스케이프 방식이 모델 버전마다 다름	`json.loads()` 또는 `JSON.parse()`로 파싱하세요. 직렬화된 입력에 대해 원시 문자열 매칭을 절대 하지 마세요.

다음 단계

도구 정의

Claude를 올바른 도구로 유도하는 스키마와 설명을 작성하세요.

도구 호출 처리

도구를 실행하고 필요한 메시지 형식으로 결과를 반환하세요.

도구 레퍼런스

Anthropic 스키마 도구와 해당 버전 문자열의 전체 목록입니다.

Was this page helpful?

Messages도구

도구 사용 문제 해결

증상별 해결 방법 진단 표를 통해 가장 흔한 도구 사용 오류를 해결합니다.

가장 흔한 "tool use"(도구 사용) 오류에 대한 증상별 해결 방법 표입니다. 각 해결 방법은 해당 기능을 담당하는 페이지를 상호 참조합니다.

Claude가 잘못된 도구를 호출함

증상	가능한 원인	해결 방법
도구 B를 원했는데 Claude가 도구 A를 호출함	설명의 모호성	설명을 더 명확하게 다듬으세요. 도구가 무엇을 하는지뿐만 아니라 언제 사용해야 하는지로 도구를 구분하세요. 도구 정의를 참조하세요.
Claude가 도구를 전혀 호출하지 않음	도구 이름 충돌 또는 지나치게 일반적인 스키마	도구 목록 전체에서 중복된 이름이 있는지 확인하세요. 의도한 사용법을 구체적으로 보여주도록 `input_examples`를 추가하세요.
Claude가 잘못된 매개변수 타입으로 호출함	모호한 스키마에 대해 모델이 추측함	`strict: true`를 추가하거나(스키마가 지원되는 하위 집합에 속하는 경우) `input_examples`를 추가하세요.

Claude가 도구 매개변수를 지어냄

증상	가능한 원인	해결 방법
스키마에 존재하지 않는 매개변수	strict 모드 없이 모델이 과잉 생성함	스키마가 지원되는 하위 집합에 속하는 경우 `strict: true`를 추가하세요.
enum 범위를 벗어난 매개변수 값	strict 모드 누락 또는 너무 큰 enum	enum을 줄이거나 유효한 선택지를 보여주는 `input_examples`를 추가하세요.

병렬 도구 호출이 작동하지 않음

증상	가능한 원인	해결 방법
병렬이 더 나은 상황에서 Claude가 도구를 순차적으로 호출함	메시지 기록 형식	여러 `tool_result` 블록을 턴마다 하나씩이 아니라 하나의 user 메시지에 담아 보내세요. 병렬 도구 사용을 참조하세요.
`disable_parallel_tool_use`가 무시되는 것처럼 보임	대화에서 너무 늦게 설정됨	`tool_use`를 반환하는 요청에 설정해야 합니다. 이후 요청에 설정하면 이전 도구 호출에는 아무 영향이 없습니다.

캐시가 계속 무효화됨

증상	가능한 원인	해결 방법
모든 요청이 캐시 미스임	`tool_choice`, thinking 구성 또는 `output_config.effort`가 요청마다 달라짐	`tool_choice`를 안정적으로 유지하거나 `cache_control` 중단점을 변동 지점 앞에 배치하세요. 캐시된 대화가 유지되는 동안 thinking 구성과 effort 수준을 일정하게 유지하세요. 프롬프트 캐싱과 함께 도구 사용 및 사고와 프롬프트 캐싱을 참조하세요.
대화 중간에 도구를 추가하면 캐시가 깨짐	도구가 tools 배열 앞쪽에 추가됨	배열의 앞부분을 수정하는 대신 도구 검색과 함께 `defer_loading: true`를 사용하여 도구를 인라인으로 뒤에 추가하세요.

요청 시점의 오류

오류	원인	해결 방법
`tool_use ids were found without tool_result blocks immediately after`	일부 `tool_use` id에 대한 `tool_result`가 누락되었거나, `tool_result`가 user 메시지의 첫 번째 콘텐츠 블록이 아님	assistant 응답의 모든 `tool_use` 블록마다 하나의 `tool_result`를 반환하세요. `tool_result` 블록을 모든 텍스트보다 앞에 두세요. 도구 호출 처리 및 병렬 도구 사용을 참조하세요.
`was found without a corresponding <name>_tool_result block`	이전 assistant 턴에 결과 블록이 없는 `server_tool_use` 블록이 있고(대부분 Claude가 클라이언트 도구와 함께 호출한 경우), 다음 user 메시지가 해당 턴을 종료했거나(예: `tool_result` 블록 뒤에 텍스트가 있는 경우) 재개 요청에 해당 서버 도구가 더 이상 정의되어 있지 않음(이 경우 메시지는 `but no <name> tool was provided`로 끝남)	클라이언트 `tool_use` id에 대한 `tool_result` 블록만 포함하는 user 메시지를 보내고 동일한 `tools` 배열을 유지하세요. 중지 사유 및 폴백을 참조하세요.
`Unsupported regex feature in pattern field: ...`	strict 도구의 `input_schema`에 있는 `pattern`이 역참조, 전후방 탐색(lookaround), 단어 경계 또는 큰 `{n,m}` 범위와 같이 strict 모드에서 컴파일할 수 없는 정규식 기능을 사용함	패턴을 단순화하세요. 기본 수량자, 문자 클래스, 그룹을 사용하는 앵커된 패턴은 지원됩니다. JSON Schema 제한 사항을 참조하세요.
`All tools have defer_loading: true`	모델에 보이는 도구가 없음	최소 하나의 도구는 즉시 로드되어야 합니다. 도구 검색 도구 자체에는 절대 `defer_loading: true`를 설정하면 안 됩니다.

오류: thinking 블록은 수정할 수 없음

전체 오류 및 해결 단계는 thinking 블록은 수정할 수 없음을 참조하세요.

Claude가 도구 결과를 프롬프트 인젝션으로 표시함

증상	가능한 원인	해결 방법
Claude가 도구 결과에 따라 행동하기를 거부하거나, 도구 결과에서 나온 지시를 사용자에게 확인해 달라고 요청함	여러분 자신의 지시가 `tool_result` 콘텐츠 안에 담겨 전달되고 있음	Claude는 도구 결과 안의 지시를 잠재적으로 신뢰할 수 없는 제3자 콘텐츠로 취급하도록 학습되어 있습니다. 지시를 도구 결과 밖으로 옮기세요. `tool_result` 블록 뒤의 `user` 턴에 보내거나, 지원되는 모델에서는 대화 중간 시스템 메시지로 보내세요. 도구 결과에는 데이터만 담으세요. 탈옥 및 프롬프트 인젝션 완화를 참조하세요.

JSON 이스케이프 차이 (Opus 4.6+)

증상	원인	해결 방법
최신 모델에서 도구 입력에 대한 문자열 비교가 실패함	유니코드 및 슬래시(/) 이스케이프 방식이 모델 버전마다 다름	`json.loads()` 또는 `JSON.parse()`로 파싱하세요. 직렬화된 입력에 대해 원시 문자열 매칭을 절대 하지 마세요.

다음 단계

도구 정의

Claude를 올바른 도구로 유도하는 스키마와 설명을 작성하세요.

도구 호출 처리

도구를 실행하고 필요한 메시지 형식으로 결과를 반환하세요.

도구 레퍼런스

Anthropic 스키마 도구와 해당 버전 문자열의 전체 목록입니다.

Was this page helpful?

Claude가 잘못된 도구를 호출함

Claude가 도구 매개변수를 지어냄

병렬 도구 호출이 작동하지 않음

캐시가 계속 무효화됨

요청 시점의 오류

오류: thinking 블록은 수정할 수 없음

Claude가 도구 결과를 프롬프트 인젝션으로 표시함

JSON 이스케이프 차이 (Opus 4.6+)

다음 단계

Claude가 잘못된 도구를 호출함

Claude가 도구 매개변수를 지어냄

병렬 도구 호출이 작동하지 않음

캐시가 계속 무효화됨

요청 시점의 오류

오류: thinking 블록은 수정할 수 없음

Claude가 도구 결과를 프롬프트 인젝션으로 표시함

JSON 이스케이프 차이 (Opus 4.6+)

다음 단계

Claude가 잘못된 도구를 호출함

Claude가 도구 매개변수를 지어냄

병렬 도구 호출이 작동하지 않음

캐시가 계속 무효화됨

요청 시점의 오류

오류: thinking 블록은 수정할 수 없음

Claude가 도구 결과를 프롬프트 인젝션으로 표시함

JSON 이스케이프 차이 (Opus 4.6+)

다음 단계

Claude가 잘못된 도구를 호출함

Claude가 도구 매개변수를 지어냄

병렬 도구 호출이 작동하지 않음

캐시가 계속 무효화됨

요청 시점의 오류

오류: thinking 블록은 수정할 수 없음

Claude가 도구 결과를 프롬프트 인젝션으로 표시함

JSON 이스케이프 차이 (Opus 4.6+)

다음 단계