MCPツールを50個書いて気づいたこと：関数呼び出しは異常に親密な関係だった

週末の2日間で資産管理ツールをSQLiteベースのCLIとMCPサーバーへ移した経験を
もとに、MCPツール設計がRPCと決定的にどこで分かれるのかを整理した文章。
筆者はCLIコマンド30個あまりとMCPツール50個あまりを書いたが、その分量に反して
もっとも長く向き合っていたのはコードではなく関数の説明だった、という発見から出発する。

• 同じ関数をCLIとMCPに同時に公開したとき、シグネチャ/引数/戻り値がすべて同じなのに、2つのインターフェースは
  異なる挙動をした。変わったのは呼び出し側が人間かLLMかだけだった
• シグネチャは関数が何を受け取るかは説明するが、いつ呼ばれるべきかはほとんど説明できない。関数名は
  辞書の1行に近く、単語そのものではどんな文の上に置かれるかを決められない
• LLMの呼び出し側にとっては、単一責任原則（SRP）で細かく分割したツールよりも、意図に直接届く重いツールのほうが
  自然だった
• MCPは形だけ見ればRPCの系譜（JSON-RPC、シグネチャ、スキーマ）だが、決定的な違いは信頼の向きが
  逆転すること。RPCでは呼び出し側が呼び出し先を信頼するが、MCPではツールを作った側が呼び出し側（LLM）を信頼しなければならない
• シグネチャは宣言で、説明はお願い。一方は強制で、もう一方は説得。ツール設計に説得の言語が入り込み始めたわけだ
• これは新しい変化というより、回帰に近い。インダストリアルデザイン、建築、UXはすでにずっと前から同じ場所にいて、
  プログラミングだけがそのあいだ特に親密な片側の端にとどまっていただけなのかもしれない

シグネチャが語らないこと

• Firmaのadd_txn（トランザクション）、add_balance（資産スナップショット）、add_flow（収入/支出）はシグネチャがどれも
  明確で、引数の型もzodスキーマで厳密に定義されていたが、LLMはユーザーの発話からどのツールを呼ぶべきかを
  しばしば取り違えた
• 最初はLLMモデルの問題を疑ったが、実際の問題はシグネチャそのものにあった。add_txnという名前には
  「ユーザーが売買について話したらこのツールを使え」という呼び出しのタイミングが含まれていない
• descriptionを**"Use this when... Do NOT use this for..."**という形で、呼び出しのタイミングや他のツールとの境界を
  明示してはじめて、呼び出しが安定した
• 関数の意図がシグネチャから関数説明のほうへ移動したということ。ハンマーの柄がその形で使い方を示唆するように、
  MCP関数の説明はLLMにとって事実上ツールのアフォーダンス（ドナルド・ノーマン）に当たる

SRP vs アフォーダンス、そして信頼の向き

• 最初は単一責任原則どおりget_holdings、get_prices、get_pnlのように細かく分けようとしたが、ユーザーが「私の
  ポートフォリオどう？」と尋ねると、LLMは4〜5回の呼び出しを組み合わせる必要があり、応答が遅くなり、食い違う余地も大きくなった
• 結局show_portfolioを保有銘柄/平均取得単価/現在価格/評価金額/累積損益を一度に返す重い
  ツールとして設計した。get_briefはさらに進んでマクロ指標やインサイトまで一度に返す
• SRPは関数を作る人の美徳で、アフォーダンスはツールを使う人の美徳。呼び出し側が人間なら組み立てられるが、
  LLMなら意図に直接届くツールのほうがよい
• 書き込みツールでは信頼の向きがもっともはっきり現れる。add_txnに**"Always confirm with the user before
  recording"**と書いたところ、LLMが毎回確認し、ユーザーは毎回「OK」と答える結果になった — 自然言語インターフェースの利点が
  消えてしまう
• 結局**「すぐに記録せよ、曖昧なときだけ尋ねよ、間違っても取り消せる」**という形で責任を再配分した。こうした
  指針はツールの形式的な説明ではなく、呼び出し側に与える運用原則である

関数呼び出しこそ、むしろ特殊なケースだったのかもしれない

• 人間はもともと自分で作っていない道具を使ってきた。陶工が作った器、鍛冶屋が作った刃物、開発者が作った
  プログラムまで、すべてそうである
• 関数呼び出しは、呼び出し側と作者が多くの文脈を共有し、型システム/IDE/ドキュメントがその親密さを絶えず補強してくれる
  かなり特殊な関係だったわけだ
• 呼び出し側が人間でないなら、選択肢は2つある。(1) LLMにより多くの文脈を与えて親密な呼び出し側にする、(2) ツール
  側で距離を埋める。MCPは後者に近い
• インターフェースを設計するやり方そのものが静かに変わりつつある時期なのかもしれない。シグネチャから説明へ、強制から
  説得へ、親密さの前提から距離の承認へと重心が移っている