# 도구와 품질 (/ko/docs/mcp-servers/tools-and-quality)

모델은 MCP 서버를 직접 보지 못합니다. 모델이 보는 것은 대화의 매 턴마다 전송되고 각 제공업체의 형식으로 변환된 서버의 도구 목록입니다.
MCP 서버 페이지의 **모델이 이 서버를 보는 방식** 카드는 모델이 받는 그대로의 목록을 보여 줍니다. 드는 비용, 비용이 가장 큰 도구,
모델이 잘못 이해할 이름, 설명, 스키마입니다. 서버를 만드는 동안, 또는 다른 사람의 서버를 에이전트에게 넘기기 전에 사용하십시오.

이 카드는 검사에서 도구가 하나 이상 나열되면 **도구** 아래에 나타납니다.

<Shot id="mcp-quality-card" alt="Alpenglow MCP의 모델이 이 서버를 보는 방식 카드. Anthropic, OpenAI, Google Gemini의 토큰 수, 가장 큰 도구, 모델이 혼동할 만한 문제 없음이라는 줄이 보입니다" />

## 도구의 비용 [#what-the-tools-cost]

카드 맨 위에는 도구 목록이 매 턴마다 **Anthropic**, **OpenAI**, **Google Gemini**에서 차지하는 토큰 수가 각 제공업체의 형식으로 센 값으로
표시됩니다. 그 아래 줄에는 도구가 몇 개인지, 셋 중 가장 큰 값이 200k 컨텍스트의 몇 퍼센트인지가 표시됩니다.

이 수치는 추정치이며 제공업체가 세는 값과 약 15% 이내로 일치합니다. 서버를 비교하거나 설명이나 스키마를 바꾸면 어떻게 되는지
확인하는 데 쓸 만합니다.

**가장 큰 도구**는 비용이 가장 큰 도구 다섯 개를 토큰 수와 함께 나열합니다. 도구가 하나인 서버에서는 이 목록이 생략됩니다.

## 모델이 혼동할 만한 부분 [#what-a-model-would-stumble-over]

다음은 심각한 순서로 나열된 발견 사항입니다. 제목에는 개수(예: `1 problem, 2 warnings`)가 표시되거나 **모델이 혼동할 만한 문제 없음**이라고
표시됩니다. 각 발견 사항은 도구를 지목하고, 무엇이 잘못되었는지 알려 주고, 해결 방법을 제안합니다.

| 종류 | 의미 |
| --- | --- |
| 문제 | 제공업체가 도구를 거부하거나, 모델이 사용법을 짐작할 수밖에 없습니다. 먼저 고치십시오. |
| 경고 | 작동하지만 모델이 잘못된 도구를 고르거나 인수를 잘못 채울 가능성이 높습니다. |
| 참고 | 한 제공업체가 제약을 무시하는 경우처럼 알아 둘 만한 사항입니다. |

Echolot이 각 도구에서 확인하는 항목:

| 발견 사항 | 종류 | 할 일 |
| --- | --- | --- |
| 이름이 제공업체가 받아들이는 형식이 아님 | 문제 | 문자, 숫자, `_`, `-`를 최대 64자까지 사용하십시오. Anthropic과 OpenAI는 나머지를 거부합니다. |
| 설명 없음 | 문제 | 도구가 무엇을 하는지, 무엇이 필요한지, 무엇을 반환하는지 쓰십시오. |
| 설명이 이름보다 거의 더 알려 주지 않음 | 경고 | 도구에 필요한 것과 반환하는 것, 비슷한 도구 대신 이 도구를 써야 할 때를 쓰십시오. |
| 긴 설명(1,500자 초과) | 참고 | 매 턴마다 다시 읽힙니다. |
| 입력 스키마가 객체가 아님 | 문제 | 모든 제공업체가 `{"type": "object", "properties": …}`를 요구합니다. 매개변수가 없는 도구는 `"properties": {}`라고 씁니다. |
| 스키마에 속성이 없음 | 참고 | 매개변수가 없으면 `"properties": {}`라고 쓰거나, 있는 매개변수를 설명하십시오. |
| 어떤 객체든 받음 | 경고 | 모델이 인수를 지어내지 않도록 도구가 읽는 속성을 설명하십시오. |
| 속성이 정의하지 않은 매개변수를 필수로 지정 | 문제 | 속성을 정의하거나 `required`에서 빼십시오. |
| 타입이 없는 매개변수 | 문제 | 각각 `type`(또는 `enum`)을 지정하십시오. 그렇지 않으면 모델이 짐작하며 OpenAI의 strict 모드는 이를 거부합니다. |
| 자유 형식 객체(속성 없음) | 경고 | 키를 설명하거나 설명에 무엇이 들어가는지 쓰십시오. |
| 설명이 없는 매개변수 | 경고 | 각각 한 줄로 무엇인지와 예시 값을 쓰십시오. |
| `$ref` 사용 | 경고 | Gemini는 이를 무시하므로 그 매개변수가 무엇이든 받게 됩니다. OpenAI의 strict 모드는 인라인으로 풀어 쓰기를 요구합니다. |
| `oneOf`, `pattern`, `additionalProperties`처럼 Gemini가 무시하는 키워드 | 참고 | Gemini에서는 제약이 사라집니다. |
| 큰 스키마(약 1,000 토큰 초과) | 경고 | 도구를 나누거나 드물게 쓰는 옵션을 스키마에서 빼십시오. |
| 매개변수 25개 초과 | 경고 | 도구를 나누거나 옵션을 묶으십시오. |
| 5단계를 넘는 중첩 | 경고 | 인수를 평탄하게 만드십시오. 모델은 깊은 구조를 잘 채우지 못합니다. |
| 값이 40개를 넘는 열거형 | 참고 | 모든 값이 매 턴마다 읽힙니다. |

그리고 목록 전체에 대해:

| 발견 사항 | 종류 | 할 일 |
| --- | --- | --- |
| 모델이 혼동할 이름(대소문자, `_`, `-`를 무시하면 같음) | 문제 | 도구를 서로 구별해 주는 점을 따라 이름을 지으십시오. |
| 설명이 같은 두 도구 | 문제 | 서로를 구별해 주는 점을 쓰십시오. 모델은 설명으로 도구를 고릅니다. |
| 거의 같은 내용을 말하는 두 설명(단어의 60% 이상이 같음) | 경고 | 각 설명에 다른 도구 대신 이 도구를 써야 할 때를 쓰십시오. |
| 도구 128개 초과 | 문제 | OpenAI는 128개를 넘으면 거부합니다. 적게 제공하거나 서버를 나누십시오. |
| 도구 40개 초과 | 경고 | 모델은 많은 도구 중에서 더 못 고릅니다. 한 번에 적게 제공하거나 주제별로 서버를 나누십시오. |
| 목록이 턴당 20,000 토큰을 넘음 | 경고 | 설명과 스키마를 줄이거나 도구를 적게 제공하십시오. |

서버를 바꾼 뒤 **검사**를 다시 클릭하면 카드가 새 도구 목록을 반영합니다.

## 제공업체가 받는 형태의 목록 [#the-list-as-a-provider-receives-it]

카드 맨 아래의 **제공업체가 받는 형태의 목록**을 열고 **Anthropic**, **OpenAI**, **Google Gemini** 중 하나를 선택합니다. 그 제공업체의
API가 받는 도구 목록이 JSON으로 표시됩니다. **복사**를 누르면 복사됩니다. 예를 들어 Gemini의 형식이 스키마에서 무엇을 빼는지 여기서
볼 수 있습니다.

## 모델로 시도 [#try-with-a-model]

아래의 **모델로 시도** 카드는 실제 모델에게 어떤 도구를 호출할지 묻습니다. 누군가 이 서버로 에이전트에게 요청할 만한 내용을 입력하고
(예: `Is the two-person tent in stock?`) **시도**를 클릭합니다.

<Shot id="mcp-try-with-a-model" alt="모델로 시도 카드: 텐트에 관한 프롬프트와, 인수가 있는 search_catalog 호출이라는 모델의 답변" />

모델은 서버의 도구를 보고 자신이 할 호출로 답합니다. 실제로 호출되는 것은 없습니다. 각 호출에는 도구와 인수가 표시되며, 도구의 스키마에
맞지 않는 인수는 무엇이 잘못되었는지와 함께 표시됩니다. 이렇게 해서 불분명한 이름과 설명이 드러납니다. 그 아래에는 Echolot이 사용한
토큰을 표시하고, 가격을 아는 모델이면 그 턴에 든 대략의 비용도 표시합니다.

이 카드는 [설정 › 어시스턴트](/docs/ai/assistant)에서 선택한 모델을 사용합니다. 선택한 모델이 없으면 그곳에서 모델 제공업체를
선택하라고 안내합니다. 처음 시도할 때 Echolot은 프롬프트와 서버의 도구를 그 제공업체에 보내도 되는지 묻습니다. 온디바이스 모델과 Mac의
서버는 묻지 않습니다.

## 명령줄에서 [#from-the-command-line]

`echolot mcp check --quality`는 터미널에서 같은 보고서를 출력하며, `--strict`는 문제가 있으면 종료 코드 1로 실패하게 하므로 서버의
CI가 도구 목록을 잘 유지할 수 있습니다. `--as anthropic`, `--as openai`, `--as gemini`는 그 제공업체가 받는 형태의 목록만 출력합니다.
[echolot mcp](/docs/cli/mcp)를 참조하십시오.

```sh
echolot mcp check --url https://demo.echolot.dev/mcp --quality
```