# Function callingのツール定義——JSON Schemaと構造化出力の設計要点

> ClaudeのFunction callingはname/description/input_schemaの3要素でツールを定義する。JSON Schema設計・strict mode・構造化出力との使い分けを実装指針として整理する。

- Canonical: https://kuucorp.com/blog/function-calling-structured-output-tool-design/
- Date: 2026-06-09
- Last modified: 2026-06-09
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
エージェントが外部APIを呼び、データベースを更新し、ファイルを操作する——こうした自律的なツール実行の基盤がFunction callingだ。ツール定義のJSON Schemaが甘いだけで、モデルはパラメータを誤解し、意図しない関数を呼び出す。設計の精度がエージェントの信頼性に直結する。

## Function callingの仕組みとツール定義の3要素

> Claudeのツール呼び出しは3要素のJSONスキーマで定義され、モデルが関数と引数を決定する。

Claudeにツールを渡すには、APIリクエストの `tools` パラメータに定義オブジェクトの配列を指定する。各定義の構成要素は3つだ。

| フィールド | 内容 |
|---|---|
| `name` | 英数字・アンダースコア・ハイフンのみ（正規表現: `^[a-zA-Z0-9_-]{1,64}$`）|
| `description` | ツールが何をするか・いつ使うか・何を返すかを記述するテキスト |
| `input_schema` | パラメータ構造を定義するJSON Schemaオブジェクト |

追加で `input_examples`（任意）を指定できる。ネストが深いパラメータや書式が厳密なフィールドでの誤呼び出しを減らす効果がある。例1件あたり20〜200トークンのコストが加わるため、必要な箇所に限定する。

`tools` を渡すと、APIはこれをシステムプロンプトへ自動注入する。モデルはスキーマを読んで呼び出すツールと入力値を判断し、`stop_reason: "tool_use"` で応答を返す。呼び出し結果は次のターンで `tool_result` コンテンツブロックとして渡す。この「判断→呼び出し→結果受け取り」のループがエージェントループの基本単位だ。

## ツール定義で性能を決めるdescriptionの書き方

> ツール定義でモデル性能に最も影響するのはdescriptionで、最低3〜4文の記述が推奨されている。

Anthropicの公式ガイドラインは「descriptionがツールパフォーマンスに最も影響する唯一の要素」と明言している。短い説明はモデルに曖昧さを残す。

**不十分な例（避けるべき）:**
```json
{
  "name": "get_stock_price",
  "description": "Gets the stock price for a ticker.",
  "input_schema": { "..." }
}
```

**推奨される例:**
```json
{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. Returns the latest trade price in USD. Use this when the user asks about the current or most recent price of a specific stock. Does not return historical data, earnings, or company information.",
  "input_schema": { "..." }
}
```

推奨例は「何をするか」「入力の制約」「何を返すか」「いつ使うか」「何を返さないか」の5点を網羅している。パラメータ側の `description` フィールドも同様に、値の形式・範囲・選択肢の意味を記載する。`enum` で有効な値を絞ると、モデルが常に正しい選択肢を選べる。

### ツール統合と名前空間設計

ツール数が増えると選択精度が下がる。関連操作を1ツールに集約し、`action` パラメータで分岐させる設計が有効だ。`create_pr`・`review_pr`・`merge_pr` と別々に定義するより、`github_pull_request` に `action` パラメータを持たせる方が、モデルの選択ミスが減る。

複数サービスにまたがるツールセットでは名前にプレフィックスで名前空間を切る（例: `github_list_prs`、`slack_send_message`）。Tool Searchと組み合わせる場合はプレフィックス設計の一貫性がとくに重要になる。

## JSON outputsとstrict tool useの使い分け

> JSON outputsはレスポンスの形式を制御し、strict: trueはツール入力を検証する。目的が違う2機能だ。

ClaudeのAPIは「モデルが返す内容の形式保証」と「ツール呼び出しパラメータの検証」を別機能で提供している。

| 機能 | 目的 | 設定方法 |
|---|---|---|
| JSON outputs | 最終応答をJSONスキーマに準拠させる | `output_config.format` |
| Strict tool use | ツール入力パラメータをスキーマで検証 | ツール定義に `strict: true` |

**JSON outputsを選ぶ場面:** Claudeの応答そのものを構造化データとして受け取りたい場合（フォーム入力抽出、レポート生成など）。

**Strict tool useを選ぶ場面:** ツールパラメータの型違反がダウンストリームロジックを壊す場合。`strict: true` を設定すると制約デコードにより入力が保証される。`additionalProperties: false` と `required` の明示が必要だ。

**両方を組み合わせる場面:** 複雑なエージェントワークフローで、ツール呼び出しの信頼性と最終応答の形式保証を同時に確保したいとき。

### スキーマ複雑度の制限と設計への影響

`strict: true` にはリクエスト単位の上限がある。**strictツール数は最大20**、**オプションパラメータ合計は24**、**ユニオン型パラメータは16** だ。これを超えると `"Schema is too complex"` エラーが返る。対処法は3つある。スキーマのネストをフラットにする、厳格検証が必要なツールとそうでないものを分ける、または複数リクエストに分割する。

また `strict: true` ツールの `name` と `description` 変更はキャッシュを無効化しないが、スキーマ構造の変更はグラマーの再コンパイルを引き起こし初回レイテンシが増す。ツール定義の変更頻度を最小化するよう設計する。

## ツールレスポンスの設計原則

> ツールは次の行動判断に必要な情報のみを返し、余剰フィールドはコンテキストを圧迫する。

ツール実装側で踏まえるべき3原則を示す。

1. **セマンティックな識別子を返す**: 内部オブジェクトIDではなく、スラッグやUUIDなどモデルが参照しやすい識別子を使う
2. **必要なフィールドだけに絞る**: 全カラムをそのまま返さず、次のアクション判断に必要な情報のみを含める
3. **エラーを構造化する**: 失敗時も `{"success": false, "reason": "not_found"}` のような構造応答を返し、モデルがリトライやフォールバックを判断できるようにする

レスポンス設計は[エージェントの可観測性](/blog/agent-observability-tracing-instrumentation/)と合わせて考えるべきだ。ツール呼び出しのスパンを記録することで、どのツールがコンテキストを圧迫しているかを可視化し、定義の改善に活かせる。

MCPを使う場合は、`input_schema`（Claude API側）と `inputSchema`（MCP側）でフィールド名が異なる点に注意が必要だ。[MCPサーバー実装](/blog/mcp-server-implementation-tool-design/)と組み合わせる場合は両仕様の差異を把握しておく。

### 規模別の留意点（SMB / エンタープライズ）

**SMBの場合:** ツール数を5〜10本に絞り、各descriptionを充実させることが最優先だ。strict modeは「パラメータ不正が業務フローを壊す」箇所（会計API呼び出し、顧客データ更新など）に限定して適用し、保守コストを最小化する。モデルはClaude Haiku 4.5でコストを抑えつつ、多ツール選択が必要な複雑なフローにのみClaude Opusを使い分ける構成が現実的だ。Kuu株式会社の[AIエージェント運用管理サービス](/services/ai-ops/)では、ツール設計から運用体制の整備まで一貫して支援している。

**エンタープライズの場合:** ツール数が数十〜数百規模になると、Tool Searchと名前空間設計の組み合わせが必須になる。strictツール数の上限（20ツール/リクエスト）はチーム横断でのツール統合に影響するため、リクエスト分割戦略を事前に設計する。スキーマ変更のキャッシュ無効化コストをAI FinOpsの観点で計上し、[LLMゲートウェイ](/blog/llm-gateway-routing-rate-limiting/)経由でのコスト配賦に組み込む。PHIなどの機密情報をスキーマのenum値・プロパティ名に含めないHIPAAの制約も設計段階で確認する。大規模なエージェント統制基盤の構築には[RDEサービス](/services/rde/)が対応する。

## 参考

- [Define tools — Anthropic公式ドキュメント](https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use)
- [Structured outputs — Anthropic公式ドキュメント](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
- [Writing tools for agents — Anthropic Engineering](https://www.anthropic.com/engineering/writing-tools-for-agents)

## まとめ

Function callingのツール定義品質は、エージェントの信頼性を直接左右する。descriptionの充実、操作の統合と名前空間設計、strict modeの適所適用、JSON outputsとの役割分担を正しく実装することで、エージェントが意図通りに動く基盤が整う。

ツール設計の段階から[エージェントガバナンス](/glossary/agent-governance/)の観点を組み込みたい場合は、[Kuu株式会社のAIエージェント運用管理サービス](/services/ai-ops/)にご相談ください。