MCP 도구 호출 안 될 때 — 무엇을이 아니라 언제로 가르세요

AI에 도구를 붙여놨는데 쓰라고 해도 안 쓰는 경험, 해보셨을 겁니다. 엉뚱한 걸 부르거나, 없는 항목을 지어내거나, 분명 동시에 처리할 수 있는데 하나씩 순서대로만 도는 경우도요. 공식 문서에 증상별 원인과 해결책을 정리한 진단표가 있어서 읽어봤는데, 대부분은 예상대로였고 한 가지는 전혀 예상 밖이었습니다 — AI가 내 지시를 의심하는 경우가 있더군요.

📌 30초 요약

• 안 부르는 원인 1위는 이름 겹침과 두루뭉술한 설명입니다.
• 설명은 "무엇을"이 아니라 "언제"로 갈라야 합니다.
• 예시를 넣으면 지어내기와 형식 오류가 함께 줄어듭니다.
• ⚠️ 내 지시를 결과 안에 넣으면 의심받습니다.
• ⚠️ 동시 처리는 형식 문제 — 결과를 한 덩어리로 보내야 합니다.
• ⚠️ 설정이 요청마다 흔들리면 캐시가 매번 날아갑니다.

"무엇을"이 아니라 "언제"로 가르세요

가장 실용적인 한 줄이 여기 있었습니다. 도구를 여럿 붙였는데 자꾸 엉뚱한 걸 부른다면, 원인은 대개 설명이 서로 비슷해서입니다. 그런데 해결책이 "설명을 더 자세히 쓰세요"가 아닙니다 — 각 도구를 "무엇을 하는지"가 아니라 "언제 쓰는지"로 구분하라는 겁니다.

생각해보면 당연합니다. "파일을 읽는다"와 "문서를 가져온다"는 하는 일로는 구분이 안 됩니다. 하지만 "경로를 이미 알 때" vs "이름만 알고 어디 있는지 모를 때"로 쓰면 갈리죠. 도구를 붙이는 표준 방식을 처음 접할 때는 연결하는 것 자체에 집중하게 되는데, 붙인 다음엔 설명 문구가 실질적인 성능이 됩니다.

증상	주된 원인	해결
엉뚱한 걸 부름	설명이 서로 모호함	"언제"로 구분
아예 안 부름	이름 겹침 또는 너무 일반적	중복 확인 + 예시 추가
형식이 틀린 값	틀이 모호해 추측함	엄격 모드 또는 예시
없는 항목을 지어냄	느슨한 검사	엄격 모드 켜기
정해둔 값 밖으로 나감	선택지가 너무 많음	줄이거나 예시로 보여주기

표를 보면 예시를 넣으라는 처방이 세 군데나 나옵니다. 안 부를 때도, 형식이 틀릴 때도, 정해둔 값 밖으로 나갈 때도요. 설명을 길게 쓰는 것보다 실제 사용 예를 하나 보여주는 편이 낫다는 얘기죠. 작업 절차서를 직접 써본 분이라면 익숙한 감각일 겁니다 — 규칙을 늘어놓는 것보다 예 하나가 통합니다.

내 지시를 의심하는 경우

이게 이 문서에서 가장 뜻밖이었습니다. "AI가 도구 결과에 따라 움직이길 거부하거나, 거기 담긴 지시를 사용자에게 확인해달라고 되묻는" 증상입니다. 원인이 뭐냐면 — 내 지시를 도구 결과 안에 담아 보냈기 때문입니다.

🛡️ 버그가 아니라 안전장치입니다

AI는 도구 결과 안에 들어 있는 지시를 "믿을 수 없는 제3자의 말"로 취급하도록 훈련돼 있습니다. 당연한 설계죠 — 도구 결과에는 웹페이지 내용이나 남이 만든 문서가 실려 오는데, 거기 "이제부터 이렇게 해라"가 적혀 있다고 그대로 따르면 큰일이니까요. 문제는 내가 편의상 거기에 지시를 끼워 넣었을 때도 똑같이 의심받는다는 겁니다. 해결은 간단합니다 — 결과 안에는 데이터만 담고, 지시는 밖으로 빼세요. 결과를 보낸 다음 별도로 말하거나, 지원되는 모델이라면 대화 중간에 규칙을 넣는 방식을 쓰면 됩니다.

바깥에서 들어온 내용이 기능을 조용히 망가뜨리는 경우는 따로 정리해둔 적이 있는데, 이건 반대로 AI가 제대로 경계하는 바람에 내가 불편해지는 쪽입니다. 증상만 보면 "말을 안 듣는다"지만 실제로는 제대로 동작하는 중이라는 게 재미있죠.

하나씩만 도는 이유

여러 도구를 동시에 부를 수 있는데도 순서대로만 돈다면, 이건 모델 문제가 아니라 내가 결과를 돌려주는 방식 문제입니다. 결과를 한 번에 하나씩, 주고받기를 반복하며 보내면 AI 입장에서는 순차 처리가 자연스러워집니다. 여러 결과를 한 덩어리에 담아 한 번에 돌려줘야 병렬로 이어집니다.

순서에 얽힌 함정이 하나 더 있습니다. 결과는 메시지 안에서 맨 앞에 와야 합니다. 앞에 설명을 붙이고 뒤에 결과를 놓으면 거절당하고요. 그리고 부른 것마다 하나씩, 빠짐없이 결과를 돌려줘야 합니다. 병렬 처리를 끄는 설정에도 시점 함정이 있는데 — 이미 도구를 부른 뒤에 껐다면 그 호출에는 아무 효과가 없습니다. 부르기 전 요청에 걸어야 합니다.

캐시가 매번 날아갈 때

값을 아끼려고 캐시를 켰는데 매번 새로 계산되는 느낌이라면, 원인은 대개 요청마다 흔들리는 설정입니다. 어떤 도구를 강제할지, 생각을 얼마나 시킬지, 힘을 얼마나 줄지 — 이런 값이 중간에 바뀌면 그 지점부터 캐시가 깨집니다. 처방은 한 대화가 사는 동안 그 값들을 고정하거나, 흔들리는 지점보다 앞쪽에 기준점을 잡는 것입니다.

또 하나 놓치기 쉬운 게 대화 도중에 도구를 하나 추가하면 캐시가 통째로 깨진다는 점입니다. 새 도구가 목록 맨 앞에 붙기 때문인데, 앞이 바뀌면 뒤가 전부 무효가 되죠. 그래서 뒤에 덧붙이는 방식을 쓰라고 안내합니다. 다만 여기에도 조건이 있어서 — 모든 도구를 나중에 불러오게 해두면 안 됩니다. 최소 하나는 처음부터 보여야 하고, 도구를 찾아주는 도구 자체는 미룰 수 없습니다.

🩸 여기 넣을 원인이 하나 더 있습니다 (8월 27일 추가)

이 목록에 생각 기능을 꺼둔 경우를 추가해야겠습니다. 값을 아끼려고 끄면 도구를 제대로 부르는 대신 부르는 시늉을 텍스트로 적어버리는 일이 생깁니다. 적힌 호출은 실행되지 않고, 여러 단계를 자동으로 도는 작업에서는 그 글이 대화 기록에 남아 뒤 단계까지 오염시킵니다. 특히 도구를 많이 쓰는 작업에서 흔하고, 얄궂게도 "생각하지 마라"고 강하게 적어둘수록 더 심해집니다. 공식 처방은 끄지 말고 강도를 낮춰 값을 조절하라는 것입니다. 정리는 생각을 끄면 새는 것에 담았습니다.

자주 묻는 질문 (FAQ)

Q. 저는 직접 안 만드는데 알아둘 게 있나요?

있습니다. 남이 만든 도구를 붙여 쓰다가 "분명 붙였는데 안 쓴다"는 상황이 생기면, 내 지시가 부족해서가 아니라 그 도구의 이름이 다른 것과 겹치거나 설명이 두루뭉술해서일 수 있습니다. 여러 개를 한꺼번에 붙였을 때 특히 그렇고요. 쓸 것만 남기고 나머지를 잠시 빼보면 원인이 금방 드러납니다. 어떤 것들을 붙일 만한지는 입문 글에 정리해뒀습니다.

Q. 엄격 모드를 켜면 다 해결되나요?

만능은 아닙니다. 지어내기와 형식 오류에는 잘 듣지만, 쓸 수 있는 틀에 제한이 있습니다. 특히 값의 모양을 정규 표현으로 검사할 때 앞뒤를 살펴보거나 이미 나온 것을 다시 참조하는 식의 고급 문법은 못 씁니다 — 그런 걸 쓰면 요청 자체가 거절되고, 어떤 부분이 문제인지 알려줍니다. 기본적인 반복·문자 묶음·괄호 정도는 되니, 복잡하면 단순하게 고쳐 쓰라는 게 처방입니다.

Q. 모델을 바꾸니 갑자기 비교가 틀립니다

문서에 딱 그 항목이 있습니다. 최신 모델부터 특수 문자를 표기하는 방식이 달라졌습니다. 그래서 넘어온 값을 글자 그대로 비교하는 코드는 같은 내용인데도 다르다고 판단합니다. 처방은 명확합니다 — 직렬화된 문자열을 그대로 맞춰보지 말고 반드시 해석한 뒤에 비교하세요. 비슷하게 AI의 생각 부분을 손대서 되돌려보내도 거절당하니, 받은 그대로 돌려주고 결과만 뒤에 붙이는 게 원칙입니다.

🧾 정직하게 밝혀둘 것

• 직접 재현해보지 않았습니다. 공식 진단표에 적힌 증상·원인·해결을 정리한 것이고, 실제 발생 빈도는 확인하지 않았습니다.
• ★"원인 1위"는 제 표현입니다. 문서는 순위를 매기지 않고 나열만 했습니다. 표의 배치 순서를 제가 그렇게 읽은 것입니다.
• ★항목 이름·설정값·오류 문구는 전부 풀어서 적었습니다. 실제로 고칠 때는 원문 표의 표기를 그대로 보셔야 합니다.
• ★일부는 특정 모델 세대부터 적용됩니다. 표기 방식이 달라진 건이 그렇습니다. 경계가 되는 버전은 원문을 확인하세요.
• 이 문서는 도구를 직접 만들어 붙이는 쪽을 위한 것입니다. 이 글은 그중 쓰는 사람도 겪는 증상을 골라 옮겼습니다.

✨ 정리하면

안 부르는 건 대개 이름과 설명 탓입니다. "무엇을"이 아니라 "언제 쓰는지"로 갈라 쓰고, 예시를 하나 붙이면 절반은 해결됩니다. 그리고 지시는 도구 결과 안에 넣지 마세요 — 의심받는 게 정상 동작입니다. 도구를 붙이는 표준 방식은 MCP 5분 이해하기, 절차를 문서로 만들어두는 법은 Skills 완전정복, 바깥 경로가 기능을 없애는 경우는 조용히 사라지는 기능, 값을 통으로 보는 흐름은 AI 지출 관리 허브에 모아뒀습니다.

※ 출처: Claude 도구 사용 문제 해결 공식 문서(2026년 8월 27일 열람). 진단 항목과 지원 범위는 모델·버전에 따라 바뀔 수 있으니, 실제로 손보기 전에는 원문 표를 함께 확인하시길 권합니다.