도구 하나 — 설명문이 코드보다 중요하다

1편의 서버는 아무것도 못 했다. 도구를 하나 붙인다.

네 조각

server.addTool(
  name: 'desk.count',
  description: 'How many people are waiting at the desk right now',
  inputSchema: const {'type': 'object', 'properties': {}},
  handler: (args) async =>
      CallToolResult(content: [TextContent(text: '{"waiting":3}')]),
);

그리고 기능을 켠다고 선언한다.

capabilities: ServerCapabilities(tools: ToolsCapability(listChanged: true))

셋은 우리가 안 읽는다

네 조각 중 handler 만 우리 코드가 읽는다. 나머지 셋은 전부 부르는 쪽이 읽는다.

tools/list 를 물으면 이렇게 나간다.

{
 "tools": [
  {
   "name": "desk.count",
   "description": "How many people are waiting at the desk right now",
   "inputSchema": {
    "type": "object",
    "properties": {}
   }
  }
 ]
}

사람이 만든 클라이언트라면 이 목록을 보고 버튼을 그린다. 모델이라면 이 목록을 읽고 어느 도구를 부를지 정한다. 그 판단의 근거가 description 한 줄이다.

그래서 이 줄은 주석이 아니다. 동작하는 코드다.

이름 짓기

desk.count 처럼 점으로 나눈 이름을 쓴다. 앞이 무엇에 대한 것인지, 뒤가 무엇을 하는지다.

desk.count      대기 인원을 센다
desk.admit      대기줄에서 들여보낸다
camera.settings 카메라 설정을 읽는다

도구가 셋일 때는 아무래도 좋아 보인다. 스물이 되면 그때 규칙이 없던 게 드러난다. 그리고 이름은 한 번 나가면 못 바꾼다 — 부르는 쪽 코드에 박혀 있기 때문이다.