Echolot도구와 품질
서버의 도구가 매 턴마다 모델에 드는 비용, 모델이 혼동할 만한 부분, 모델이 어떤 도구를 고를지 확인합니다.
모델은 MCP 서버를 직접 보지 못합니다. 모델이 보는 것은 대화의 매 턴마다 전송되고 각 제공업체의 형식으로 변환된 서버의 도구 목록입니다. MCP 서버 페이지의 모델이 이 서버를 보는 방식 카드는 모델이 받는 그대로의 목록을 보여 줍니다. 드는 비용, 비용이 가장 큰 도구, 모델이 잘못 이해할 이름, 설명, 스키마입니다. 서버를 만드는 동안, 또는 다른 사람의 서버를 에이전트에게 넘기기 전에 사용하십시오.
이 카드는 검사에서 도구가 하나 이상 나열되면 도구 아래에 나타납니다.
도구의 비용
카드 맨 위에는 도구 목록이 매 턴마다 Anthropic, OpenAI, Google Gemini에서 차지하는 토큰 수가 각 제공업체의 형식으로 센 값으로 표시됩니다. 그 아래 줄에는 도구가 몇 개인지, 셋 중 가장 큰 값이 200k 컨텍스트의 몇 퍼센트인지가 표시됩니다.
이 수치는 추정치이며 제공업체가 세는 값과 약 15% 이내로 일치합니다. 서버를 비교하거나 설명이나 스키마를 바꾸면 어떻게 되는지 확인하는 데 쓸 만합니다.
가장 큰 도구는 비용이 가장 큰 도구 다섯 개를 토큰 수와 함께 나열합니다. 도구가 하나인 서버에서는 이 목록이 생략됩니다.
모델이 혼동할 만한 부분
다음은 심각한 순서로 나열된 발견 사항입니다. 제목에는 개수(예: 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 토큰을 넘음 | 경고 | 설명과 스키마를 줄이거나 도구를 적게 제공하십시오. |
서버를 바꾼 뒤 검사를 다시 클릭하면 카드가 새 도구 목록을 반영합니다.
제공업체가 받는 형태의 목록
카드 맨 아래의 제공업체가 받는 형태의 목록을 열고 Anthropic, OpenAI, Google Gemini 중 하나를 선택합니다. 그 제공업체의 API가 받는 도구 목록이 JSON으로 표시됩니다. 복사를 누르면 복사됩니다. 예를 들어 Gemini의 형식이 스키마에서 무엇을 빼는지 여기서 볼 수 있습니다.
모델로 시도
아래의 모델로 시도 카드는 실제 모델에게 어떤 도구를 호출할지 묻습니다. 누군가 이 서버로 에이전트에게 요청할 만한 내용을 입력하고
(예: Is the two-person tent in stock?) 시도를 클릭합니다.
모델은 서버의 도구를 보고 자신이 할 호출로 답합니다. 실제로 호출되는 것은 없습니다. 각 호출에는 도구와 인수가 표시되며, 도구의 스키마에 맞지 않는 인수는 무엇이 잘못되었는지와 함께 표시됩니다. 이렇게 해서 불분명한 이름과 설명이 드러납니다. 그 아래에는 Echolot이 사용한 토큰을 표시하고, 가격을 아는 모델이면 그 턴에 든 대략의 비용도 표시합니다.
이 카드는 설정 › 어시스턴트에서 선택한 모델을 사용합니다. 선택한 모델이 없으면 그곳에서 모델 제공업체를 선택하라고 안내합니다. 처음 시도할 때 Echolot은 프롬프트와 서버의 도구를 그 제공업체에 보내도 되는지 묻습니다. 온디바이스 모델과 Mac의 서버는 묻지 않습니다.
명령줄에서
echolot mcp check --quality는 터미널에서 같은 보고서를 출력하며, --strict는 문제가 있으면 종료 코드 1로 실패하게 하므로 서버의
CI가 도구 목록을 잘 유지할 수 있습니다. --as anthropic, --as openai, --as gemini는 그 제공업체가 받는 형태의 목록만 출력합니다.
echolot mcp를 참조하십시오.
echolot mcp check --url https://demo.echolot.dev/mcp --quality