ツール定義は「初めて来た人への説明書」として書く：Anthropic・OpenAI・Google・MCPの公式資料で、説明、名前、引数、個数、結果の返し方の指針を並べる

この記事は、公式の文書を読んでまとめたもので、実際に使って確かめた記録ではありません。数字や仕様は2026年10月22日に読み直しました。モデルや機能の名前は、変わることがあります。

先に結論

• ツール定義は、プログラムの部品の宣言であると同時に、AIへの説明書です。名前、説明、引数の説明、引数の型、これだけが判断材料です。
• 各社の指針は、細部は違っても方向がそろっています。説明は詳しく、ツールは少なく、引数は間違えようがない形に、結果は必要最小限に、エラーは次の行動が分かるように。
• 「いい定義」かどうかは、読んで判断せず、実際の仕事で測るのが公式の考え方です。Anthropicの技術記事は、現実に近い課題を数十件作って、正答率、呼び出し回数、トークン量、エラーを記録する手順を書いています。

前提：ツール定義とは何か

ツール呼び出し（関数呼び出し）は、AIが「この関数をこの引数で呼んでほしい」という依頼を返し、実行は自分のプログラムが行う仕組みです。仕組みそのものは別の記事で扱っています。ここでは、依頼の前に渡す「ツール定義」に絞ります。

定義の主な部品は、名前、説明、引数の形です。引数の形は、JSONスキーマ（データの形を書く決まった書式）で書きます。公式の文書で、呼び方が少し違います。

MCPは、AIとツールをつなぐ共通の決まりです。ここで見るのは、その仕様のうち「ツール」の節です。読んだのは2025-06-18版と2026-07-28版です。10月22日に仕様のトップページを開くと、2026-07-28版の各ページが案内されていたので、あわせて読みました（どちらが正式に「最新」と呼ばれているかは、読んだページには書かれていませんでした）。

公式の指針を並べる

読んだ文書から、共通して出てくる指針を8つに分けました。表の「誰が書いているか」は、読んだ範囲で確かめられたものだけです。

1つの定義の書き方の例

以下は、Anthropicの文書が説明する形式に合わせて、この記事で作った例です（実行はしていません）。2つを比べると、公式の指針のどこを直したかが分かります。

{"name": "search", "description": "検索する",
 "input_schema": {"type": "object", "properties": {"q": {"type": "string"}}}}

{"name": "orders_search",
 "description": "注文の一覧から、条件に合うものを探す。注文番号や顧客IDが分かっているときは使わず、orders_getを使う。返すのは注文ID、状態、合計金額だけで、商品の明細は含まない。結果は新しい順に最大20件。",
 "input_schema": {"type": "object",
  "properties": {
   "customer_id": {"type": "string", "description": "顧客ID（例: cus_1234）"},
   "status": {"type": "string", "enum": ["pending", "shipped", "cancelled"], "description": "注文の状態"}},
  "required": ["customer_id"]}}

直した点は、名前の接頭辞（指針3）、いつ使うか・使わないか・返さないものを書いたこと（指針1）、enumで状態を限ったこと（指針4）です。なお、「最大20件」「返すのは3項目」は、この例のための仮の数字です。

数と選び間違い

OpenAIの文書は、最初の時点で使える関数は20個未満が目安で、これは「弱い目安」だとしています。多い場合は、tool searchで必要なものだけ後から読み込む方法がありますが、OpenAIでは対応は新しいモデル（gpt-5.4以降）に限られる、と書かれています。

Anthropicのtool searchの文書は、より具体的な数字を出しています。ツール定義だけで約55,000トークンを使いうる例が書かれています。ツールが30〜50個を超えると選ぶ精度が落ちる、とも書いています。使う目安は、ツールが10個以上、定義が1万トークンを超える、複数のMCPサーバーをまとめている（原文は200個以上のツールを例に挙げる）、といった場合です。逆に、10個未満や、毎回すべてを使う場合は、通常の呼び出しのほうが向く、とあります。

見立てです。「ツールを減らす」は、機能を削ることではありません。似た操作をまとめる、使わない定義を出さない、後から読み込む、のどれで減らすかを選ぶ話だと思います。

結果とエラー

Anthropicの技術記事は、ツールの結果を、人が読んで意味が分かる項目にするよう勧めています。response_formatという引数で詳細版と簡潔版を選ばせると、簡潔版は約3分の1のトークンで済んだ例がある、と書かれています。結果が長いときの対策も具体的で、ページを分ける、範囲を指定する、絞り込む、切り詰める、を既定値つきで用意することです。同社のClaude Codeは、ツールの結果を既定で25,000トークンまでに制限している、と書いています。

エラーについて、Anthropicの文書は、tool_resultにis_error: trueを付けて返す形を示しています。引数が足りない、または不正なとき、Claudeは通常2〜3回、直して再試行してから謝る、とあります。不正な入力を防ぐには、strict: true（厳密モード）を使う、とも書かれています。

MCPの仕様は、エラーを2系統に分けています。未知のツールや不正な引数などは、通信の決まり（JSON-RPC）のエラーとして返し、外部APIの失敗や業務の都合などは、結果の中でisError: trueとして返します。どちらに入れるかは、自分のツールの設計で決めます。なお、2026-07-28版は分け方の説明が変わっています。通信の決まりのエラーは、未知のツール、要求の形が壊れている場合、サーバーの不具合とされ、日付の書式違いや値の範囲外のような入力の検査の失敗は、isError: trueの側に入れて、AIが自分で直せるようにする、と書かれています。2025-06-18版では、不正な引数は通信の決まりのエラーの例に挙がっていました。

精度以外にかかるもの

• トークンの費用：Anthropicの文書では、ツール定義は入力トークンとして課金され、さらに、ツールを使うための固定の説明文が加わります。OpenAIの文書も、関数定義は入力トークンとして課金される、と書いています。
• tool_choice：ツールをどう使わせるかの指定です。Anthropicは、自動（auto）、どれか必ず使う（any）、指定の1つを使う（tool）、使わない（none）の4つを説明しています。Geminiは、自動、必ず呼ぶ、禁止、validatedの4つです。
• 安全：MCPの仕様は、サーバー側に、入力の検査、アクセス制御、呼び出しの回数制限、出力の無害化を求め、クライアント側に、重要な操作の確認、結果の検査、タイムアウト、記録を勧めています。ツールの注釈は、信頼できるサーバーのものでなければ、信頼しない、とも書かれています。

自分で確かめる手順（見立て）

公式の評価の考え方を、小さな仕事に落とした見立てです。

1. 実際に近い課題を作る。Anthropicの技術記事は数十件を挙げています。最初は少なくても、同じ手順は使えます。複数のツール呼び出しを要する課題を混ぜ、正解は確かめられる形にする。
2. 課題ごとに、正答、呼び出しの回数、トークン量、エラーを記録する。
3. 記録を読む。同じ呼び出しの無駄が多ければ、ページ分けや上限を見直す。引数の間違いが多ければ、説明や例を直す。
4. 直したら、もう一度測る。技術記事は、合わせ込みすぎを避けるために、直すときに使わなかった課題（取っておいた課題）でも確かめるよう勧めています。

よくある失敗・つまずき

• 既存の窓口をそのまま、1対1でツールにする。Anthropicの技術記事は、一覧を全部返すlist_contactsより、絞り込むsearch_contactsのほうが良い例だと書いています。
• 説明が一行しかない。いつ使うか、使わないかが書かれていない。
• 引数名が曖昧（user、id）。
• 結果に、AIに要らない内部の識別子やログを大量に入れる。
• ツールの数と文脈の量を測らず、全ツールを毎回渡す。
• エラーが「失敗しました」だけ。

気をつけること

• この記事は、実際に使って確かめた記録ではありません。上の例の定義は、公式の形式に合わせて僕らが作ったもので、動作は確認していません。数字（最大20件など）は仮のものです。
• 読んだページは、ツールが要約を返す形で取得しています。文章は言い換えで、要約に混じった推論は事実として使っていません。
• Googleの関数呼び出しの文書は、約10万3千字です。10月16日には2回に分けて読み、10月22日の読み直しでは先頭の約10万字までを読みました（残りの約3千字は読んでいません）。どちらでも、個数や書き方の「ベストプラクティス」の節は見つかりませんでした。「ない」とは断定できません。表のGoogleの欄は、定義の項目と呼び出しの方式だけです。
• OpenAIの文書は、tool_choiceとparallel_tool_callsについて、読んだ範囲に説明がありませんでした。
• Anthropicの「Define tools」は、disable_parallel_tool_useとis_errorの説明が、そのページにはありません。is_errorは、別ページ（Handle tool calls）で確認しました。
• MCPの仕様は、2025-06-18版と2026-07-28版の「ツール」の節を読みました。この記事の表と本文は2025-06-18版の書き方に沿っていて、2026-07-28版との違いは、エラーの分け方のほかは細かく突き合わせていません（2026-07-28版には、ツール名の文字に.も許す、結果にresultTypeの項目が付くなど、別の変更もあります）。
• 「小さな定義の例」「確かめる手順」「ツールを減らす方法の整理」は、僕らの見立てです。
• 公式が挙げる名前や数字（モデル名、gpt-5.4など）は、更新されます。

出典

• Define tools（Claude Platform Docs、Anthropic、2026年10月22日確認）
• Handle tool calls（Claude Platform Docs、Anthropic、2026年10月22日確認）
• Tool use overview（Claude Platform Docs、Anthropic、2026年10月22日確認）
• Tool search tool（Claude Platform Docs、Anthropic、2026年10月22日確認）
• Writing effective tools for agents（Anthropic Engineering、Anthropic、2026年10月22日確認）
• Function calling（OpenAI API、OpenAI、2026年10月22日確認）
• Function calling（Gemini API、Google AI for Developers、Google、2026年10月22日確認）
• Tools（Model Context Protocol仕様 2025-06-18、MCPプロジェクト、2026年10月22日確認）
• Tools（Model Context Protocol仕様 2026-07-28、MCPプロジェクト、2026年10月22日確認）

更新履歴

• 2026年10月25日 書き方を直しました。

  • 前：運営者が使っていないと読める書き方 → いま：「この記事は、実際に使って確かめた記録ではありません」。公式の資料を読んでまとめた記事で、使い心地は書いていない、という意味に直した

• 2026年10月22日 公式の資料を読み直して、次の点を直しました。

  • 前：MCPの仕様は2025-06-18版を読み、現行かは未確認 → いま：2026-07-28版もあわせて読みました。正式な最新かは書かれていません
  • 前：不正な引数はJSON-RPCのエラーで返す → いま：2026-07-28版は、日付の書式違いなどの入力の検査の失敗をisErrorの側に入れる
  • 前：Googleの文書は約10万3千字を2回に分けて読んだ → いま：先頭の約10万字までを読み、残り約3千字は読んでいません
  • 前：2026-07-28版との違いは記載なし → いま：ツール名に「.」も許すなどの変更があり、突き合わせていません

一部の出典は読めなかったため、その部分は前のままです。