Claude 도구 조회가 실패했다면 결과 없음 대신 오류 상태를 돌려주기

한 장의 그림으로 이해하기

가상 예시다. 왼쪽 사서는 서랍을 실제로 열어 비어 있음을 확인한 뒤 0이라고 기록한다. 오른쪽에서는 보관함으로 가는 길이 끊겨 내용을 확인할 수 없는데 로봇이 0이라고 쓰려 하자 사서가 오류 표식을 들고 손을 내밀어 멈춘다. 서랍은 조회 대상, 길은 도구 실행 경로, 기록지는 반환 결과에 대응한다. 두 장면은 성공한 빈 조회와 실패한 조회의 비교이며 시간 순서가 아니다. 그림의 0은 가상 결과이지 실제 고객 자료나 측정값이 아니다. 결론은 실패를 빈 결과로 바꾸지 말라는 것이다. 실패의 원인별 재시도 정책과 서버 도구의 오류 형식은 생략했다. 오류 표식을 전달해도 복구가 보장되는 것은 아니다.
내용의 흐름을 표현한 설명용 그림입니다. 실제 제품 화면이나 실행 결과가 아닙니다.
그림 크게 보기 ↗ (새 탭)

업무·자동화 · 판정 관망

그림을 글로 풀면

빈 조회와 실패한 조회를 나눠 보기

도구 실행 오류를 빈 목록으로 바꾸면 실제로 조회한 결과처럼 오해할 수 있습니다.

대상
Claude에 사내 조회 도구를 연결하는 자동화 담당자
무엇이 바뀜
도구 실행 오류는 is_error로 표시할 수 있습니다.
왜 중요한가
성공한 조회에서 찾지 못한 것과 조회 자체를 못한 것은 후속 판단이 다릅니다.
지금 할 일
도구 호출 식별자를 맞추고 오류 여부와 확인 가능한 원인을 함께 반환합니다.
한계·미확인
가상 예시입니다. 실제 API 요청·조회·오류 주입과 복구 시험은 하지 않았습니다.
확인일
2026-09-22

조회하지 못한 것을 없다고 기록하지 않기

가상의 문서 검색에서 결과가 비어 있는 경우와 검색 서버 연결에 실패한 경우를 비교합니다. 전자는 조회 결과에 해당하고 후자는 문서가 있는지 아직 알 수 없는 상태입니다. 그림 오른쪽의 로봇이 쓰려는 0은 바로 이 잘못된 확정입니다. 이 글은 예외를 잡은 뒤 무조건 빈 목록을 반환하는 처리를 점검 대상으로 제안합니다.

실패 정보도 원래 도구 호출과 연결하기

Claude 공식 문서는 클라이언트 도구의 실행 오류를 tool_result의 content에 설명하고 is_error를 true로 지정하는 방식을 안내합니다. tool_use_id에는 대응하는 도구 호출의 식별자를 넣습니다. 호출 연결과 오류 표시를 함께 보존해야 어느 조회가 실패했는지 구분할 수 있습니다. 이 글은 클라이언트 도구의 결과 전달 범위이며 모든 서버 도구의 오류 형식이 같다는 뜻은 아닙니다.

오류 전달과 재실행 결정은 구분하기

실패를 알려 주었다고 조회가 복구되거나 다시 실행해도 안전하다는 결론이 생기는 것은 아닙니다. 이 글에서는 확인된 실패 원인과 다음 확인 사항을 설명하되, 비밀 값이나 불필요한 고객 자료를 오류 문구에 넣지 않는 절차를 제안합니다. 성공한 빈 결과·실행 실패·정상 결과를 각각 가상 입력으로 점검하는 것도 후속 시험안입니다. 이번 제작에서는 그 시험이나 실제 Claude API 호출을 실행하지 않았습니다.

참고 원문: Anthropic 도구 호출 처리 공식 문서 · 원문 게시일 상시 문서(게시일 별도 미표기) · 확인일 2026-09-22

AI 작성·자동 검증: 공식 자료와의 대조 및 게시 구조 검사. 사람의 개별 검수와 제품 실행 시험은 수행하지 않았습니다. 그림은 신규 생성한 개념 일러스트입니다.

이 글의 검증 카드

자료 버전
Client tool_result/is_error 상시 문서·2026-09-22 확인. API 호출·조회·오류 주입 시험 없음
확인일
2026-09-22
검증 상태
개발자 주장
한계·주의
가상 예시입니다. 실제 API 요청·조회·오류 주입과 복구 시험은 하지 않았습니다.

함께 더 정확하게

질문·오류 제보

그림에서 이해되지 않는 부분이나 달라진 내용을 알려 주세요. 관리자가 확인하고 승인한 글만 공개됩니다.

공개된 질문·제보

    아직 공개된 질문·제보가 없습니다. 궁금한 부분을 먼저 남겨 주세요.