Claude Agent SDK では、自分で書いた関数を「ツール」として Claude に渡し、エージェントループの中から呼ばせることができます。本稿は公式ドキュメント(Custom Tools)の検証済み記述に基づき、ツールの定義方法・登録・許可設定・結果の返し方・言語ごとの差異を仕様ベースで整理します(検証日: 2026-08-20 JST)。すべての技術的主張は末尾 References の出典に対応します。
ツール定義の 4 要素
ツールは 4 つの構成要素で定義され、TypeScript では tool() ヘルパー、Python では @tool デコレータに渡されます [1]。
A tool is defined by four parts
具体的には、ツールを呼ぶときに Claude が使う一意の名前(Name)、何をするツールかを説明する記述(Description)、入力スキーマ、そしてハンドラの 4 つです。
入力スキーマ — TypeScript と Python の差
TypeScript では入力スキーマに常に Zod スキーマを使います。ハンドラの引数はそのスキーマから自動的に型付けされます [1]。
In TypeScript this is always a Zod schema
Python では扱いが異なります。dict スキーマはすべてのキーを必須として扱います [1]。
the dict schema treats every key as required
したがってオプションパラメータを表現したい場合は、そのパラメータをスキーマから外し、説明文で言及し、ハンドラ内で args.get() を使って読み取ります [1]。
インプロセスサーバーとしての登録
定義したツールは createSdkMcpServer(Python では create_sdk_mcp_server)でラップします。このサーバーはアプリケーション内でインプロセス動作し、別プロセスとして起動しません [1]。
The server runs in-process inside your application, not as a separate process.
完全修飾名
mcpServers に登録する際のキーが、各ツールの完全修飾名 mcp__{server_name}__{tool_name} における {server_name} セグメントになります [1]。
becomes the {server_name} segment in each tool's fully qualified name
パーミッションと allowedTools
ツールの完全修飾名を allowedTools に列挙すると、そのツールはパーミッションプロンプトなしで実行されます [1]。
List that name in allowedTools so the tool runs without a permission prompt.
同一サーバー上の全ツールを一括で許可するにはワイルドカードが使えます [1]。
use the wildcard mcp__weather__* to cover every tool the server exposes
ツールサーチ(デフォルト有効)
ツールサーチはデフォルトで有効で、SDK MCP ツールを遅延ロードします [1]。Claude はコンパクトなリストで各ツール名を確認し、必要になったときにフルスキーマをオンデマンドで読み込みます。
Tool search is on by default and defers SDK MCP tools
ツールアノテーション
アノテーションはツールの振る舞いに関するメタデータです。readOnlyHint のデフォルトは false で、環境を変更しないことを示します [1]。この値は、他の読み取り専用ツールとの並列呼び出し可否を制御します。
Controls whether the tool can be called in parallel with other read-only tools.
destructiveHint のデフォルトは true で、破壊的更新を行いうることを示しますが、情報提供のみで強制力はありません [1]。
destructiveHint true Tool may perform destructive updates. Informational only.
なお idempotentHint および openWorldHint のデフォルト値については、本稿の検証範囲では確認しておらず、別途公式ドキュメントでの確認が必要です。
重要なのは、アノテーションはメタデータであって強制ではない点です [1]。
Annotations are metadata, not enforcement.
つまり readOnlyHint: true を付けたツールでも、ハンドラの実装次第でディスクへ書き込むことは可能です。
エラー処理
ハンドラのエラーはエージェントループを止めません [1]。SDK のインプロセス MCP サーバーが、キャッチされない例外を捕捉してエラー結果に変換します。
A handler error doesn't stop the agent loop.
ツールの失敗を Claude に明示的に伝えたい場合は、結果に isError(Python では is_error)を設定します [1]。
set to true to signal a tool failure so Claude can react to it.
結果ブロック — 画像・音声・リソースリンク
画像ブロックの data フィールドは base64 エンコードされたバイト列で、生の base64 のみを受け付けます [1]。
Raw base64 only, no data:image/...;base64, prefix
音声ブロックの扱いは言語で異なります。TypeScript では SDK が音声ブロックをディスクに保存し、Claude は保存先のファイルパスを含むテキストブロックを受け取ります [1]。Python では音声ブロックはツール結果からドロップされ、警告がログに記録されます [1]。
the SDK drops audio blocks from the tool result and logs a warning.
リソースリンクブロックは、リンクの name・URI・description を含むテキストブロックに変換されます [1]。
The SDK converts resource link blocks to a text block containing the link's name, URI, and description.
structuredContent
structuredContent は結果に付与できるオプションの JSON オブジェクトで、content 配列とは独立しています。テキストや画像からパースさせるのでなく、正確なフィールドとして値を Claude に読ませるために使います [1]。
Use it to return raw values that Claude can read as exact fields
structuredContent を設定すると、content 内のテキストブロックは構造化データの複製とみなされ、転送されません [1]。
Text blocks in content are not forwarded
Python では制約があります。@tool デコレータはハンドラの戻り値から content と is_error のみを転送します [1]。
The Python @tool decorator forwards only content and is_error from the handler's return dict.
そのため Python から structuredContent を返すには、インプロセス SDK サーバーではなくスタンドアロンの MCP サーバーを動かす必要があります。
ビルトインツールの制御
tools オプションにビルトインツール名を列挙すると、列挙されたものだけが Claude のコンテキストに残り、未列挙のビルトインは除去されます(MCP ツールは影響を受けません)[1]。
Only the listed built-ins are in Claude's context. Unlisted built-ins are removed.
一方 disallowedTools にスコープ付きルール(例: "Bash(rm *)")を指定すると、ツールはコンテキストに残したまま、一致する呼び出しだけを拒否します [1]。
leaves the tool in context and denies only matching calls