# ツール呼び出し精度評価——3指標の設計法

> AIエージェントのツール呼び出し精度は、選択・引数・順序の3指標で評価できる。RAGASのToolCallAccuracy等の指標設計とSMBでの導入手順を解説する。

- Canonical: https://kuucorp.com/blog/agent-tool-call-accuracy-evaluation-design/
- Date: 2026-10-09
- Last modified: 2026-10-09
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
エージェントの最終出力が正しくても、途中のツール呼び出しが間違っていることがある。違うツールを選んだ、引数を取り違えた、呼ぶ順番がずれた——これらは最終出力のテキストだけを見ていると発見できない。ツール呼び出しそのものを評価対象にする設計が必要だ。

## なぜ最終出力だけの評価では不十分か

> 最終出力が正解でも、途中のツール呼び出しが誤っていれば再現性のない偶然の正解にすぎない。

LLM-as-judgeで最終出力を採点する設計は多くのチームが導入済みだ。しかし最終出力の正しさと、プロセスの正しさは別物だ。たとえば在庫確認エージェントが本来呼ぶべき`check_inventory`ではなく`search_catalog`を呼び、たまたま同じ結果を返したケースは、次のリクエストでは失敗する。ツール呼び出しの選択・引数・順序を個別に測定しないと、こうした脆さは本番で初めて露見する。

## 何を測るべきか——選択・引数・順序の3指標

> ツール呼び出しの評価は、ツール選択の正誤・引数の正確性・呼び出し順序を分けて測定する3指標に分解できる。

OSSの評価フレームワークRAGASは、エージェント専用の指標として`ToolCallAccuracy`と`ToolCallF1`を定義している。前者はツール呼び出しの順序と引数の一致度を評価し、引数の一致率に順序一致の有無を掛け合わせてスコアを出す仕組みだ。厳密な順序一致（デフォルト）と、順序を問わない柔軟モードの2種類がある。後者の`ToolCallF1`は呼び出しすぎ・呼び出し漏れを許容し、期待される呼び出しとの一致を適合率・再現率・F1で評価する。

実務では3指標に分けて記録するとよい。

1. **選択精度**: 期待したツールを呼んだか（名前の一致）
2. **引数精度**: 呼んだツールの引数が期待値と一致するか
3. **順序整合性**: 複数ツールを呼ぶ際、順序が業務要件を満たすか

この3つを個別に可視化すると、「ツールは正しく選べているが引数でよく間違える」のような具体的な弱点が見える。

## Claude Agent SDKでツール呼び出しをトレースする

> Claude Agent SDKは`PreToolUse`/`PostToolUse`フックでツール呼び出しの前後を捕捉でき、評価用ログに転用できる。

ツール呼び出しを評価するには、まず呼び出しの記録が必要だ。Claude Agent SDKのエージェントループは、Claudeがツール呼び出しを要求するたびに`AssistantMessage`を発行し、SDKがツールを実行した結果を`UserMessage`としてClaudeに返す。この一往復が1ターンであり、`PreToolUse`フックで実行前のツール名・引数を、`PostToolUse`フックで実行後の結果を捕捉できる。フックはアプリケーション側のプロセスで動くため、エージェントのコンテキストウィンドウを消費しない。

セッション終了時に発行される`ResultMessage`には、ツール呼び出しを含む全ターン数とトークン使用量・コストが記録される。この2つのフックと`ResultMessage`の組み合わせで、期待されるツール呼び出し列（reference）と実際の呼び出し列を記録し、オフラインでRAGASのような指標に通せる評価データセットを作れる。

## SMBチームの段階的導入ステップ

> SMBチームはまず5〜10タスクの期待呼び出し列を手作業で定義し、そこから指標を自動計算する構成が現実的だ。

大規模な評価基盤を最初から作る必要はない。

**ステップ1**: 代表的なタスク5〜10件について、期待されるツール呼び出し列（ツール名・引数・順序）を手作業でYAMLやJSONに書き出す
**ステップ2**: `PreToolUse`フックで実際の呼び出しをログに記録し、ステップ1の期待値と突き合わせる
**ステップ3**: 選択精度・引数精度・順序整合性の3指標を週次で集計し、どの指標が低いかを追跡する

[AIエージェントのトレース計装](/blog/agent-observability-tracing-instrumentation/)を既に導入している場合は、そのログをそのまま期待値との突き合わせに再利用できる。ツール呼び出し評価の設計から運用まで、[Kuuのai-ops](/services/ai-ops/)で支援している。

## 参考

- [How the agent loop works — Claude Agent SDK Docs](https://code.claude.com/docs/en/agent-sdk/agent-loop)
- [Agents metrics — RAGAS Docs](https://docs.ragas.io/en/latest/concepts/metrics/available_metrics/agents/)

## まとめ

ツール呼び出しの精度は、最終出力の採点だけでは見えない。選択・引数・順序の3指標に分解し、Claude Agent SDKのフックで呼び出しログを記録すれば、SMBチームでも5〜10タスクの期待値定義から評価を始められる。

ツール呼び出し評価基盤の設計に関するご相談は[Kuu株式会社のai-ops](/services/ai-ops/)まで。