MCP ツールなどで zod 由来の生成 JSON Schema と handler 固有の手書き schema を合成する場合、トップレベルの properties だけを merge すると不十分。配列 item の object properties や nested object の中に handler 側だけで定義した項目があると、生成 schema 側の親 property が丸ごと勝って、その項目が公開 schema から消える。

判断基準

• 生成 schema を単一の定義元にしつつ、handler 固有の説明や追加 property を残す設計では、object の properties、array の items、required を再帰的に merge する。
• 同名 property は生成 schema を優先して型制約の正本を保ち、handler 側だけにある property は消さない。
• regression test はトップレベル property だけでなく、array item 内の nested property まで確認する。

検証

tools/list など実際にクライアントへ公開される schema を取得し、handler が受け付ける nested field が inputSchema にも出ているか確認する。単体テストだけでなく、起動済みサーバーの公開 schema を見ると、登録時の annotation や merge 処理の漏れを発見しやすい。