MCP 도구 설명 작성법: LLM이 REST API를 잘 호출하게 만드는 체크리스트

MCP 도구를 붙였는데 에이전트가 엉뚱한 API를 호출한다면, 모델 성능만 의심하면 안 된다. 많은 경우 문제는 도구 설명에 있다. LLM은 API 문서를 사람처럼 “의도를 추론해서” 읽지 않는다. tools/list에 나온 name, description, parameters를 보고 다음 행동을 고른다.

특히 REST API를 MCP 도구로 노출할 때 이 문제가 자주 나온다. 기존 OpenAPI 스펙은 사람 개발자와 SDK 생성기를 대상으로 작성됐다. “Get user”, “Update status”, “List items” 같은 설명도 사람이 보면 맥락을 보충할 수 있다. 하지만 에이전트는 비슷한 도구가 여러 개 있으면 작은 표현 차이로 선택을 바꾼다.

이 글은 MCP 서버 구현법보다 도구 설명 품질에 집중한다. Google Cloud API Gateway의 MCP Public Preview처럼 기존 REST operation을 바로 도구화하는 흐름이 늘어날수록, 설명 작성은 운영 품질의 일부가 된다.

도구 설명은 문서가 아니라 라우팅 규칙이다

사람용 API 문서는 기능을 설명한다. MCP 도구 설명은 호출 판단을 유도한다. 이 차이를 먼저 받아들여야 한다. “이 API는 주문 상태를 반환한다”보다 “사용자가 주문의 현재 위치, 배송 상태, 도착 예정일을 물을 때 사용한다”가 낫다.

좋은 설명에는 세 가지가 들어간다. 첫째, 언제 사용해야 하는가. 둘째, 언제 사용하면 안 되는가. 셋째, 호출 후 결과를 어떻게 해석해야 하는가. 예를 들어 get_order_status 도구라면 “배송 변경, 환불, 주소 수정에는 사용하지 말 것”이라는 금지 조건을 넣어야 한다.

설명은 길다고 좋은 게 아니다. 모델이 빠르게 구분할 수 있어야 한다. 한 도구 설명에 여러 책임을 넣으면 오히려 선택이 흔들린다. 하나의 operation이 여러 intent를 처리한다면 API 자체를 나누거나, MCP 노출용 wrapper를 따로 두는 것이 낫다.

이름은 짧게, 목적은 구체적으로

도구 이름은 모델과 사람 모두를 위한 인덱스다. getData, fetchInfo, updateRecord처럼 넓은 이름은 피해야 한다. get_customer_subscription_status, create_refund_draft, search_help_center_articles처럼 대상과 행동이 드러나는 이름이 좋다.

동사도 중요하다. get, list, search, create, update, delete, send를 구분해야 한다. 특히 send, delete, charge, cancel처럼 외부 영향이 있는 동사는 이름에서 숨기면 안 된다. createRefund처럼 실제 환불을 실행하는지, create_refund_draft처럼 초안만 만드는지 명확히 해야 한다.

Parameter 이름도 모델이 이해하기 쉬워야 한다. id 하나만 두면 어떤 id인지 헷갈린다. orderId, customerId, invoiceId처럼 도메인 객체를 붙인다. 날짜는 startDate, endDate와 format 설명을 넣는다. enum은 가능한 값을 모두 적고, 각 값이 어떤 상황에 쓰이는지 설명한다.

좋은 description의 구조

실무에서는 다음 형식이 안정적이다.

첫 문장: “Use this when...”으로 사용 조건을 쓴다. 둘째 문장: 반환값을 쓴다. 셋째 문장: 금지 조건이나 대체 도구를 쓴다. 넷째 문장: 권한이나 확인이 필요한 조건을 쓴다.

예를 들어 주문 조회 도구는 이렇게 쓸 수 있다.

Use this when the user asks where an existing order is, whether it has shipped, or when it is expected to arrive. Returns order status, carrier, tracking number, and ETA when available. Do not use this to change address, cancel an order, or request a refund. Requires a verified customer identity and a valid orderId.

이 설명은 기능보다 intent를 먼저 말한다. 또한 유사 도구와의 경계를 명확히 한다. “주문 관련 질문”처럼 넓게 쓰면 취소나 환불 질문에도 호출될 수 있다.

파라미터 스키마는 방어적으로 쓴다

MCP 도구 호출 오류는 description만으로 해결되지 않는다. parameter schema가 부실하면 모델이 틀린 값을 넣는다. string 하나로 모든 값을 받는 방식은 빠르지만 운영에서 비용이 크다.

필수값과 선택값을 구분한다. nullable인지, 빈 문자열이 허용되는지, 배열 최대 길이는 얼마인지 적는다. 검색 API라면 query 길이 제한과 필터 사용법을 설명한다. 날짜 범위 API라면 timezone 기준과 최대 조회 기간을 적는다. 금액 관련 API라면 currency와 minor unit 여부를 명확히 한다.

입력값 검증은 백엔드에서도 해야 한다. 모델이 schema를 항상 지키지는 않는다. 잘못된 enum, 너무 긴 배열, 존재하지 않는 id, 과도한 날짜 범위를 거부해야 한다. 거부 메시지도 모델이 다음 행동을 고칠 수 있게 구체적이어야 한다. “Invalid request”보다 “endDate must be within 31 days of startDate”가 낫다.

도구 수는 적게 시작한다

처음 MCP를 붙일 때 기존 API 전체를 노출하고 싶어진다. 하지만 도구가 많을수록 모델의 선택 문제는 어려워진다. 특히 비슷한 이름의 get, list, search가 많으면 오호출이 늘어난다.

첫 배포는 5개 이하가 좋다. 사용자 질문 로그를 보고 가장 자주 반복되는 read-only 작업부터 고른다. 이후 도구별 호출 성공률, 재시도율, 사람 개입률을 보고 늘린다. 도구 추가는 기능 추가가 아니라 라우팅 공간 확장이다. 추가할 때마다 기존 도구와의 경계를 다시 봐야 한다.

또한 도구를 카테고리별로 나누는 것도 도움이 된다. support_order_status, support_refund_policy_search처럼 prefix를 둘 수도 있다. 단, prefix가 너무 길어져 모델이 핵심 동사를 놓치면 안 된다.

실패 케이스를 테스트셋으로 만든다

도구 설명은 한 번 쓰고 끝나는 문서가 아니다. 테스트 대상이다. 실제 사용자 질문 30개만 모아도 문제를 많이 찾을 수 있다. 각 질문에 대해 기대 도구, 기대 인자, 호출 금지 도구를 표로 만든다.

예를 들어 “배송이 늦는데 환불 가능해?”라는 질문은 주문 상태 조회와 환불 정책 검색이 모두 관련될 수 있다. 하지만 바로 환불 실행 도구를 부르면 안 된다. 이런 애매한 케이스를 테스트셋에 넣어야 한다.

평가 기준도 단순해야 한다. 정확한 도구를 골랐는가. 필요한 인자를 모두 채웠는가. 모르는 값은 사용자에게 물었는가. 위험한 작업 전에 확인을 받았는가. API 오류를 사용자에게 그대로 던지지 않고 복구했는가.

보안 설명은 모델에게도 필요하다

권한 체크는 백엔드가 해야 한다. 하지만 모델에게도 보안 경계를 알려야 한다. “관리자 전용”, “본인 계정에만 사용”, “결제 실행 전 확인 필요” 같은 조건은 description에 들어가야 한다.

이유는 간단하다. 백엔드에서 막더라도, 모델이 계속 잘못된 도구를 호출하면 사용자 경험이 망가진다. 또한 실패 로그가 늘어나고 rate limit을 낭비한다. 도구 설명은 보안 장치가 아니라 보안 UX 장치다.

민감한 도구는 이름에도 위험도를 드러내는 편이 좋다. delete_user_account보다 request_user_account_deletion이 안전할 수 있다. 즉시 삭제가 아니라 요청 생성임을 보여주기 때문이다. 실제 삭제 도구는 내부 시스템에서만 호출되도록 분리하는 것이 낫다.

실행 체크리스트

• description 첫 문장에 “언제 사용하는지”를 쓴다.
• “언제 사용하면 안 되는지”를 반드시 포함한다.
• get, search, create, update, delete, send를 이름에서 명확히 구분한다.
• id 대신 orderId, customerId처럼 도메인 객체명을 쓴다.
• enum, 날짜, 금액, 배열 제한을 schema에 구체적으로 적는다.
• 백엔드 입력 검증과 구체적인 오류 메시지를 준비한다.
• 첫 MCP 배포는 read-only 도구 5개 이하로 시작한다.
• 실제 사용자 질문으로 도구 선택 테스트셋을 만든다.
• 위험 작업은 도구 설명, 백엔드 권한, human confirmation을 함께 설계한다.
• 도구 추가 전 기존 도구와 intent 충돌이 없는지 확인한다.