에이전트의 도구 선택을 개선하는 MCP 설명 설계와 평가

도구의 기능보다 호출 판단 근거를 써야 한다

arXiv 논문 2602.14878 「Augmented MCP Tool Descriptions for Improved Agent Tool Selection」은 AI 에이전트가 도구를 잘못 고르는 원인을 모델 능력만으로 설명하지 않는다. 대규모 실험을 통해 도구 설명의 품질 결함이 선택 실패의 근본 원인이 될 수 있음을 보이고, 의도 명확화, 사용 예시 임베딩, 파라미터 타입 주석, 에러 응답 명세, 검색 친화적 키워드 배치를 증강 기법으로 제안한다.

이 기법을 적용한 MCP 서버에서는 에이전트의 도구 선택 정확도가 평균 31.4%, 태스크 완료율이 26.8% 향상되었다고 보고한다. 핵심은 설명을 단순한 기능 소개가 아니라 에이전트가 호출 여부와 실행 순서를 판단하는 운영 명세로 다루는 데 있다.

MCP 도구 설명에서 자주 빠지는 정보는 “언제, 왜 이 도구를 써야 하는가”다. 에이전트는 현재 태스크와 각 설명의 의미적 유사도를 바탕으로 후보를 고르므로, 무엇을 수행하는지만 적어서는 비슷한 도구 사이의 경계를 판단하기 어렵다.

설명에는 이 도구를 호출할 구체적인 상황, 다른 유사 도구를 선택해야 하는 상황, 호출 전에 충족해야 할 조건이 드러나야 한다.

{
  "name": "execute_sql_query",
  "description": "읽기 전용 SELECT 쿼리를 데이터베이스에 실행하고 결과를 반환한다. 데이터 조회, 집계, 필터링, 조인 작업에 사용한다. INSERT·UPDATE·DELETE 등 데이터 변경 작업에는 execute_sql_mutation 도구를 사용할 것. 쿼리 실행 전 테이블 구조를 모른다면 먼저 get_table_schema 도구로 스키마를 확인할 것을 권장한다. 대용량 테이블(100만 행 이상)에서 LIMIT 없이 실행하면 타임아웃이 발생할 수 있다.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "실행할 SELECT SQL 쿼리. 세미콜론으로 끝내야 한다. 예: 'SELECT id, name FROM users WHERE created_at > '2024-01-01' LIMIT 100;'"
      },
      "database": {
        "type": "string",
        "enum": ["production", "staging", "analytics"],
        "description": "대상 데이터베이스 환경. 기본값: 'production'. 테스트 목적이라면 'staging'을 사용할 것."
      },
      "timeout_seconds": {
        "type": "integer",
        "minimum": 1,
        "maximum": 300,
        "default": 30,
        "description": "쿼리 실행 타임아웃(초). 복잡한 집계 쿼리는 60-120초로 설정을 권장한다."
      }
    },
    "required": ["query"]
  }
}

이 설명은 읽기 작업과 변경 작업의 경계를 execute_sql_mutation과의 비교로 보여 준다. 스키마를 모를 때는 get_table_schema를 먼저 호출하도록 안내하고, 대용량 테이블에서는 LIMIT 없이 실행할 때의 제약도 함께 명시한다. 이런 정보는 잘못된 도구 선택과 파라미터 구성 오류를 동시에 줄이는 판단 근거가 된다.

인자 형식과 실패 이후의 행동까지 명시한다

JSON Schema의 type만으로는 인자가 실제로 어떤 값을 받아야 하는지 충분히 전달하기 어렵다. "type": "string"만 보고서는 URL, 파일 경로, 자유 텍스트를 구별할 수 없다. 논문은 파라미터 설명에 형식 패턴, 허용 범위, 제외 케이스를 명시하는 작업이 도구 선택보다 파라미터 구성 정확도에 더 큰 영향을 미친다는 실험 결과를 제시한다.

오류 설명도 에러 코드 목록에 머물러서는 안 된다. 에이전트가 실패 원인을 해석한 뒤 어떤 행동을 이어갈지까지 연결해야 복구 명세가 된다.

{
  "errors": {
    "QUERY_SYNTAX_ERROR": {
      "cause": "SQL 문법 오류",
      "agent_action": "쿼리 문법을 수정하여 재시도. 에러 메시지의 LINE/COLUMN 정보를 참조할 것."
    },
    "TABLE_NOT_FOUND": {
      "cause": "존재하지 않는 테이블 참조",
      "agent_action": "get_table_schema 도구로 사용 가능한 테이블 목록을 먼저 조회한 후 재시도."
    },
    "QUERY_TIMEOUT": {
      "cause": "쿼리가 timeout_seconds 이내에 완료되지 못함",
      "agent_action": "LIMIT 절 추가 또는 WHERE 조건 강화 후 재시도. 또는 timeout_seconds 값을 증가시킬 것."
    },
    "PERMISSION_DENIED": {
      "cause": "현재 세션이 해당 테이블에 대한 SELECT 권한이 없음",
      "agent_action": "다른 database 환경(staging/analytics)으로 전환하거나 태스크를 상위 에이전트에 에스컬레이션할 것."
    }
  }
}

문법 오류라면 쿼리를 고치고, 테이블을 찾지 못했다면 스키마부터 조회하며, 타임아웃에는 쿼리 범위나 제한 시간을 조정하도록 유도한다. 권한 오류는 다른 환경으로 전환하거나 상위 에이전트에 넘긴다. 같은 요청만 되풀이하는 단순 재시도 루프 대신 오류별 복구 경로를 선택하게 만드는 구조다. 논문에서는 에러 명세를 보강한 도구의 실패 후 복구 성공률이 44.2% 향상되었다.

검색되는 설명은 사용자 표현의 차이를 흡수한다

도구가 수십 개를 넘는 MCP 서버에서는 모든 설명을 에이전트의 컨텍스트 윈도우에 넣기 어렵다. 이때 MCP 클라이언트나 에이전트 프레임워크는 도구 설명을 벡터 임베딩하고, 태스크 쿼리와의 의미 유사도를 기준으로 후보를 사전 필터링하는 경우가 많다. 설명은 사람이 읽기 쉬워야 할 뿐 아니라 의미 검색에서도 발견될 수 있어야 한다.

같은 작업을 가리키는 동의어와 별칭은 설명 안에 자연스럽게 포함한다. 파일 검색이라면 “search”, “find”, “locate”, “discover”, “lookup”처럼 사용자가 선택할 수 있는 표현을 함께 담는다.

전문 용어와 일반 표현도 병기한다. “JWT 토큰 검증”과 “인증 토큰 확인”을 같이 쓰면 요청의 기술적 표현 수준이 달라도 적절한 도구와 연결될 가능성이 높아진다. 설명 앞부분에는 “데이터베이스에서 사용자 정보를 조회한다”처럼 태스크를 나타내는 동사와 목적어를 먼저 배치한다.

설명 안에 도구 간 실행 관계를 남긴다

멀티스텝 태스크에서는 개별 도구의 역할만 정확해도 충분하지 않다. 어떤 도구가 선행되어야 하고, 성공 또는 실패 뒤에 무엇을 실행할지 알아야 전체 작업을 끝낼 수 있다. 사전 조건과 권장 후속 도구를 각 설명에 인라인으로 넣으면 에이전트가 그 정보를 실행 계획으로 조립할 수 있다.

⤢✕

이 구조에서 설명은 도구 검색용 텍스트이면서 의존 그래프의 일부다. 에이전트는 사전 조건을 먼저 충족하고, 오류가 생기면 명세에 적힌 복구 행동을 실행하며, 결과가 유효하면 후속 도구로 넘어간다.

선택 정확도만으로는 설명 품질을 판단할 수 없다

도구 설명을 바꾼 뒤 효과를 측정하려면 서로 다른 실패 지점을 구분해야 한다. 정답 도구를 골랐더라도 파라미터가 틀리거나 실행 순서가 잘못되면 태스크는 끝나지 않는다. arXiv 2602.14878은 평가 지표를 네 계층으로 나눈다.

도구 선택 정확도(Tool Selection Accuracy, TSA)는 정답 도구를 1순위로 고른 비율이며 TSA = (정답 도구 1순위 선택 횟수) / (전체 태스크 수)로 계산한다.

상위 K 재현율(Top-K Recall@K)은 정답 도구가 후보 상위 K개 안에 포함된 비율이다. 도구가 많은 환경에서는 TSA만으로 미세한 변화를 포착하기 어려워 Recall@3과 Recall@5를 함께 측정한다.

파라미터 구성 정확도(Parameter Construction Accuracy, PCA)는 정답 도구를 선택한 호출 가운데 파라미터의 형식과 값이 모두 유효한 비율이다. 계산식은 PCA = (파라미터 형식·값이 모두 유효한 호출 횟수) / (정답 도구 선택 횟수)다.

태스크 완료율(Task Completion Rate, TCR)은 도구를 사용해 최종 작업까지 성공한 비율이다. TSA와 PCA가 높더라도 워크플로우 순서가 잘못되면 TCR은 낮게 나타날 수 있다.

class ToolSelectionEvaluator:
    def __init__(self, benchmark_suite: list[TaskSpec]):
        self.benchmark = benchmark_suite
        self.results: list[EvalResult] = []

    def evaluate(self, agent, tool_registry: MCPToolRegistry) -> EvalReport:
        for task in self.benchmark:
            selected_tools = agent.select_tools(task.query, tool_registry)
            
            tsa = selected_tools[0].name == task.expected_tool
            recall_3 = task.expected_tool in [t.name for t in selected_tools[:3]]
            recall_5 = task.expected_tool in [t.name for t in selected_tools[:5]]
            
            if tsa:
                call_result = agent.execute_tool(
                    selected_tools[0],
                    task.sample_input
                )
                pca = call_result.is_valid_call
                tcr = call_result.task_completed
            else:
                pca = False
                tcr = False
            
            self.results.append(EvalResult(
                task_id=task.id,
                tsa=tsa,
                recall_3=recall_3,
                recall_5=recall_5,
                pca=pca,
                tcr=tcr,
                failure_category=self._classify_failure(call_result)
            ))
        
        return EvalReport.from_results(self.results)

    def _classify_failure(self, result: CallResult) -> FailureCategory:
        if result.error_type == "WRONG_TOOL":
            return FailureCategory.TOOL_SELECTION_ERROR
        elif result.error_type == "INVALID_PARAMS":
            return FailureCategory.PARAMETER_CONSTRUCTION_ERROR
        elif result.error_type == "WORKFLOW_ORDER":
            return FailureCategory.WORKFLOW_SEQUENCE_ERROR
        elif result.error_type == "TIMEOUT":
            return FailureCategory.PERFORMANCE_CONSTRAINT_ERROR
        return FailureCategory.UNKNOWN

A/B 평가에서 실패 원인을 분리한다

설명 변경의 효과는 동일한 태스크 셋으로 원본 설명(Control)과 증강 설명(Treatment)을 비교해야 한다. 에이전트 실행에는 비결정적 특성이 있으므로 각 설명 버전에서 같은 태스크를 최소 5회 이상 반복하고 평균과 표준편차를 함께 보고한다.

오답 도구를 선택했다면 도구 선택 오류다. 정답과 선택된 도구의 설명 유사도를 분석하면 어떤 표현이 혼동을 만들었는지 찾을 수 있다.

도구는 맞지만 인자의 형식이나 값이 틀렸다면 파라미터 구성 오류로 분류한다. 이 경우에는 파라미터 형식 명세와 예시가 충분한지 확인한다. 필요한 사전 조건 도구를 먼저 실행하지 않았다면 워크플로우 순서 오류이며, 타임아웃이나 레이트 리밋 초과처럼 설명에 적힌 제약을 놓쳤다면 성능 제약 오류에 해당한다.

이 분류를 유지해야 TSA가 개선되지 않은 이유와 TCR만 떨어진 이유를 서로 다른 설명 결함으로 추적할 수 있다.

설명 변경도 회귀 테스트 대상으로 다룬다

도구 설명은 코드와 분리된 부가 문서처럼 보이지만, 에이전트의 실행 경로를 바꾼다는 점에서는 동작을 구성하는 일부다. 설명을 업데이트할 때 기존 태스크가 퇴행하지 않는지 CI에서 검사해야 한다.

또한 에이전트가 산출한 선택 신뢰도 점수가 임계값보다 낮다면 상위 에이전트나 인간 감독자에게 넘기는 경로를 둘 수 있다.

⤢✕

임계값은 모든 도구에 똑같이 적용하지 않는다. 데이터 조회 도구는 0.5로 자율 실행을 허용하되, 데이터 변경, 외부 시스템 연동, 금융 처리 도구에는 0.85 이상의 높은 임계값을 두어 불확실한 호출을 억제한다.

증강 설명이 평가 지표에 미친 영향

논문은 32개 MCP 서버의 847개 도구와 4,200개 태스크 쿼리를 대상으로 실험했다. GPT-4o, Claude 3.5 Sonnet, Gemini 1.5 Pro를 같은 벤치마크에 적용해 모델 사이의 일반화 가능성도 검증했다.

원본 설명에서 64.3%였던 평균 TSA는 증강 설명에서 95.7%로 높아져 31.4%p 개선되었다. 세 모델에서 유사한 개선폭이 나타나 특정 모델에만 국한된 효과가 아님을 확인했다.

PCA는 71.2%에서 93.8%로 22.6%p 향상되었다. 파라미터 예시만 추가했을 때도 형식 오류가 68% 감소했다.

TCR은 58.1%에서 84.9%로 26.8%p 높아졌다. 멀티스텝 태스크, 즉 3개 이상의 도구를 연속으로 사용하는 작업에서는 개선폭이 35.2%p로 가장 컸다.

기법별로 보면 의도 명확화가 TSA 개선에 46%로 가장 크게 기여했고, 파라미터 예시는 PCA 개선의 54%를 담당했다. 에러 응답 명세는 실패 후 복구 성공률에 44.2% 기여했다. 키워드 배치는 임베딩 검색에서 28%, 워크플로우 힌트는 멀티스텝 TCR에서 35.2%의 개선과 연결되었다.

⤢✕

도구가 늘수록 설명 품질의 영향도 커진다

도구 수가 증가하면 설명 품질이 선택 결과에 미치는 영향은 비선형적으로 커진다. 도구가 10개 미만인 MCP 서버에서는 에이전트가 저품질 설명을 어느 정도 보정하지만, 50개 이상에서는 저품질 설명의 TSA가 32.1%까지 급락한다.

의미 검색 단계에서 설명 품질이 낮은 정답 도구가 상위 K 후보에서 제외되는 빈도가 도구 수에 비례해 늘어나기 때문이다. 도구가 100개인 환경에서 정답이 상위 10개 후보에 포함될 확률은 원본 설명에서 61%였지만, 증강 설명에서는 97.3%로 개선되었다.

대응 방법 중 하나는 비슷한 도구를 카테고리로 묶는 도구 카테고리 계층화다. 에이전트가 카테고리를 먼저 선택하고 그 안에서 개별 도구를 찾도록 검색 공간을 나눈다.

사용 빈도에 따른 노출 우선순위도 적용할 수 있다. 호출이 잦은 도구는 컨텍스트에 우선 포함하고, 사용 빈도가 낮은 도구는 검색 쿼리와의 유사도가 일정 임계값 이상일 때 후보에 넣는다.

MAID를 기업 MCP 설명 표준으로 적용한다

논문은 기업 MCP 서버의 설명 작성 표준으로 MAID(MCP Augmented Information Design) 프레임워크를 제안한다.

Mission은 도구의 핵심 기능과 사용 의도를 2-3문장으로 기술하고 유사 도구와의 차이를 포함한다. Arguments에는 각 파라미터의 타입, 형식 패턴, 허용 범위, 기본값, 제약 조건, 사용 예시를 기록한다.

Interactions는 호출 전에 실행할 사전 조건 도구와 완료 뒤 권장되는 후속 도구를 연결한다. Diagnostics에는 발생 가능한 모든 에러 코드와 에이전트가 취할 복구 행동을 적는다. Examples는 실제 입력과 출력으로 구성한 2-3개의 사용 예시를 제공한다.

기존 도구를 MAID 기준으로 0-100점으로 평가하는 설명 품질 스코어카드를 운영하면 개선 순서를 정할 수 있다. 낮은 점수만 보는 대신 호출 빈도와 비즈니스 중요도를 가중치로 반영해 우선순위를 조정한다.

class MAIDScorecard:
    WEIGHTS = {
        "mission_clarity": 0.25,      # 의도 명확성
        "argument_completeness": 0.30, # 인자 명세 완성도
        "interaction_hints": 0.20,     # 상호작용 명세
        "diagnostics_coverage": 0.15,  # 진단 명세 커버리지
        "examples_quality": 0.10       # 예시 품질
    }
    
    def score(self, tool_description: dict) -> float:
        scores = {
            "mission_clarity": self._score_mission(tool_description),
            "argument_completeness": self._score_arguments(tool_description),
            "interaction_hints": self._score_interactions(tool_description),
            "diagnostics_coverage": self._score_diagnostics(tool_description),
            "examples_quality": self._score_examples(tool_description)
        }
        return sum(
            score * self.WEIGHTS[key]
            for key, score in scores.items()
        ) * 100

    def prioritize_improvements(
        self,
        tool_registry: list[dict],
        call_frequency: dict[str, int]
    ) -> list[ImprovementTask]:
        scored = [
            (tool, self.score(tool), call_frequency.get(tool["name"], 0))
            for tool in tool_registry
        ]
        # 낮은 품질 점수 + 높은 호출 빈도 = 높은 우선순위
        return sorted(
            scored,
            key=lambda x: (100 - x[1]) * (x[2] ** 0.5),
            reverse=True
        )

새 도구 발견 능력까지 설명이 좌우한다

논문의 도구 발견 실험은 에이전트가 훈련 과정에서 접하지 않은 신규 도구 100개를 포함한 MCP 서버에서 태스크를 수행하도록 구성했다. 원본 설명에서는 신규 도구의 발견·활용 성공률이 38.4%였고, 증강 설명에서는 82.7%로 두 배 이상 높아졌다.

증강 설명은 알려진 도구의 호출 정확도만 높이는 장치가 아니다. 에이전트가 별도 훈련 없이 새 도구의 용도와 사용법을 추론하도록 충분한 컨텍스트를 제공해 새로운 도구 생태계에 대한 적응력을 높인다.

이를 구현하는 방식이 도구 자기 문서화 패턴이다. 각 도구의 MAID 메타데이터를 코드에 선언적으로 정의한 뒤, 서버가 시작될 때 MCP 도구 설명 필드로 자동 직렬화한다. 구현과 설명을 같은 선언에서 생성하면 코드가 바뀌었는데 설명은 이전 상태로 남는 문제를 구조적으로 차단할 수 있다.

운영 단계에서는 MAID 스코어카드로 설명 품질을 점수화하고 호출 빈도에 따라 개선 순서를 정한다. 설명 변경은 CI/CD 회귀 테스트에 포함해 TSA 31.4%p와 TCR 26.8%p로 확인된 개선을 유지하고, 모델을 교체하지 않고도 다룰 수 있는 도구 선택 병목을 지속적으로 관리한다.