MCP 도구 설명과 입력 스키마
모델은 도구의 이름, 설명, 입력 스키마만 읽고 도구를 선택하므로 설명은 구체적으로 작성하고 인자는 enum과 범위로 제한한다.
모델에 제공되는 정보
모델은 서버 코드를 볼 수 없다. tools/list로 수신한 도구 정의, 즉 이름(name), 설명(description), 입력 스키마(inputSchema)를 읽고 어느 도구를 어떤 인자로 호출할지 결정한다. 이 세 항목이 불명확하면 모델은 도구를 잘못 선택하거나 인자를 추측으로 채운다.
부적절한 예
{
"name": "control",
"description": "장비 제어",
"inputSchema": {
"type": "object",
"properties": {
"id": { "type": "string" },
"mode": { "type": "string" },
"value": { "type": "number" }
}
}
}제어 대상이 무엇인지, mode에 어떤 값을 지정하는지, value의 단위와 한계가 무엇인지 알 수 없다. 필수 인자도 없다.
개선한 예
{
"name": "set_fan_speed",
"description": "환기 팬 한 대의 속도를 바꾸고 바뀐 속도를 돌려준다. 현재 속도는 get_fan_status로 확인한다.",
"inputSchema": {
"type": "object",
"properties": {
"fan_id": { "type": "string", "description": "예: FAN-03" },
"mode": { "type": "string", "enum": ["auto", "manual"] },
"speed_percent": {
"type": "integer", "minimum": 0, "maximum": 100,
"description": "최대 속도 대비 백분율"
}
},
"required": ["fan_id", "mode"]
}
}
작성 기준
- 이름: 동작과 대상을 포함한다.
- 설명: 무엇을 하는지, 언제 사용하는지, 무엇을 반환하는지 기술한다.
enum: 정해진 값 가운데 하나를 받는 인자라면 자유 문자열로 두지 않는다.minimum,maximum: 숫자의 범위를 제한하고, 단위는 인자 설명에 명시한다.required: 생략할 수 없는 인자를 나열한다.
스키마로 제한하더라도 서버는 수신한 인자를 검증해야 한다. 범위를 벗어난 값에는 도구 실행 오류(isError: true)로 사유를 반환한다. 모델은 그 내용을 읽고 인자를 수정한다.
