도구 사용 문제 해결

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

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

Claude가 잘못된 도구를 호출합니다

증상	가능한 원인	해결 방법
Claude가 원하는 도구 B 대신 도구 A를 호출합니다	설명의 모호성	설명을 명확히 하세요. 도구를 "어떤 것을 하는가"뿐만 아니라 "언제 사용하는가"로 구분하세요. 도구 정의를 참조하세요.
Claude가 도구를 절대 호출하지 않습니다	도구 이름 충돌 또는 과도하게 일반적인 스키마	도구 목록 전체에서 중복된 이름이 있는지 확인하세요. 의도된 사용을 구체적으로 만들기 위해 `input_examples`를 추가하세요.
Claude가 잘못된 매개변수 타입으로 호출합니다	모호한 스키마에 대한 모델 추측	`strict: true`를 추가하세요(스키마가 지원되는 부분 집합에 있는 경우) 또는 `input_examples`를 추가하세요.

Claude가 도구 매개변수를 만들어냅니다

증상	가능한 원인	해결 방법
스키마에 없는 매개변수	strict 모드 없이 모델이 과도하게 생성	스키마가 지원되는 부분 집합에 있으면 `strict: true`를 추가하세요.
열거형 범위를 벗어난 매개변수 값	strict 모드 누락 또는 너무 큰 열거형	열거형을 축소하거나 유효한 선택을 보여주는 `input_examples`를 추가하세요.

병렬 도구 호출이 작동하지 않습니다

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

캐시가 계속 무효화됩니다

증상	가능한 원인	해결 방법
모든 요청이 캐시 미스입니다	요청 간 `tool_choice` 변동	`tool_choice`를 안정적으로 유지하거나 `cache_control` 중단점을 변동 지점 이전에 배치하세요. 프롬프트 캐싱을 사용한 도구 사용을 참조하세요.
대화 중간에 도구를 추가하면 캐시가 깨집니다	도구가 도구 배열의 앞에 추가됨	배열 헤드를 수정하는 대신 도구 검색과 함께 `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` 블록을 모든 텍스트 앞에 배치하세요. 도구 호출 처리 및 병렬 도구 사용을 참조하세요.
`Input schema is not compatible with strict mode: string patterns are not supported`	`strict: true`와 함께 `pattern` 사용	패턴을 제거하거나 `strict: true`를 삭제하세요. `pattern` 키워드는 아직 지원되는 JSON Schema 부분 집합에 포함되지 않았습니다.
`All tools have defer_loading: true`	모델에 표시되는 도구가 없음	최소한 하나의 도구는 즉시 로드되어야 합니다. 도구 검색 도구 자체는 절대 `defer_loading: true`를 가져서는 안 됩니다.

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

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

다음 단계

도구 정의

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

도구 호출 처리

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

도구 참조

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

Was this page helpful?

빌드도구