도구 사용 문제 해결

도구 사용 문제 해결 (Troubleshooting tool use)

흔한 도구 사용 오류들을 증상-해결 진단 표로 정리했어요. 각 해결 방법은 그 기능을 다루는 페이지를 함께 참조해요. 도구가 예상대로 동작하지 않을 때 이 표를 먼저 확인해 보세요.

출처: 문서

본문

가장 흔한 도구 사용 오류에 대한 증상-해결 표예요. 각 해결 방법은 그 기능을 소유한 페이지를 교차 참조해요.

Claude가 잘못된 도구를 호출할 때 (Claude calls the wrong tool)

증상	가능한 원인	해결 방법
Claude calls tool A when you wanted tool B	Description ambiguity	Sharpen descriptions. Differentiate tools by WHEN to use them, not only WHAT they do. See Define tools.
Claude never calls your tool	Tool name collision or overly-generic schema	Check for duplicate names across your tool list. Add `input_examples` to make the intended use concrete.
Claude calls with wrong parameter types	Model guessing at ambiguous schema	Add `strict: true` (if your schema is in the supported subset) or add `input_examples`.

B 도구를 원했는데 A를 호출할 때: 설명이 모호해서 그래요. 도구들이 무엇을 하는지뿐 아니라 언제 써야 하는지로 구분하도록 설명을 다듬으세요. 도구 정의하기를 참고하세요.
도구를 아예 호출하지 않을 때: 도구 목록에 이름 충돌이 있는지 확인하고, 의도한 사용을 구체적으로 만들려면 input_examples를 추가하세요.
잘못된 타입의 매개변수로 호출할 때: 스키마가 모호하면 모델이 추측해요. strict: true(스키마가 지원 부분집합에 있다면)를 추가하거나 input_examples를 추가하세요.

Claude가 도구 매개변수를 지어낼 때 (Claude invents tool parameters)

증상	가능한 원인	해결 방법
Parameter that doesn't exist in your schema	Model over-generation without strict mode	Add `strict: true` if your schema is in the supported subset.
Parameter values outside your enum	Missing strict mode or too-large enum	Shrink the enum or add `input_examples` showing valid choices.

스키마에 없는 매개변수를 생성하면: 엄격 모드 없이 과생성했어요. 스키마가 지원 부분집합에 있다면 strict: true를 추가하세요.
enum 밖의 값을 쓰면: 엄격 모드가 없거나 enum이 너무 커요. enum을 줄이거나 유효한 선택을 보여주는 input_examples를 추가하세요.

병렬 도구 호출이 동작하지 않을 때 (Parallel tool calls don't work)

증상	가능한 원인	해결 방법
Claude calls tools sequentially when parallel would be better	Message history formatting	Send multiple `tool_result` blocks in ONE user message, not one per turn. See Parallel tool use.
`disable_parallel_tool_use` seems ignored	Set too late in the conversation	Must be set on the request that returns `tool_use`. Setting it on a later request has no effect on earlier tool calls.

병렬이 나을 텐데 순차로 호출하면: 메시지 기록 포맷 문제예요. 턴마다 하나씩이 아니라 여러 tool_result 블록을 한 사용자 메시지에 보내세요. 병렬 도구 사용을 참고하세요.
disable_parallel_tool_use가 무시되는 것 같으면: 대화에서 너무 늦게 설정했어요. tool_use를 반환하는 요청에 설정해야 해요. 이후 요청에 설정해도 이전 도구 호출에는 효과가 없어요.

캐시가 계속 무효화될 때 (Cache keeps invalidating)

증상	가능한 원인	해결 방법
Every request is a cache miss	`tool_choice`, the thinking configuration, or `output_config.effort` varying between requests	Keep `tool_choice` stable or place the `cache_control` breakpoint before the variation point; hold the thinking configuration and effort level constant for the life of a cached conversation. See Tool use with prompt caching and Thinking and prompt caching.
Adding a tool mid-conversation breaks cache	Tool prepended to the tools array	Use `defer_loading: true` with tool search to append the tool inline instead of modifying the array head.

매 요청이 캐시 미스이면: 요청 사이에 tool_choice, thinking 구성, 또는 output_config.effort가 변하고 있어요. tool_choice를 안정적으로 유지하거나 변이 지점 앞에 cache_control 중단점을 두고, 캐시된 대화가 살아 있는 동안 thinking 구성과 effort 수준을 일정하게 유지하세요. 프롬프트 캐싱과 함께하는 도구 사용과 Thinking과 프롬프트 캐싱을 참고하세요.
대화 중간에 도구를 추가하면 캐시가 깨지면: 배열 앞에 도구를 추가하고 있어요. 배열 머리를 수정하는 대신 도구 검색과 함께 defer_loading: true를 써서 도구를 인라인으로 추가하세요.

요청 시점의 오류 (Errors at request time)

Error	Cause	Fix
`tool_use ids were found without tool_result blocks immediately after`	Missing `tool_result` for some `tool_use` ids, or `tool_result` is not the first content block in the user message	Return one `tool_result` for every `tool_use` block in the assistant response. Put `tool_result` blocks before any text. See Handle tool calls and Parallel tool use.
`was found without a corresponding <name>_tool_result block`	The previous assistant turn has a `server_tool_use` block with no result block (most often, Claude called it alongside a client tool), and either your next user message ended that turn (for example, with text after the `tool_result` blocks) or the resume request no longer defines that server tool (the message then ends with `but no <name> tool was provided`)	Send a user message containing only the `tool_result` blocks for the client `tool_use` ids and keep the same `tools` array. See Stop reasons and fallback.
`Unsupported regex feature in pattern field: ...`	A `pattern` in a strict tool's `input_schema` uses a regex feature that strict mode can't compile, such as a backreference, a lookaround, a word boundary, or a large `{n,m}` range	Simplify the pattern. Anchored patterns with basic quantifiers, character classes, and groups are supported; see JSON Schema limitations.
`All tools have defer_loading: true`	No tools visible to the model	At least one tool must be immediately loaded. The tool search tool itself must never have `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 배열을 유지하세요. 정지 이유와 폴백을 참고하세요.
Unsupported regex feature in pattern field: ...: 엄격한 도구의 input_schema에 있는 pattern이 역참조, lookaround, 단어 경계, 큰 {n,m} 범위 같은 엄격 모드가 컴파일할 수 없는 정규식 기능을 쓰기 때문이에요. 패턴을 단순화하세요. 기본 양자화·문자 클래스·그룹이 있는 앵커 패턴은 지원돼요. JSON Schema 한계를 참고하세요.
All tools have defer_loading: true: 모델에 보이는 도구가 없어요. 최소한 하나의 도구는 즉시 로드되어야 해요. 도구 검색 도구 자체에는 절대 defer_loading: true를 설정하지 마세요.

오류: thinking 블록을 수정할 수 없음 (Error: thinking blocks cannot be modified)

도구 호출 후 대화를 이어갈 때 메시지에 `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified가 담긴 400 invalid_request_error로 요청이 실패하면, 애플리케이션이 어시스턴트의 thinking 블록을 다시 보내기 전에 바꾸고 있는 거예요. 어시스턴트 메시지 전체를 그대로 보내고, 그 뒤에 tool_result를 추가하세요.

전체 오류와 해결 단계는 Thinking 블록 수정 불가를 참고하세요.

Claude가 도구 결과를 프롬프트 주입으로 표시할 때 (Claude flags tool results as prompt injection)

증상	가능한 원인	해결 방법
Claude refuses to act on a tool result, or asks the user to confirm instructions that came from it	Your own instructions are being delivered inside the `tool_result` content	Claude is trained to treat instructions inside tool results as potentially untrusted third-party content. Move your instructions out of the tool result: send them in a `user` turn after the `tool_result` block, or, on supported models, in a mid-conversation system message. Keep the tool result to just the data. See Mitigate jailbreaks and prompt injections.

증상: Claude가 도구 결과에 따라 행동하기를 거부하거나, 그 도구 결과에서 온 지침을 사용자가 확인하도록 요구함.
원인: 우리 지침을 tool_result 콘텐츠 안에 전달하고 있음.
해결: Claude는 도구 결과 안의 지침을 신뢰할 수 없는 제3자 콘텐츠로 취급하도록 훈련돼요. 지침을 도구 결과 밖으로 옮기세요. tool_result 블록 뒤의 user 턴에 보내거나, 지원 모델에서는 대화 중간 시스템 메시지로 보내세요. 도구 결과에는 데이터만 유지하세요. 재일브레이크와 프롬프트 주입 완화를 참고하세요.

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

증상	원인	해결 방법
String comparison on tool inputs fails with newer models	Unicode and forward-slash escaping differs between model versions	Parse with `json.loads()` or `JSON.parse()`. Never do raw string matching on serialized input.

증상: 새 모델에서 도구 입력에 대한 문자열 비교가 실패함.
원인: 모델 버전마다 Unicode와 슬래시 이스케이프가 다름.
해결: json.loads()나 JSON.parse()로 파싱하세요. 직렬화된 입력에 원시 문자열 매칭을 절대 하지 마세요.