道具ひとつ — 説明文がコードより重要だ

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 カメラの設定を読む

道具が三つのうちはどうでもよく見える。二十になったとき、規則が無かったことが露わになる。 そして名前は一度出たら変えられない — 呼ぶ側のコードに埋まっているからだ。