#tools

MCP 서버를 만들 때 같은 데이터를 Resource로 노출할지 Tool로 노출할지 헷갈리는 순간이 온다. application-controlled와 model-controlled라는 통제 주체 차이에서 출발해 부작용 여부·시점 결정 주체·파라미터화 필요성 세 기준으로 판별하고, 같은 로그 데이터를 두 방식으로 등록하는 코드로 차이를 정리한다.

MCP 도구는 description 말고도 annotations라는 채널로 자신의 행동 특성을 알릴 수 있다. readOnlyHint·destructiveHint·idempotentHint·openWorldHint 네 필드가 각각 무엇을 뜻하는지, 왜 힌트일 뿐 보장이 아닌지, registerTool에 실제로 붙이는 코드까지 정리한다.

MCP에서 도구 실패는 프로토콜 에러와 실행 에러 두 층으로 나뉘고, 실행 에러는 isError: true를 얹은 정상 결과로 돌아간다. 이 텍스트는 LLM이 읽고 행동을 바꾸는 입력이다 — 무엇이·왜 실패했고 다음에 뭘 하면 되는지를 담는 에러 메시지 설계법을 실제 코드로 정리한다.

MCP 도구는 LLM이 스스로 고른다. 이때 모델이 보는 건 구현 코드가 아니라 이름·description·입력 스키마뿐이다. 설명문이 곧 도구의 인터페이스인 이유와, 무엇을·언제·경계를 담아 선택률을 높이는 실무 규칙을 예제로 정리한다.