Claudeツール名に使える文字と日本語が弾かれる理由

Claudeツール名に使える文字は4種類だけ

Claude APIにツールを渡すとき、nameフィールドは正規表現^[a-zA-Z0-9_-]{1,64}$で検証されます。使える文字はアルファベットの大文字・小文字、数字、アンダースコア(_)、ハイフン(-)の4種類のみです。長さは1〜64文字に収める必要があります。

スペース、日本語、絵文字、ピリオド、コロンはすべて対象外です。get_weatherやcreate-issueは通りますが、天気を取得やget weather、get.weatherはリクエストそのものが拒否されます。名前をどう決めるかで悩む前に、まずこの4文字種と長さ制限を機械的なチェックポイントとして押さえておくと、後段の設計に集中できます。使える文字が少ないぶんルール自体はシンプルで、一度覚えてしまえば毎回調べ直す必要はありません。

日本語のツール名がエラーになる理由

日本語の文字はUnicodeの範囲で見ると、a-zA-Z0-9_-のどの文字クラスにも属しません。正規表現がASCII範囲に限定されているため、天気取得のような名前を送るとinvalid_request_errorとしてリクエストが400で拒否されます。

ツール名はAPIが構築するシステムプロンプトに埋め込まれ、モデルがtool_useブロックの中で同じ文字列を生成し直します。

日本語で表現したい情報(ツールの目的をチーム内で分かりやすくしたい等)は、nameではなくdescriptionに書きます。descriptionは自由なプレーンテキストで、日本語を含め言語の制約がありません。名前で識別性を、説明文で可読性を担保する、という役割分担だと考えると迷いにくくなります。

実際に弾かれる名前と通る名前

半角スペースの代わりにアンダースコアかハイフンへ置換すれば、たいていの名前案はそのまま通ります。パス風の名前(repo/create_issueなど)も一見ASCII範囲内に見えますが、/自体が許可文字に入っていないため同様に拒否されます。

大文字・小文字は正規表現の上ではどちらも許可されているため、GetWeatherもget_weatherも文字種としては通ります。ただし公式のサンプルはすべて小文字スネークケース(get_weatherのような形)を採用しています。実務でもこの慣習に合わせておくと、他のツールとの一貫性が保て、複数人でツール一覧をレビューするときの可読性も上がります。

input_schemaのプロパティ名にはこの制約が無い

nameフィールドの正規表現は、ツールを識別するトップレベルの名前だけに適用されます。input_schemaの中で定義するプロパティ名(locationやunitなど)は、JSON Schemaのpropertiesオブジェクトのキーであり、通常のJSON文字列として扱われます。日本語のプロパティ名を書いても構文エラーにはなりません。

ただし、公式のサンプルはプロパティ名も英数字とアンダースコアで揃えられています。意味の説明自体はdescriptionフィールドに書けば十分なので、命名の自由度(構文的に許されるか)と実運用の慣習(公式サンプルがどう揃えているか)は別の軸として考える必要があります。

ツールを増やす前に決める3つのルール

命名の失敗は実装の後半になるほど直しにくくなります。効くルールは3つです。

1. サービス名を接頭辞にする。GitHub用ならgithub_list_prs、Slack用ならslack_send_messageのように、由来するサービスを名前の先頭に置きます。ツールが数十本を超えると、接頭辞なしのlist_prsやsend_messageは他サービスの同名操作と衝突しやすくなります。
2. 1操作1ツールにしない。create_pr・review_pr・merge_prと分けるより、actionパラメータを持つ1つのツールに集約したほうがClaudeの選択ミスは減ります。ツールの数そのものを絞る設計判断ですが、結果として命名すべき名前の数も減り、接頭辞の付け忘れや衝突のリスクも下がります。
3. 命名規則をコード側で強制する。動的にツール一覧を生成するアプリケーションでは、ユーザー入力やDBの値をそのままnameに流用しないでください。全角→半角の変換、スペース→アンダースコアの置換、64文字切り詰めを行うバリデーション関数を1つ用意すれば、実行時の400エラーを未然に防げます。

名前が重複するとClaudeがツールを呼ばなくなる

正規表現を満たしていても、tools配列の中で名前が重複していると別の問題が起きます。公式のトラブルシューティングガイドは「Claudeが用意したツールを一向に呼ばない」症状の原因として、ツール名の衝突と汎用的すぎるスキーマの2つを挙げ、まず「ツールリスト内で名前が重複していないか確認する」ことを最初のチェック項目に置いています。

同じような処理をする複数のツールを異なるサービスから取り込むとき(例えば独自定義のsearchとMCPサーバー由来のsearch)、うっかり同名になっていると、正規表現の検証は通過するのに実行時の選択精度だけが落ちるという厄介な失敗の仕方をします。エラーにならないぶん気づきにくく、命名規則を決めるときは「文字種が正しいか」だけでなく「配列全体でユニークか」も合わせて確認する価値があります。

Anthropicが提供するクライアントツールにはnameが無い

bash・text editor・computer useのようなAnthropic-schema client toolsは、ユーザー定義ツールと違ってnameではなく日付入りのtype(bash_20250124のような文字列)で識別されます。スキーマも命名もAnthropic側が固定しているため、開発者が文字種を気にする場面はありません。

computer use toolとbrowser use toolはさらに一段抽象化されています。1つのtypeエントリが複数の内部ツール(メンバーツール)をまとめて宣言する「クライアントツールセット」という形を取り、エントリ自体はnameを持ちません。個々のメンバーの識別はtoolset_nameとnameのペアで行われます。

この違いを知っておくと、「なぜこのツールのページには命名規則が書いていないのか」という疑問にすぐ答えられます。^[a-zA-Z0-9_-]{1,64}$を意識する必要があるのは、あなたが独自に定義するtools配列のエントリだけです。

エラーになったときのレスポンスの読み方

nameが正規表現に一致しないリクエストを送ると、Claude APIは他のinvalid_request_errorと同じ形式でエラーを返します。エラーは常にJSONで、トップレベルのerrorオブジェクトにtypeとmessageが入り、request_idが併記されます。

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "..."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

messageの具体的な文言はエラーの種類ごとに異なりますが、error.typeがinvalid_request_errorになることとrequest_idが付くことは共通です。サポートに問い合わせるときは、このrequest_idをそのまま伝えると調査が早くなります。公式SDKを使っていれば、生のJSONではなくPythonのanthropic.BadRequestErrorのような型付き例外として受け取れるため、文字列一致でエラー内容を判定する必要はありません。

命名チェックをコードで自動化する

動的にツール定義を組み立てるアプリケーションでは、nameを生成する箇所に検証関数を1つ挟むだけで、実行時の400エラーをほぼゼロにできます。

import re
 
TOOL_NAME_PATTERN = re.compile(r"^[a-zA-Z0-9_-]{1,64}$")
 
def to_safe_tool_name(raw: str) -> str:
    # 全角・半角スペースをアンダースコアに、それ以外の非許可文字を除去する
    safe = re.sub(r"[\s　]+", "_", raw)
    safe = re.sub(r"[^a-zA-Z0-9_-]", "", safe)
    safe = safe[:64]
    if not TOOL_NAME_PATTERN.match(safe):
        raise ValueError(f"tool name '{raw}' cannot be normalized to a valid name")
    return safe

このような正規化関数を共有ライブラリに1つ置いておけば、外部システムの表示名やAPI名をそのままnameに流用しても、送信前に安全な形へ揃えられます。日本語の名称を捨てたくない場合は、正規化前の文字列をdescriptionの先頭に添えておくと、Claude自身がツールの由来を理解する手がかりにもなります。

Tool RunnerやAgent SDKでも同じ制約を受ける

Tool RunnerやAgent SDKのtoolsパラメータも、最終的には同じMessages APIのtools配列を生成します。SDK側でPythonの関数名やTypeScriptのメソッド名からツール名を自動生成する実装では、キャメルケースやスネークケースの関数名がそのままASCII範囲に収まるため、通常は問題になりません。

つまづきやすいのは、外部システムのメタデータ(日本語のAPI名やUI表示名)をそのままnameに流し込んだときです。表示用の名前とname用の識別子は、最初から別の変数として管理するのが安全です。エージェント向けのツール設計の原則でも、名前空間の設計は精度に直結する要素として扱われています。Anthropic API完全ガイドで扱ったモデル選択・料金と合わせて、命名規則は実装の早い段階で固定しておくと手戻りが減ります。

まとめ

Claudeのツールnameに使える文字は英数字・アンダースコア・ハイフンの4種類、長さは1〜64文字です。日本語・スペース・記号を含む名前は400エラーで即座に拒否されます。日本語で表現したい情報はdescriptionに書き、nameはサービス名を接頭辞にしたASCII識別子に統一するのが、実装で事故が起きにくい書き方です。

正規表現を満たしていてもツールが呼ばれない場合は、文字種ではなく配列内での名前の重複を疑ってください。命名のエラーは400という形で即座に分かりますが、重複による選択ミスはエラーにならないぶん見つけにくく、実装の早い段階で両方をチェックしておくと後戻りが少なくて済みます。ツール数が数本のうちは気にならなくても、複数のサービスやMCPサーバーを組み合わせる構成では、名前空間の設計自体が精度を左右する要素になります。