작업 수준 agent API는 작업이 무엇을 달성하는지, 언제 사용하고 언제 사용하지 않아야 하는지, 어떤 영향을 줄 수 있는지 설명합니다. endpoint 형태만으로는 요청을 보내는 방법만 알 수 있습니다. 도구를 선택하는 모델에는 두 가지 정보가 모두 필요합니다.
semantic이라는 단어가 거창하게 들릴 수 있지만 실제 변경은 단순합니다. 데이터베이스 테이블이나 내부 서비스 경계가 아니라 사용자의 작업을 중심으로 도구를 설계하세요.
유효한 endpoint도 모호할 수 있습니다
다음 REST 작업을 생각해 보세요.
POST /users/{id}/status
{"value":"inactive"}
method, path, body, response가 모두 자세히 문서화되어 있어도 이 contract만으로는 inactive가 로그인을 중지하는지, 청구를 멈추는지, 담당 업무를 제거하는지, 삭제를 예약하는지, CRM label만 바꾸는지 알 수 없습니다.
개발자는 주변 문서를 읽고 이런 모호함을 한 번 해결합니다. 모델은 실행할 때마다 여러 도구 가운데 다시 선택해야 할 수 있습니다.
호출 가능한 contract에 의도를 담으세요
좋지 않은 도구:
set_user_status
Set a user's status.
작업 수준 도구:
suspend_workspace_member
Temporarily block one member from signing in to this workspace.
Use when an administrator asks to suspend access without deleting the account.
Do not use for billing cancellation, workspace deletion, or permanent data removal.
두 번째 설명은 모델에 작업, 권한, 영향, 제외 조건을 알려 줍니다. schema에는 필요에 따라 workspace, member, reason, approval 또는 operation ID도 지정해야 합니다.
MCP 도구 명세는 각 도구에 이름, 설명, input schema, 선택적 output schema, annotation을 제공합니다. 하지만 경계를 대신 작성해 주지는 않습니다.
작업 하나를 필요한 최소 결과에 연결하세요
다음 단계를 선택하는 agent에는 백엔드의 전체 응답이 필요하지 않은 경우가 많습니다. 다음 행동을 결정하는 필드만 반환하세요.
주문 조회라면 다음 정도면 충분합니다.
{
"orderId": "1842",
"status": "shipped",
"estimatedDelivery": "2026-09-02",
"canCancel": false
}
내부 database column, provider token, 200 KB payload를 반환한 뒤 모델이 답을 다시 찾아내게 하지 마세요. REST-to-MCP 가이드는 여러 내부 호출을 작업 결과 하나로 결합하는 변환 계층을 설명합니다.
부작용과 실패 동작을 명시하세요
각 도구에 다음 내용을 문서화하세요.
- 읽기, 쓰기, 지출, 전송, 삭제 중 어떤 작업을 하는가
- 어떤 caller와 resource 권한 부여가 적용되는가
- 승인이 필요한가
- 작업을 안전하게 재시도할 수 있는가
- 어떤 안정적인 실패가 다음 행동을 바꾸는가
- 어떤 결과 필드가 기준 정보인가
도구 annotation은 클라이언트가 위험을 표시하는 데 도움이 될 수 있지만, 클라이언트는 신뢰할 수 없는 서버의 annotation도 신뢰해서는 안 됩니다. 실제 제한은 정책과 백엔드에서 적용하세요.
비슷한 도구의 경계를 분명히 하세요
기능이 겹치는 도구에는 명확한 제외 조건이 필요합니다. 서버가 search_customers, find_contacts, query_accounts를 제공한다면 각 설명에서 자신이 담당하는 entity와 task를 밝혀야 합니다. 차이를 분명하게 설명할 수 없다면 도구를 합치거나 하나를 제거하세요.
잘못된 도구 선택 디버깅 가이드는 system prompt를 바꾸기 전에 도구 목록과 호출 trace부터 확인합니다.
선택과 실행을 따로 테스트하세요
각 도구를 선택해야 하는 prompt와 어느 도구도 선택하면 안 되는 prompt를 만드세요. 도구 목록, 설명, model, setting을 고정하고 아무 작업도 실행하기 전에 선택 결과를 기록하세요.
그런 다음 유효한 입력, 잘못된 입력, 권한 없는 입력, 반복 입력으로 실행을 테스트하세요. 선택하기 쉬운 도구라도 호출이 안전하다는 보장은 없습니다.
가장 비슷한 도구 쌍부터 다시 작성하세요
설명에서 같은 단어를 가장 많이 쓰는 두 도구를 찾으세요. 각각의 task, 사용 조건, 제외 조건, 부작용, 다음 단계에 필요한 결과를 작성합니다. 그래도 차이가 모호하다면 구현 경계가 agent interface로 새어 나오고 있을 가능성이 큽니다.
아래 프롬프트는 이 모호성 테스트를 수행하고 집중된 평가 세트를 만듭니다.