> ## Documentation Index
> Fetch the complete documentation index at: https://arizeai-433a7140.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool Invocation

> Evaluate whether LLM tool calls have correct arguments and formatting using a Phoenix-managed judge model.

## Overview

The **Tool Invocation** evaluator determines whether an LLM invoked a tool correctly with proper arguments, formatting, and safe content. This evaluator focuses on the *how* of tool calling — validating that the invocation itself is well-formed — rather than whether the right tool was selected.

This is an LLM evaluator: Phoenix runs a judge model against a managed prompt template on your behalf.

**When to Use**

Use the Tool Invocation evaluator when you need to:

* **Validate tool call arguments** — Ensure all required parameters are present with correct values
* **Check JSON formatting** — Verify tool calls are properly structured
* **Detect hallucinated fields** — Identify when the LLM invents parameters not in the schema
* **Audit for unsafe content** — Check that arguments don't contain PII or sensitive data
* **Evaluate multi-tool invocations** — Validate when the LLM calls multiple tools at once

<Info>
  This evaluator validates tool invocation correctness, not tool selection. For evaluating whether the right tool was chosen, use the [Tool Selection evaluator](/docs/phoenix/evaluation/server-evals/pre-built-metrics/tool-selection) instead. The two evaluators are complementary — Tool Selection catches wrong-tool errors while Tool Invocation catches malformed-call errors — and are best run together for complete tool-calling coverage.
</Info>

**Input Mapping**

The template handles output formatting automatically — it pulls from your experiment's output and formats the tool calls and available tools into a human-readable structure for the judge. You don't need to configure anything for the output side.

The only field you may need to map is **`input`**, which should point to the user query from your dataset. For example, if your dataset has `input.query`:

| Template field | Dataset column |
| -------------- | -------------- |
| `input`        | `input.query`  |

## Output Labels

| Property      | Value                        | Description                                    |
| ------------- | ---------------------------- | ---------------------------------------------- |
| `label`       | `"correct"` or `"incorrect"` | Classification result                          |
| `score`       | `1.0` or `0.0`               | Numeric score (1.0 = correct, 0.0 = incorrect) |
| `explanation` | `string`                     | LLM-generated reasoning for the classification |
| Optimization  | Maximize                     | Higher scores are better                       |

**Criteria for Correct (1.0):**

* All required parameters are present with correct values
* Tool call is properly structured and formatted
* No hallucinated fields or parameters invented by the LLM
* Arguments contain no unsafe content (PII, sensitive data)

**Criteria for Incorrect (0.0):**

* Required parameters are missing or have incorrect values
* Tool call is malformed or improperly structured
* The LLM invented parameters not in the schema
* Arguments contain unsafe or sensitive content

## Using in Phoenix

1. Navigate to your dataset and open the **Evaluators** tab.
2. Click **Add Evaluator** and select **LLM Evaluator Template**, then choose **tool\_invocation**.
3. In the evaluator slide-over, you'll see the prompt template and choices are pre-configured. You can use the defaults or edit the prompt to fit your use case.
4. Set an **input mapping** for the `input` field so the template pulls from the correct column in your dataset. Output formatting is already handled by the template — no output mapping needed.
5. Optionally, configure which LLM to use as the judge model.
6. Click **Create**. The evaluator will automatically run on any future experiments for that dataset.

## See Also

* [Pre-Built Metrics Overview](/docs/phoenix/evaluation/server-evals/pre-built-metrics)
* [Tool Invocation (client-side)](/docs/phoenix/evaluation/pre-built-metrics/tool-invocation) — run this evaluator from Python or TypeScript code
* [Tool Selection](/docs/phoenix/evaluation/server-evals/pre-built-metrics/tool-selection) — evaluate whether the right tool was chosen
* [Correctness](/docs/phoenix/evaluation/server-evals/pre-built-metrics/correctness) — evaluate factual accuracy of LLM responses