Claude Platform Docs
Messages도구

도구 사용 문제 해결

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

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

Claude가 잘못된 도구를 호출함

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

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

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

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

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

캐시가 계속 무효화됨

증상가능한 원인해결 방법
모든 요청이 캐시 미스임tool_choice, 사고 구성 또는 output_config.effort가 요청마다 달라짐tool_choice를 일정하게 유지하거나 cache_control 중단점을 변동 지점 앞에 배치하세요. 캐시된 대화가 유지되는 동안 사고 구성과 effort 수준을 일정하게 유지하세요. 프롬프트 캐싱과 함께 도구 사용 및 사고와 프롬프트 캐싱을 참조하세요.
대화 중간에 도구를 추가하면 캐시가 깨짐도구가 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 ... block후속 요청이 대기 중인 서버 도구의 실행을 막음서버 도구 호출에 결과 블록이 없음을 참조하세요.
Unsupported regex feature in pattern field: ...strict 도구의 pattern이 역참조, 단어 경계 또는 큰 {n,m} 범위와 같이 strict 모드에서 컴파일할 수 없는 정규식 기능을 사용함패턴을 단순화하세요. JSON Schema 제한 사항을 참조하세요.
Invalid regex in pattern field: ...strict 도구의 pattern에 전방 탐색(lookahead), 후방 탐색(lookbehind) 또는 구문 오류가 있음전방 탐색이나 후방 탐색을 제거하고 구문 오류를 수정하세요. JSON Schema 제한 사항을 참조하세요.
All tools have defer_loading: true모델에 보이는 도구가 없음최소 하나의 도구는 즉시 로드되어야 합니다. 도구 검색 도구 자체에는 절대 defer_loading: true를 설정하면 안 됩니다.

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

서버 도구의 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 메시지로 하여 끝나도록 해당 메시지를 제거하세요.

전체 단계는 서버 도구가 아직 대기 중인 경우 및 pause_turn 중지 이유를 참조하세요.

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

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

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

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

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

모델 버전 간 JSON 이스케이프 차이

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

다음 단계

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

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

Anthropic이 제공하는 도구와 해당 버전 문자열의 전체 목록입니다.

이 페이지가 도움이 되었나요?