잘못된 도구를 사용하는 AI agent를 debugging하려면 model이 본 정확한 tool list와 context를 재구성한 뒤 아무것도 실행하지 않고 selection을 테스트하세요. 많은 failure는 겹치는 name, description, argument shape 또는 missing context에서 발생하지만 trace를 살펴보면 올바른 call이 잘못된 result를 반환한 경우도 있습니다.
어느 stage가 실패했는지 특정하기 전에는 prompt를 바꾸지 마세요.
현재 MCP 도구 명세는 name, description, input schema, optional output schema를 client에 표시합니다. 관찰할 수 있는 contract이므로 숨은 model reasoning 탓으로 돌리기 전에 검사하세요.
failure를 정확히 분류하세요
- Wrong selection: 표시된 다른 tool이 task에 더 적합했습니다.
- Wrong arguments: 선택한 tool은 맞지만 ID, enum, scope, required field가 틀렸습니다.
- Premature call: agent가 필요한 context나 approval을 모으기 전에 올바른 tool을 사용했습니다.
- Misleading result: tool이 backend를 올바르게 호출했지만 ambiguous, stale, malformed response를 반환했습니다.
- Unsafe execution: selection은 유효했지만 tool 뒤에서 authorization, idempotency, approval이 실패했습니다.
각 사례에는 서로 다른 변경이 필요합니다. asynchronous job이 끝나기 전에 ok를 반환하는 provider response는 도구 이름을 바꿔도 고쳐지지 않습니다.
정확한 trace와 tool set를 가져오세요
model 및 version, system prompt, retrieved context, conversation prefix, 표시된 전체 tool list, tool definition, 선택한 name, argument, result, policy decision, downstream outcome을 기록하세요.
전체 목록이 중요합니다. 의심되는 file 두 개만 읽으면 plugin이나 session에서 노출한 세 번째 tool을 놓칠 수 있습니다. 실패한 실행에서 사용할 수 없었던 tool은 선택의 원인이 될 수 없습니다.
agent observability 가이드는 selection을 backend effect에 연결하는 trace를 설명합니다.
비슷한 tool을 나란히 놓으세요
[
{
"name": "list_files",
"description": "List entries directly inside one directory.",
"inputSchema": { "directory": "string" }
},
{
"name": "search_files",
"description": "Find files whose path or content matches a query across a directory tree.",
"inputSchema": { "directory": "string", "query": "string" }
}
]
description에는 서로 다른 output과 trigger가 명시되어 있습니다. schema도 이 차이를 강화합니다. “works with files”와 “finds files” 같은 일반적인 쌍은 model이 경계를 만들어 내게 합니다.
공통 verb, noun, description, example, required field, result shape를 확인하세요. 두 tool이 같은 user intent를 provider별 구현으로 나타낸다면, 가능하면 semantic tool 하나만 노출하고 그 뒤에서 provider를 선택하세요.
argument를 task language에 맞추세요
order_id, customer_id, deployment_id를 사용해 서로 관련 없는 id field 세 개를 대체하세요. enum, format, bound, description을 추가합니다. model이 제공하게 하지 말고 인증된 context에서 tenant와 user scope를 가져오세요.
tool에 agent가 모를 수 있는 정보가 필요하다면 prerequisite를 명시하고 안정적인 missing-context error를 반환하세요. 추측한 free-text value를 받는 대신 identifier를 가져오는 별도의 read tool도 고려하세요.
MCP 도구 설계 가이드는 bounded input과 structured error를 다룹니다.
selection을 탓하기 전에 result를 검사하세요
result는 agent에게 무슨 일이 있었고 다음에 무엇을 할 수 있는지 알려 줘야 합니다. 안정적인 status, resource 또는 operation ID, polling 또는 approval requirement를 반환하세요. 전체 provider payload나 generic success string은 반환하지 마세요.
asynchronous work에서는 accepted, running, completed, failed를 구분하세요. creation이 pending인데 result가 “created”라고 하면 agent가 다음 tool을 너무 일찍 호출할 수 있습니다.
selection-only evaluation을 만드세요
model, prompt, tool list, 관련 context를 고정하세요. execution을 허용하지 않고 선택한 tool과 argument를 요청합니다. 다음 사례를 포함하세요.
- 모든 tool의 명확한 positive case
- 가장 가까운 pair의 near-miss case
- required context가 빠진 request
- 어떤 tool도 호출하면 안 되는 request
- retrieved content 안의 hostile instruction
- 원래 failing request와 sanitize한 variant
nondeterministic case를 반복하고 trial 수를 보고하세요. contract element 하나씩 바꾼 뒤 같은 set를 다시 실행합니다. 이렇게 하면 name, description, schema, context 가운데 어떤 변경이 selection을 개선했는지 분리할 수 있습니다.
실패한 contract를 최소한으로 바꾸세요
모호한 tool의 name을 바꾸고, description을 좁히고, prerequisite를 추가하고, argument를 제한하고, 섞인 read-write operation을 나누거나, 구분할 수 없는 tool 두 개를 합치세요. 관련 없는 tool이 collision을 만들면 task에 표시되는 set를 줄입니다.
여러 tool에 실제로 걸친 workflow policy에는 system-prompt guidance를 사용하세요. ambiguity가 contract에 있는데도 과거의 mistake마다 one-off rule을 계속 쌓지 마세요.
selection이 통과한 뒤에만 execution을 다시 활성화하세요
그런 다음 isolated environment에서 valid, invalid, unauthorized, repeated, interrupted, policy-gated call을 테스트하세요. model이 올바른 tool을 고른다고 해서 tool이 안전한 것은 아닙니다.
아래 프롬프트는 변경을 권장하기 전에 failure를 재구성하고 분류합니다. execution을 꺼 두므로 destructive tool을 대상으로 debugger를 실행해도 두 번째 incident가 생기지 않습니다.