この記事では、Windows環境のClaude Codeで実際に試した結果をもとにまとめています。
「Claude Codeにもっと自分専用の機能を追加できたら便利そう」と感じる場面があります。Agent SDKのCustom Toolsを使うと、Claudeに独自の処理を渡して実行させることができます。そこで、Claude Codeに「ツールを作って」と頼むだけで、どこまで進むのかを検証しました。最小のツール定義から、ファイルを読み込んでチェックする機能まで、実際の依頼文と結果をそのまま追います。
この記事で確かめること
Agent SDKのCustom Tools機能を使って、Claudeに「自分専用の処理」を追加し、どこまで自動で作れるかを確かめます。
具体的には、文字数を数える最小ツールの作成から始め、ファイルを読み込んでルールに合っているかチェックする機能まで拡張します。各Stepで依頼文とその結果をそのまま見せ、最初の依頼でどこまで進むか、修正指示でどこまで広げられるかを追います。
先に知っておきたいこと
この記事で試すのは、Claude Code本体にスラッシュコマンドを追加する話ではありません。Agent SDKのコード内でツール関数を定義し、それをClaudeに渡して実行させる仕組みです。
Pythonスクリプトを書いてPowerShellで実行する工程が含まれるため、完全なノーコードとはいきません。ただしコードの大部分はClaude Codeに書かせます。Windows環境での分担は、依頼をClaude Codeの入力欄、実行をPowerShellという形になります。
Custom Toolsとは何か
Custom Toolsは、Agent SDKのPythonコード内で関数を定義し、それをClaudeに「使える道具」として渡す仕組みです。Claudeは会話の中でそのツールが必要だと判断したとき、自動的に関数を呼び出して結果を受け取ります。
例えば、「テキストの文字数を数える」関数をCustom Toolとして定義しておけば、Claudeは文章を渡すだけでその長さを知ることができます。独自のフォーマット変換や、特定のルールでデータをチェックする処理も同じ仕組みで追加できます。
MCPサーバーとの違いをざっくり言うと、Custom ToolsはSDKコードの中に直接書くため、外部サーバーを立ち上げる手間がありません。一方、MCPサーバーは別プロセスとして動き、複数のアプリから利用できるのが利点です。今回はSDKコード内で完結するCustom Toolsに絞って検証します。
事前に必要なもの
始める前に、ざっくり次の環境を揃えておきます。
- Claude Codeが使えること：インストール済みで、チャットに入力できる状態
- PythonでAgent SDKの基本が使えること：
claude-agent-sdkパッケージのインストールと、簡単なエージェント呼び出しの経験があるとスムーズです（自作エージェントの基礎はCC-066を参照） - MCPサーバーの基本を知っていること：外部ツール連携の概念を押さえておくと、Custom Toolsとの違いが分かりやすいです（CC-010を参照）
- Windows環境：PowerShellでスクリプトを実行し、VS Code等のエディタでコードを確認します
依頼はClaude Codeの入力欄に書き、生成されたコードはPowerShellで実行して動作を確かめます。この二つの役割の違いを意識しておくと、流れがつかみやすくなります。
今回の検証条件
検証は次の条件で進めます。
- 検証範囲：文字数カウントの最小ツール作成 → ファイルを読んでチェックする機能への拡張
- 成功基準：ClaudeがCustom Toolを呼び出せる、引数を正しく渡せる、実行結果を返せる
- 限界判定：複雑な外部API連携や、例外処理の網羅は今回の検証では扱いません
- 検証環境：Windows 11で、ターミナルからClaude Codeに自然文で依頼する形で試しました
Step 1で最小ツールを作り、Step 2で動作確認、Step 3で機能を広げ、Step 4でどこまで実用化できたかを整理します。
Step 1: 最小のCustom Toolを作る
まずは一番シンプルな形を試します。次の依頼文をClaude Codeに入力しました。
Agent SDKで、テキストの文字数を数えるCustom Toolを作って。関数名は count_characters にして。Pythonコードを出力して。
Claude Codeは、Custom Toolとして使うためのPythonコードを出力してくれました。ただし、現在のAgent SDK公式例では @tool デコレータや create_sdk_mcp_server を使う形が案内されているため、出力されたコードが最新の公式例と同じ書き方かは確認が必要です。
出力されたコードの要点を拾うと、次のような構造でした。
count_characters関数がテキストを受け取ってlen(text)を返す- 関数の説明文（docstring）が書かれており、Claudeが「いつこのツールを使うか」を判断する材料になる
- エージェント側から使えるように、ツールとして登録する処理が含まれている
良かったのは、docstringが丁寧でClaudeがツールの用途を理解しやすいところ。足りなかったのは、エージェント呼び出し部分のAPIキーの扱いが環境変数前提になっていた点で、初心者向けに os.environ の設定手順が省略されていました。
Step 2: 実行して確認する
Step 1で生成されたコードをファイルに保存し、PowerShellで実行します。
python custom_tool_test.py
今回は、エージェントに「次の文章の文字数を数えて」と投げたところ、ツールが正しく呼び出されました。出力には「文字数: XX」と表示され、手動で数えた数と一致していました。
実際に動かすと、いくつかよくあるエラーに出くわすことがあります。
ModuleNotFoundError：必要なPythonパッケージが入っていない。Agent SDKを使う場合はclaude-agent-sdk、生成コードがanthropicを直接読み込んでいる場合はanthropicのインストール状況を確認しますFileNotFoundError：スクリプトの保存場所とPowerShellのカレントディレクトリが違う。cdでスクリプトの場所に移動してから実行します- 文字コードのエラー：日本語を含むテキストを渡す際に
utf-8で保存されていないと文字化けやエラーになることがあります
人が確認したポイントは、ツールに渡された引数と戻り値が正確だったかどうかです。Claudeがツールを呼び出した際のログを見て、テキストがそのまま渡され、戻り値が正しい文字数であることを手動で確かめました。
Step 3: 実用寄りに広げる
最小ツールが動いたところで、次はファイルを読み込んでルールに合っているかチェックする機能に拡張します。修正の依頼文は次の通りです。
このツールを拡張して、指定したファイルを読み込み、行の長さが50文字を超えていたら警告を返す機能を追加して。関数名は check_line_length にして。
Claude Codeは既存のコードに新しい関数を追加する形で出力しました。主な変化点は次の通りです。
check_line_length関数がファイルパスを受け取り、行ごとに文字数をチェックする- 50文字を超える行があった場合、行番号とともに警告メッセージを返す
- 既存の
count_charactersはそのまま残る
ファイル読み込みにはいくつか注意点があります。相対パスで指定した場合、スクリプトの実行場所（カレントディレクトリ）が基準になるため、PowerShellをどこから起動したかで結果が変わります。存在しないファイルを渡した場合、このコードでは FileNotFoundError がそのまま上がる仕様でした。実用するなら、ファイルが見つからないときのメッセージをもう少し親切にしたいところです。
修正指示を出したのは、文字数カウントだけでは実務で使う場面が限られると感じたためです。「ルールに合っているかを確認する」という方向に広げることで、より実用的なツールの検証になりました。
Step 4: どこまで実用化できたか
拡張後のツールをPowerShellで実行し、実際のテキストファイルを渡してチェックしました。
結果として、50文字を超える行が正しく検出され、行番号とともに警告が返されました。ファイルが短ければ、このまでも実用に耐える動きでした。
改善されたのは、複数行の一括チェックと行番号付きの警告表示。最小ツールの時にはなかった「どこが問題か」が分かる出力になりました。
残った課題は例外処理の甘さで、ファイルが存在しない場合、日本語のファイルパスが含まれる場合、非常に長いファイルを渡した場合の挙動まではカバーされていませんでした。
ざっくり分担を書くと、次のようになります。
- Claude Code任せで進んだ部分：ツールの定義、関数の基本的なロジック、ファイル読み込み機能の骨組み
- 人が判断した部分：エラーの原因切り分け（
ModuleNotFoundErrorとFileNotFoundErrorの違い）、出力の妥当性確認（検出された行番号と実際の行が一致しているか）
到達しなかったこととして、外部APIとの連携や、エラーハンドリングの網羅的な実装は今回の検証範囲外でした。
どんな時にCustom Tools / MCPを選ぶか
Custom ToolsとMCPサーバー、どちらを選ぶべきかは用途で分かれます。
Custom Toolsが向く場面
SDKコードの中で完結する処理なら、Custom Toolsの方が手軽です。簡単な変換、文字数チェック、特定のルールでデータを検証するといった「1スクリプトで済む作業」に向いています。
MCPが向く場面
外部サービス（Slack、データベース、Web API等）との連携や、複数のアプリから同じツールを使いたい場合はMCPサーバーが適しています。別プロセスとして動くため、スクリプトを終了してもサーバーが動き続けます。
まずはCustom Toolsで「関数を1つ定義してClaudeに渡す」感覚を掴むのがおすすめです。MCPは別プロセスの管理が増えるため、Agent SDKに慣れてから取り組むとスムーズです。
どこまで頼むだけでできたか
今回の検証の境界線を事実ベースで整理します。
頼むだけで進んだ部分
ツール関数の定義、docstringの記述、基本的なファイル読み込み機能の骨組みまでは、1回の依頼で出力されました。修正指示1回で、文字数カウントから行の長さチェックへの拡張も完了しています。
人が判断した部分
エラーの原因切り分けと、出力の妥当性確認は人が担当しました。検出された行番号が実際のファイル内容と一致しているかは、目視での確認が必要だった部分です。
到達しなかったこと
複雑な外部API連携、本格的なエラーハンドリング、日本語パスを含むファイル操作は今回の検証では試していません。
やり取りの回数：依頼2回、修正指示1回の計3回でした。
環境やバージョンによっては、今後さらに進められる可能性があります。
次に試すなら
Custom Toolsの基本が分かったところで、次に試したい方向けの導線を書いておきます。
コストの把握方法を学ぶ
Agent SDKでツールを動かすとAPI利用量が増えるため、使い方に応じたコスト感をつかんでおくと安心です（CC-070を参照）。
MCPサーバーを試す
外部サービスと連携したい場合は、MCPサーバーの構築に挑戦してみてください（CC-010を参照）。Custom Toolsの仕組みが分かっていると、「関数定義を外部プロセスに切り出す」というMCPの違いが理解しやすいはずです。
自作エージェントの基礎を固める
Custom ToolsはAgent SDKの一部なので、エージェント全体の設計に興味があればCC-066で基本構造を押さえられます。
次に試すときのコツとして、最初は「入力を受け取って文字列を返す」だけの最小関数から始めると、エラーの切り分けがしやすいです。関数が増えてからファイル読み込みや外部APIの呼び出しを足していくと、どこでつまずいたかが追いやすくなります。
まとめ
最小のCustom Toolなら1回の依頼で定義まで到達できました。実用レベルに広げるには修正指示が1回必要で、エラーの原因切り分けと出力の妥当性確認は人が担当する形でした。
骨組みが短時間でできるので、合わない部分だけ後から直せばいい——この感覚で取り組むと、Custom Toolsは試しやすい機能だと言えそうです。
今回の結果は、利用モデル、接続先、時期、環境によって変わる可能性があります。再現する時は検証条件もあわせて確認してください。
