신뢰할 수 있는 MCP 도구에는 구분되는 작업 이름, 범위가 제한된 입력, 구조화된 출력, 안정적인 오류, 다운스트림 권한 부여, 안전한 쓰기 동작이 필요합니다. 도구 선택 실패는 개별적으로는 유효한 두 정의가 겹칠 때 자주 발생하므로 전체 도구를 한 세트로 테스트해야 합니다.
선택만 수행하는 평가부터 시작하세요. 잘못된 호출이 백엔드에 닿지 않은 상태에서 모호함을 드러낼 수 있습니다.
도구 하나에는 역할 하나만 부여하세요
사용자의 작업에 맞는 동사와 목적어를 사용하세요. get_order_status는 query_order_service보다 더 명확합니다. 넓은 기능을 의도했고 엄격하게 제한한 경우가 아니라면 execute, manage, process, run_query처럼 일반적인 이름은 피하세요.
설명은 다음 질문에 답해야 합니다.
- 도구가 어떤 결과를 만드는가?
- 모델은 언제 이 도구를 사용해야 하는가?
- 언제 다른 도구를 사용하거나 아무 도구도 사용하지 않아야 하는가?
- 외부에 어떤 영향을 줄 수 있는가?
작업 수준 API 가이드는 좋지 않은 contract와 좋은 contract를 나란히 보여 줍니다.
입력은 작고 제한적으로 유지하세요
JSON Schema로 필수 필드, enum, format, 길이, 숫자 범위를 표현하세요. 사용자나 이전 도구가 리소스를 이미 식별했다면 자유 형식 설명보다 안정적인 resource ID를 사용하세요.
인증된 맥락에서 서버가 알아낼 수 있는 값을 모델에 요구하지 마세요. tenant ID, user ID, provider 자격 증명은 보통 도구 인수가 아니라 session이나 server에 속합니다.
변경 작업의 경우 백엔드 contract가 요구할 때 operation key나 idempotency key를 받으세요. 자동 재시도 안에서 새 key를 생성하면 재시도가 새로운 작업으로 바뀌므로 그렇게 해서는 안 됩니다.
다음 판단에 필요한 결과를 반환하세요
현재 MCP 도구 명세는 선택적 output schema와 structuredContent를 지원합니다. 호환 클라이언트를 위해 text 표현도 함께 반환할 것을 권장합니다.
agent가 다음에 필요한 기준 필드를 다음처럼 제한된 형태로 반환하세요.
{
"deploymentId": "dep_1842",
"state": "pending",
"statusUrl": "/deployments/dep_1842",
"retryAfterSeconds": 10
}
provider의 전체 응답을 기본값으로 반환하지 마세요. 불안정한 필드, 내부 identifier, 지나치게 긴 text, secret이 들어 있는 경우가 많습니다.
protocol 오류와 domain 오류를 분리하세요
MCP 요청 자체가 유효하지 않거나 서버가 처리할 수 없을 때 protocol error를 사용하세요. 도구가 실행되었지만 비즈니스 작업이 실패했다면 안정적인 domain error와 함께 isError: true를 반환하세요.
유용한 domain error는 호출자가 다음에 할 일을 알려 줍니다.
| 오류 | 다음 행동 |
|---|---|
invalid_resource_id |
인수 수정 |
not_authorized |
중단하고 접근 권한 요청 |
approval_required |
정확한 작업을 사용자에게 제시 |
operation_in_progress |
반환된 operation을 polling |
rate_limited |
반환된 시각까지 대기 |
upstream_unavailable |
operation contract가 허용할 때만 재시도 |
모델에 보이는 오류에 stack trace, database message, 자격 증명을 포함하지 마세요.
도구 뒤에서 권한을 적용하세요
서버는 클라이언트와 그 클라이언트가 대신하는 사용자를 인증해야 합니다. 다운스트림 API는 해당 신원을 tenant, 리소스, 작업에 대해 권한 부여해야 합니다. 도구 목록은 접근 제어 목록이 아닙니다.
MCP 인증 가이드는 대상이 제한된 access token과 별도의 업스트림 자격 증명을 다룹니다.
쓰기 작업을 안전하게 반복할 수 있게 만드세요
생성, 업데이트, 전송, 지출, 삭제를 수행하는 모든 도구에 대해 다음을 지키세요.
- 논리적 operation identifier 하나를 정의합니다.
- 결과를 저장하거나 조정합니다.
- 충돌하는 재사용을 거부합니다.
- timeout 후 결과를 알 수 없을 때의 동작을 문서화합니다.
- 중요한 실행 전에 승인을 배치합니다.
- 백엔드가 지원한다면 되돌릴 수 있는 삭제를 우선합니다.
클라이언트 재시도와 서버 재시도가 서로 곱해질 수 있습니다. 어떤 계층이 재시도를 맡을지 정하고 모든 시도를 하나의 operation 아래 기록하세요.
annotation은 표시용 힌트로 취급하세요
MCP 도구 annotation은 읽기 전용, 파괴적, idempotent, open-world 동작을 설명할 수 있습니다. 클라이언트는 신뢰할 수 없는 서버의 annotation을 신뢰하면 안 됩니다. 표시 방식을 개선하는 데 사용하되 같은 사실을 코드에서도 강제하세요.
선택과 실행을 따로 평가하세요
선택 테스트는 모델에 보이는 도구 집합을 고정하고 어떤 도구를 호출할지 묻습니다. 다음 사례를 포함하세요.
- 모든 도구에 대한 명확한 정상 작업
- 가장 비슷한 도구 쌍에 대한 경계 사례
- 필수 맥락이 빠진 요청
- 어떤 도구도 호출하면 안 되는 요청
- 검색된 데이터 안에 포함된 적대적 콘텐츠
실행 테스트는 선택된 도구를 유효한 요청, 잘못된 요청, 권한 없는 요청, 반복 요청, 중단된 요청으로 호출합니다. 도구 이름, redaction을 적용한 뒤의 인수, policy 결정, operation ID, 결과 분류, 소요 시간을 기록하세요.
잘못된 도구 디버깅 가이드는 선택 테스트가 실패했을 때 이 trace를 사용하는 방법을 설명합니다.
전체 도구 목록에서 시작하세요
모델이 보는 목록을 그대로 내보내세요. 도구 파일을 하나씩 읽으면 충돌이 보이지 않습니다. 공통 noun, verb, description, argument 형태를 기준으로 도구 쌍의 순위를 매긴 다음 가장 가까운 쌍에 대한 경계 작업을 작성하세요.
아래 프롬프트는 도구를 하나도 호출하지 않고 이 평가 세트를 만듭니다.