MCP 툴 설명을 개선해 에이전트의 도구 선택 정확도 높이기

에이전트가 엉뚱한 도구를 고르거나 파라미터를 반복해서 틀린다면 모델부터 교체할 일은 아니다. 에이전트가 판단 근거로 삼는 툴 설명이 목적과 제약을 충분히 전달하는지 먼저 확인해야 한다.

arXiv에 발표된 「MCP Tool Descriptions Are Smelly!」는 배포된 MCP 서버의 툴 설명 대부분이 모호하거나 불완전하며, 이런 설명이 에이전트 성능을 떨어뜨리는 주요 원인이라고 실증적으로 설명한다. 논문이 제안한 증강 MCP 툴 설명(Augmented MCP Tool Description)은 문구를 다듬는 데 그치지 않는다. 에이전트가 툴의 용도와 입력 조건, 실패 가능성을 판단할 수 있도록 설명을 체계적으로 설계하는 방법이다.

짧은 설명이 도구 선택을 어렵게 만든다

다음과 같은 설명은 사람이 봐도 툴의 정확한 동작을 알기 어렵다.

{
  "name": "search_files",
  "description": "Search for files",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {"type": "string"},
      "path": {"type": "string"}
    }
  }
}

Search for files만으로는 검색 대상과 방식을 구분할 수 없다. 파일명을 찾는지, 파일 내용 전체를 검색하는지 알 수 없고, path에 절대 경로와 상대 경로 중 무엇을 넣어야 하는지도 드러나지 않는다. 권한이 없는 디렉토리에 접근했을 때의 처리 방식도 빠져 있다. 결국 에이전트가 설명에 없는 조건을 추측하게 된다.

논문은 이를 툴 설명의 악취(Tool Description Smells)라고 부르며 여섯 가지 패턴으로 나눈다. 불명확한 목적(Vague Purpose), 파라미터 설명 부재(Missing Parameter Context), 예제 없음(No Examples), 에러 처리 미명시(Undocumented Errors), 사용 제약 미기재(Hidden Constraints), 반환값 불명확(Unclear Return Values)이다.

에이전트가 판단할 근거를 설명에 담는다

좋은 설명은 툴의 기능만 알리는 문장이 아니다. 무엇을 처리하는지와 어떤 상황에서 선택해야 하는지를 구분하고, 각 파라미터의 타입·형식·허용 범위·기본값을 적어야 한다. 경계 조건과 예외도 설명에 포함한다.

호출 예제는 에이전트가 입력 형식을 구성할 때 참고할 구체적인 패턴을 제공한다. 여기에 발생 가능한 에러와 대응 방법, 레이트 리밋이나 파일 크기 제한, 필요 권한처럼 호출 전에 알아야 할 제약을 함께 적는다. 고품질 MCP 툴 설명에 필요한 요소는 목적과 용도, 파라미터 제약, 사용 예제, 에러 처리, 사용 제약의 다섯 가지다.

이를 search_files에 적용하면 설명의 밀도가 다음처럼 달라진다.

{
  "name": "search_files",
  "description": "지정된 디렉토리 내에서 파일명 또는 파일 내용에 특정 텍스트가 포함된 파일 목록을 반환한다. 코드베이스에서 특정 함수, 변수, 텍스트 패턴이 사용된 위치를 찾을 때 사용한다. 바이너리 파일은 자동으로 제외된다.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "검색할 텍스트 패턴. 정규식 지원. 예: 'def main', 'TODO:', 'import.*pandas'"
      },
      "path": {
        "type": "string",
        "description": "검색할 디렉토리 절대 경로. 예: '/home/user/project'. 상대 경로 사용 불가."
      },
      "file_pattern": {
        "type": "string",
        "description": "검색 대상 파일 패턴. 예: '*.py', '*.{ts,tsx}'. 기본값: '*' (모든 파일)"
      }
    },
    "required": ["query", "path"]
  },
  "examples": [
    {
      "description": "Python 파일에서 main 함수 찾기",
      "input": {"query": "def main", "path": "/home/user/project", "file_pattern": "*.py"},
      "expected_output_summary": "main 함수가 정의된 Python 파일 목록과 라인 번호"
    }
  ],
  "errors": {
    "PathNotFound": "path가 존재하지 않을 때. path를 확인하거나 list_directory 툴로 먼저 구조를 파악할 것.",
    "PermissionDenied": "접근 권한이 없을 때. 다른 경로를 시도할 것."
  },
  "constraints": {
    "max_results": 1000,
    "max_file_size_mb": 10,
    "rate_limit": "분당 100회"
  }
}

설계 범위는 개별 툴에 머물지 않는다. 툴 사이의 선후 관계도 에이전트의 선택에 영향을 준다. 파일을 쓰기 전에 기존 내용을 읽어야 한다면 write_file 설명에서 먼저 read_file을 호출하도록 권장할 수 있다. 이런 워크플로우 힌트는 적절한 툴을 골랐더라도 순서를 잘못 잡아 실패하는 상황을 줄인다.

⤢✕

소스와 호출 로그에서 설명을 보강한다

MCP 툴이 수백 개라면 모든 설명을 사람이 직접 고치는 방식은 유지하기 어렵다. 기존 툴의 소스 코드와 파라미터 스키마, 실제 호출 로그를 분석하고 LLM이 보강된 설명을 생성하는 파이프라인으로 작업을 자동화할 수 있다.

소스 분석 결과에서는 툴이 실제로 수행하는 동작과 제약을 가져오고, 호출 로그에서는 성공과 실패가 반복되는 입력 패턴을 추출한다. 이 정보를 기존 설명 및 입력 스키마와 함께 LLM에 전달해 목적, 파라미터, 예제, 에러, 제약을 채운다.

class ToolDescriptionAugmenter:
    def __init__(self, llm_client):
        self.llm = llm_client

    async def augment(self, tool: MCPTool) -> AugmentedTool:
        # 소스 코드 분석
        source_analysis = await self._analyze_source(tool.source_code)

        # 실제 호출 로그에서 패턴 추출
        call_patterns = await self._extract_patterns(tool.call_logs)

        # LLM으로 설명 생성
        augmented_description = await self.llm.generate(
            system=AUGMENTATION_PROMPT,
            user=f"""
            원본 툴 이름: {tool.name}
            원본 설명: {tool.description}
            소스 코드 분석: {source_analysis}
            실제 사용 패턴: {call_patterns}
            파라미터 스키마: {tool.input_schema}

            위 정보를 바탕으로 다음을 포함하는 고품질 툴 설명을 생성하라:
            1. 명확한 목적과 사용 시나리오
            2. 각 파라미터의 상세 설명, 형식, 제약
            3. 실제 사용 예제 2-3개
            4. 발생 가능한 에러와 처리 방법
            5. 사용 제약 (레이트 리밋, 파일 크기 등)
            """
        )
        return AugmentedTool(original=tool, augmented=augmented_description)

예제 섹션도 같은 파이프라인에서 만들 수 있다. 실제 호출 로그의 성공 사례를 추출한 뒤 파라미터 조합을 분석해 대표 예제를 고른다. LLM은 여기에 빈 쿼리, 최대 길이 입력, 특수 문자가 포함된 입력 같은 경계 조건 케이스를 추가해 설명을 보완한다.

실패 로그를 설명의 다음 버전에 반영한다

툴 동작이 바뀌거나 에이전트가 같은 유형의 호출 오류를 반복한다면 설명도 다시 손봐야 한다. 변경 전후의 에이전트 행동을 A/B 테스트로 비교하고 더 나은 설명을 선택하는 피드백 루프가 필요한 이유다.

가장 직접적인 피드백은 툴 호출 실패 로그에서 나온다. 에이전트가 넘긴 파라미터, 반환된 에러, 실패 후 수정한 호출을 함께 보면 설명에서 어느 조건이 불명확했는지 찾을 수 있다. 툴 설명을 버전으로 관리하면 동작 변경과 설명 변경을 맞추면서 각 수정이 에이전트 행동에 미친 영향도 추적할 수 있다.

설명 품질이 성능 지표에 남기는 차이

논문의 실험에서 고품질 증강 툴 설명은 에이전트의 툴 선택 정확도를 평균 23% 높였다. 특히 기능이 비슷한 툴 사이에서 올바른 대상을 고르는 정밀도(precision)가 크게 개선됐다. search_files와 find_files가 함께 있을 때 모호한 설명에서는 선택이 무작위에 가까웠지만, 명확한 설명에서는 95% 이상의 정확도를 보였다.

여러 벤치마크에서는 증강 설명을 적용한 뒤 잘못된 파라미터 때문에 툴 호출이 실패하는 비율이 40-60% 감소했다. 감소 폭이 컸던 항목은 경로·날짜·열거형 값과 같은 파라미터 형식 오류와 필수 파라미터 누락이었다. 예제를 포함한 설명에서는 파라미터 형식 오류가 거의 사라졌다.

에이전트 성능은 세 가지 지표로 측정한다. 작업 완료율(Task Completion Rate)은 에이전트가 툴을 이용해 주어진 작업을 끝낸 비율이다. 툴 호출 효율성(Tool Call Efficiency)은 완료까지 몇 번의 호출이 필요한지를 나타내며, 설명이 명확할수록 시행착오와 호출 수가 줄어든다. 비용 효율성(Cost Efficiency)은 불필요한 호출에 따른 토큰 비용까지 반영한다. 설명 품질 개선은 이 비용을 줄이는 데 직접 연결된다.

모든 툴을 한꺼번에 같은 수준으로 고칠 필요는 없다. 호출 빈도가 높은 상위 20%의 툴이 전체 성능의 80%에 영향을 미치므로, 파레토 원칙에 따라 자주 쓰이는 툴부터 개선하는 편이 실무적인 우선순위다.

⤢✕

툴 설명을 운영 자산으로 다루기

MCP 툴 설명은 에이전트 시스템의 눈에 잘 띄지 않는 품질 변수다. 모델을 바꾸거나 프롬프트를 고치는 것보다 툴 설명을 손보는 편이 더 빠르고 저렴하게 성능을 높이는 경우가 많다.

증강 툴 설명은 사람의 검토와 LLM 자동화를 결합할 수 있는 개선 경로를 제공한다. 호출 로그로 문제가 잦은 툴을 찾고, 소스와 스키마를 바탕으로 설명을 보강한 뒤 A/B 테스트와 실패 로그로 다음 버전을 결정한다. 이 과정을 MCP 서버 개발의 일급 관심사로 다뤄야 에이전트 시스템의 장기적인 신뢰성을 확보할 수 있다.