Messages도구

도구 사용 문제 해결

증상별 진단 표를 통해 가장 일반적인 도구 사용 오류를 해결하세요.

가장 일반적인 도구 사용 오류에 대한 증상별 해결 표입니다. 각 해결 방법은 해당 기능을 다루는 페이지를 참조합니다.

Claude가 잘못된 도구를 호출함

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

Claude가 도구 매개변수를 만들어냄

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

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

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

캐시가 계속 무효화됨

증상	예상 원인	해결 방법
모든 요청이 캐시 미스임	요청 간에 `tool_choice`가 달라짐	`tool_choice`를 일정하게 유지하거나 `cache_control` 중단점을 변동 지점 앞에 배치하세요. 프롬프트 캐싱과 함께 도구 사용하기를 참조하세요.
대화 중간에 도구를 추가하면 캐시가 깨짐	도구가 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` 블록을 모든 텍스트보다 앞에 배치하세요. 도구 호출 처리하기 및 병렬 도구 사용을 참조하세요.
`was found without a corresponding <name>_tool_result block`	이전 어시스턴트 턴에 결과 블록이 없는 `server_tool_use` 블록이 있으며(대부분 Claude가 클라이언트 도구와 함께 호출한 경우), 다음 사용자 메시지가 해당 턴을 종료했거나(예: `tool_result` 블록 뒤에 텍스트가 있는 경우) 재개 요청이 더 이상 해당 서버 도구를 정의하지 않음(이 경우 메시지가 `but no <name> tool was provided`로 끝남)	클라이언트 `tool_use` id에 대한 `tool_result` 블록만 포함하는 사용자 메시지를 보내고 동일한 `tools` 배열을 유지하세요. 중지 이유 및 대체 처리를 참조하세요.
`Input schema is not compatible with strict mode: string patterns are not supported`	`strict: true`와 함께 `pattern`을 사용함	pattern을 제거하거나 `strict: true`를 제거하세요. `pattern` 키워드는 아직 지원되는 JSON Schema 하위 집합에 포함되지 않습니다.
`All tools have defer_loading: true`	모델에 표시되는 도구가 없음	최소 하나의 도구는 즉시 로드되어야 합니다. 도구 검색 도구 자체는 절대 `defer_loading: true`를 가져서는 안 됩니다.

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

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

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

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

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

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

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

다음 단계

도구 정의하기

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

도구 호출 처리하기

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

도구 참조

Anthropic 스키마 도구와 해당 버전 문자열의 전체 디렉터리입니다.

Was this page helpful?

Messages도구

도구 사용 문제 해결

증상별 진단 표를 통해 가장 일반적인 도구 사용 오류를 해결하세요.

가장 일반적인 도구 사용 오류에 대한 증상별 해결 표입니다. 각 해결 방법은 해당 기능을 다루는 페이지를 참조합니다.

Claude가 잘못된 도구를 호출함

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

Claude가 도구 매개변수를 만들어냄

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

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

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

캐시가 계속 무효화됨

증상	예상 원인	해결 방법
모든 요청이 캐시 미스임	요청 간에 `tool_choice`가 달라짐	`tool_choice`를 일정하게 유지하거나 `cache_control` 중단점을 변동 지점 앞에 배치하세요. 프롬프트 캐싱과 함께 도구 사용하기를 참조하세요.
대화 중간에 도구를 추가하면 캐시가 깨짐	도구가 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` 블록을 모든 텍스트보다 앞에 배치하세요. 도구 호출 처리하기 및 병렬 도구 사용을 참조하세요.
`was found without a corresponding <name>_tool_result block`	이전 어시스턴트 턴에 결과 블록이 없는 `server_tool_use` 블록이 있으며(대부분 Claude가 클라이언트 도구와 함께 호출한 경우), 다음 사용자 메시지가 해당 턴을 종료했거나(예: `tool_result` 블록 뒤에 텍스트가 있는 경우) 재개 요청이 더 이상 해당 서버 도구를 정의하지 않음(이 경우 메시지가 `but no <name> tool was provided`로 끝남)	클라이언트 `tool_use` id에 대한 `tool_result` 블록만 포함하는 사용자 메시지를 보내고 동일한 `tools` 배열을 유지하세요. 중지 이유 및 대체 처리를 참조하세요.
`Input schema is not compatible with strict mode: string patterns are not supported`	`strict: true`와 함께 `pattern`을 사용함	pattern을 제거하거나 `strict: true`를 제거하세요. `pattern` 키워드는 아직 지원되는 JSON Schema 하위 집합에 포함되지 않습니다.
`All tools have defer_loading: true`	모델에 표시되는 도구가 없음	최소 하나의 도구는 즉시 로드되어야 합니다. 도구 검색 도구 자체는 절대 `defer_loading: true`를 가져서는 안 됩니다.

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

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

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

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

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+)

다음 단계