MCP 도구 설명(description): 쓸 내용과 길이 제한

MCP 도구 설명은 서버가 나열하는 각 도구의 자유 텍스트 필드인 description입니다. MCP 스키마는 이를 사람이 읽을 수 있는 설명이라고 부르며, 클라이언트는 이 설명으로 사용 가능한 도구에 대한 모델의 이해를 높일 수 있습니다. 모델에게 주는 힌트와 같습니다. 명세는 설명에는 길이 제한을 두지 않고 도구 이름(1–128자)에만 두지만, 클라이언트는 제한을 둘 수 있습니다. Claude Code는 기본적으로 각 도구 설명을 2,048자에서 자릅니다.

규칙은 MCP 2025-11-25의 도구 페이지와 스키마 레퍼런스, Claude Code의 MCP 문서, Anthropic의 도구 정의하기와 도구 사용 페이지, OpenAI의 함수 호출 가이드, Copilot CLI 명령어 레퍼런스에서 가져왔으며, 모두 2026-09-28에 확인했습니다. 예시로 든 Sume 호스팅 MCP 서버 내용은 서버의 현재 코드에서 가져왔습니다. Sume 기초 페이지는 호스팅 MCP가 여전히 동작하지만 현재 주 경로는 아니라고 설명합니다.

MCP 도구에서 설명은 어디에 들어가나요?

tools/list가 반환하는 각 도구에서 name, title, inputSchema와 나란히 들어갑니다. 스키마는 description을 선택 항목으로 표시합니다. 파라미터마다 inputSchema 안에 자체 description이 있습니다. 아래는 명세의 날씨 도구를 줄인 것입니다.

{
  "name": "get_weather",
  "title": "Weather Information Provider",
  "description": "Get current weather information for a location",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": { "type": "string", "description": "City name or zip code" }
    },
    "required": ["location"]
  }
}

MCP 도구 설명은 얼마나 길어도 되나요?

명세만 보면 원하는 만큼 길어도 됩니다. 실제 한도는 클라이언트와 토큰 비용에서 나옵니다.

MCP 도구 설명에는 무엇을 써야 하나요?

MCP 명세는 내용을 정해 두지 않습니다. 도구가 모델 제어(model-controlled) 방식이어서 모델이 컨텍스트와 사용자 프롬프트를 바탕으로 도구를 찾아 호출한다고 말할 뿐입니다. 다만 모델 공급사들은 자사 도구 형식에 맞춘 안내를 내놓고 있고, 그 내용은 서로 맞아떨어집니다.

• Anthropic은 상세한 설명을 도구 성능에서 단연 가장 중요한 요소라고 말합니다. 도구가 하는 일, 언제 쓰고 언제 쓰지 말아야 하는지, 각 파라미터의 의미와 그것이 도구 동작에 미치는 영향, 중요한 주의 사항이나 한계를 다루세요. 도구마다 최소 3–4문장을 목표로 하고, 복잡한 도구는 더 길게 쓰세요.
• OpenAI는 함수의 목적과 각 파라미터(형식 포함), 그리고 출력이 무엇을 나타내는지를 명시적으로 설명하라고 합니다. 예시와 엣지 케이스를 넣으라고 제안하지만, 추론 모델에서는 예시가 성능을 떨어뜨릴 수 있다고 덧붙입니다.
• Claude Code가 MCP 서버 작성자에게 주는 조언은 설명을 간결하게 유지하고, 한도를 넘는 부분은 잘리므로 중요한 내용을 앞쪽에 두라는 것입니다.

프로덕션 도구 설명은 어떤 모습인가요?

Sume 호스팅 MCP 서버가 한 예입니다. 현재 코드에서는 소스 주석 하나가 자주 호출되는 create 도구들의 설명 템플릿을 정합니다. Purpose(목적), When to use and when not(언제 쓰고 언제 쓰지 않는지), Defaults(기본값), Required payload(필수 payload, generate_image에서는 Input shape라는 이름), Aliases and forbidden keys(별칭과 금지 키), Safety(안전), Next step(다음 단계), 그리고 선택 항목인 Skill 줄입니다. 같은 주석은 설명 길이를 약 0.5–2KB로 제한하고 더 긴 안내는 스킬에 두도록 하며, 테스트는 각 설명이 512바이트에서 2,048바이트 사이인지 확인합니다.

설명 옆에 붙는 힌트는 MCP 도구 어노테이션에서 다룹니다. 아래는 generate_image 설명의 일부를 줄이고 줄바꿈을 더한 것입니다.

Purpose: Generate a still via POST /v1/images. The default image tool.
When to use: any still, … When not: B-roll (generate_video); BGM (music_create);
  cutout (rmbg_create); enlarging a still (image_upscale_create).
Input shape: { idempotency_key, payload } — every generation field goes INSIDE
  payload. payload.prompt required; …
Safety: paid create bills via wallet/admission. Require idempotency_key.
  Optional dry_run=true for cost; optional max_spend_usd when provided. …
Next step: async create answers in ms — fan out the whole wave, then one
  jobs_wait on job_ids … → jobs_result; no per-still wait mid-wave.