두 개의 MCP 도구 이름을 바꿨더니 에이전트의 도구 호출 (Tool-call) 정확도가 71%에서 94%로 상승했습니다

3개월 전, 저희의 고객 서비스 에이전트(customer-service agent)는 240달러의 부분 환불을 처리해야 할 상황에서 2,400달러의 회계 취소(accounting reversal)를 자신 있게 실행했습니다. 고객은 "파손된 품목에 대한 환불"을 요청했습니다. 에이전트에게는 환불(refund)과 취소(cancel)라는 두 가지 도구가 있었습니다. 에이전트는 취소를 선택했습니다. 저희 시스템에서 취소(cancel) 도구는 회계 장부에서 전체 거래 취소를 수행합니다.

기술적으로 에이전트는 옳았습니다. "취소(Cancel)"는 "되돌리기(undo)"를 의미할 수 있고, 이는 다시 "반전(reverse)"을 의미할 수 있기 때문입니다. 고객은 격분했고, CFO는 짜증이 났습니다.

3주 동안 저는 프롬프트 엔지니어링 (prompt engineering)으로 이 문제를 해결하려 노력했습니다. 하지만 아무것도 효과가 없었습니다. 별도의 테스트 데이터셋(held-out trace set)에서 도구 호출 (tool-call) 정확도는 71%였습니다.

해결책은 도구의 이름을 바꾸는 것이었습니다.

진단 (The diagnosis)

저는 그동안 MCP 도구를 API 엔드포인트 (API endpoints)를 다루는 방식과 동일하게 취급해 왔습니다. 동사를 고르고, 명사를 고르고, 이름을 붙이는 방식 말입니다. 깔끔한 RESTful 명명 규칙을 따랐던 것이죠.

하지만 이러한 명명 규칙은 도구를 사용하는 에이전트 (tool-using agents)에게는 잘못된 방식입니다. LLM (Large Language Model)에게는 경계가 있는 문맥 (bounded contexts)이 존재하지 않습니다. LLM은 하나의 전역 도구 목록을 보고 사용자의 의도와 의미론적 유사성 (semantic similarity)에 따라 선택합니다.

Eric Evans는 2003년 "도메인 주도 설계 (Domain-Driven Design)"에서 이에 대해 기술했습니다. 그는 이를 유비쿼터스 언어 (Ubiquitous Language)라고 불렀습니다. Russell Miles는 올해 초 "도메인 주도 에이전트 설계 (Domain Driven Agent Design)"에서 이를 에이전트에 적용했습니다. Dennis Traub는 Dev.to에서 "당신의 에이전트가 계속 그 단어를 사용합니다"라는 프레임워크로 이에 대해 글을 썼습니다.

규칙은 다음과 같습니다: 도구의 이름을 동작 (operation)이 아니라, 경계가 있는 문맥 (bounded context)에 따라 명명하십시오.

이름 변경 (The rename)

변경 전:

@mcp_tool
def cancel(order_id: str) -> dict:
    """주문을 취소합니다."""
...

변경 후:

@mcp_tool
def customer_support_cancel_order(order_id: str) -> CustomerOrderCancellation:
    """배송 전 고객의 주문을 취소합니다.
...

세 가지 변화가 있었습니다:

1. 도구 이름에 접두사 (prefix)로 경계가 있는 문맥 (bounded context)을 포함했습니다.
2. 설명 (descriptions)에서 형제 도구들을 명시적으로 교차 참조했습니다 (각 도구가 자신이 무엇이 '아닌지'를 명시함).
3. 반환 타입 (return types)에 문맥을 포함하여 이름을 붙였습니다. Pydantic 모델들도 동일한 어휘를 사용합니다.

측정 방법 (How we measured)

500개의 예시로 구성된 별도의 테스트 데이터셋 (held-out test set)을 사용했습니다. 변경 전 정확도는 71%였으나, 변경 후 94%를 기록했습니다.

FastAPI + MCP에 연결하기

from mcp.server.fastmcp import FastMCP
from fastapi import FastAPI
from pydantic import BaseModel
...

Pydantic 반환 타입은 LLM(Large Language Model)에게 또 다른 모호성 해소 (disambiguation) 신호를 제공합니다. 우리는 단지 딕셔너리 (dict) 반환 타입을 명명하는 것만으로도 약 5% 포인트의 정확도 상승을 확인했습니다.

부패 방지 계층 (The anti-corruption layer)

class CustomerRefundToAccountingTransaction:
    """고객이 요청한 환불을 회계 도메인으로 매핑합니다."""

...

매퍼 (mapper)는 엄격한 경계입니다. LLM은 고객 컨텍스트 (customer-context) 도구 인터페이스만을 보기 때문에 이를 우회할 수 없습니다. 회계 컨텍스트 (accounting context)는 결정론적 (deterministically)으로 호출됩니다.

결론

MCP 도구는 API 메서드가 아닙니다. 그것들은 공유된 언어 속의 어휘 (vocabulary) 항목입니다. 작업 (operation) 단위가 아니라 경계 컨텍스트 (bounded context) 단위로 이름을 붙이십시오. 당신의 MCP 서버는 API 문제가 아니라 데이터베이스 스키마 (database schema) 문제입니다.

이에 대해 반론을 제기한다면

이 모든 경험은 도구 계층 (tool layers)을 바라보는 나의 관점을 재고하게 만들었습니다. 그것들은 API가 아닙니다. 어휘입니다. 나는 내부적으로 "도구"라는 단어 사용을 중단하고 "우리 에이전트 언어의 동사"라고 말하기 시작했습니다. 그래야 설계 질문이 더 명확하게 드러나기 때문입니다.

경계 컨텍스트 (bounded-context) 명명 규칙은 장황함을 더합니다. 엔지니어들은 반발할 것입니다. 내가 수용할 수 있는 반발은 "모호성을 해소할 만큼의 여러 경계 컨텍스트가 존재하지 않는다"는 것입니다. 소규모 규모에서는 그것이 사실입니다.

내가 수용하지 않을 반발은 "설명 (descriptions)만으로 충분하다"는 것입니다. 우리는 3주 동안 그것을 시도해 보았습니다. 충분하지 않습니다. 에이전트의 행동은 당신이 작성한 설명이 아니라, 당신이 선택한 이름에 의해 형성됩니다.

만약 당신이 경계 컨텍스트 명명 규칙 없이 멀티 컨텍스트 (multi-context) 에이전트를 출시했는데 도구 호출 (tool-call) 정확도가 90% 이상을 유지했다면, 나는 그 아키텍처 (architecture)를 보고 싶습니다. 나의 선입견은 강하지만 절대적인 것은 아닙니다.