17장. 도구 정의와 설계

에이전트의 능력은 결국 "어떤 도구를 어떻게 줬는가"로 결정된다. Claude는 도구를 직접 실행하지 않는다. 도구 호출(tool_use 블록)을 만들어 낼 뿐이고, 실제 실행과 결과 반환은 너의 하네스(harness)가 담당한다. 따라서 도구 정의는 단순한 함수 시그니처가 아니라, 모델이 "언제 이 도구를 부를지"를 판단하는 의사결정 근거이자, 하네스가 "이 호출을 게이팅·렌더링·감사·병렬화할 수 있는지"를 결정하는 인터페이스다. 이름 하나, 설명 한 줄, 스키마의 enum 하나가 모델의 호출 정확도와 시스템의 안전 경계를 동시에 좌우한다.

CCA-F의 "도구 설계와 MCP 통합" 도메인은 전체의 18%를 차지하며, 그중 도구 정의의 구조와 설계 원칙은 가장 기본이자 가장 자주 출제되는 영역이다. 시험은 "이 도구 정의의 무엇이 잘못됐는가", "이 작업을 bash로 둘 것인가 전용 도구로 승격할 것인가", "왜 이 설명문이 호출 정확도를 떨어뜨리는가" 같은 의사결정 문제를 낸다. 단순 암기가 아니라 "왜 이 설계가 정답인가"를 판단할 수 있어야 한다.

이 장을 마치면 다음을 할 수 있다.

• 도구 정의의 세 구성요소(name, description, input_schema)와 JSON Schema 제약을 정확히 설명하고, 잘못된 정의를 식별할 수 있다.
• tool_choice, strict, 구조화 출력(output_config.format)이 도구 동작에 어떻게 영향을 주는지 구분할 수 있다.
• 좋은 도구 설계의 원칙과 대표적 안티패턴(과다한 도구, 모호한 설명, bash 남용, 비결정적 스키마)을 진단하고 교정할 수 있다.
• bash 도구와 전용 도구 중 무엇을 선택할지 보안 경계·렌더링·병렬성 기준으로 판단할 수 있다.