Tool Selection Correctness Grading Prompt Template

This prompt is designed for agent platform teams and evaluation engineers who need to programmatically verify that a language model selected the correct tool from a defined catalog. The core job-to-be-done is binary classification: given a user task, a conversation context, and a list of available tools, did the model choose the right one? This is not a prompt for generating tool calls; it is a grading prompt that acts as an LLM judge to score a prior model's decision. The ideal user is someone building a CI/CD evaluation harness who needs a repeatable, automatable signal to gate a model or prompt update before it reaches production.

Use this prompt when you have a closed tool catalog and a golden dataset of expected tool selections. It works best when the correct tool choice is unambiguous given the context. You must provide the full tool catalog with descriptions, the user's input, any relevant conversation history, and the model's actual tool selection. The prompt produces a structured pass/fail judgment with a justification, making it suitable for automated precision/recall tracking across test suites. Do not use this prompt when the correct tool is ambiguous or when multiple tools could reasonably satisfy the request—this is a correctness grader, not a preference judge. For those cases, use a pairwise comparison or rubric-based evaluation instead.

This prompt is a component in a larger evaluation pipeline, not a standalone product feature. It assumes you already have a test suite of examples where the ground-truth tool selection is known. Wire it into your regression testing framework to catch tool-selection regressions when you change system prompts, update tool descriptions, or swap models. The output is designed to be machine-readable, but the justification field provides human-readable debugging information when a test case fails. Always pair this prompt with human spot-checking of a sample of judgments, especially when adding new tools to the catalog or when the judge model disagrees with your ground truth. The judge can be wrong, and calibration against human ratings is essential before trusting automated pass/fail decisions at scale.

This section provides the core prompt template for evaluating tool selection correctness. The template is designed to be copied directly into your evaluation harness, with placeholders that you replace with your specific tool catalog, agent trace, and grading criteria. It produces a binary pass/fail judgment with a structured justification, making it suitable for automated regression testing, CI/CD gates, and batch evaluation pipelines. The prompt assumes you have a golden dataset or ground-truth label for which tool should have been selected in each scenario.

textCopy
You are an expert evaluator grading an AI agent's tool selection decision. Your task is to determine whether the agent chose the correct tool from the provided tool catalog, given the user's request and available context.

# TOOL CATALOG
[TOOL_CATALOG]

# USER REQUEST
[USER_REQUEST]

# AVAILABLE CONTEXT
[CONTEXT]

# AGENT'S SELECTED TOOL
[SELECTED_TOOL_NAME]

# EXPECTED CORRECT TOOL (GROUND TRUTH)
[EXPECTED_TOOL_NAME]

# GRADING INSTRUCTIONS
1. Compare the agent's selected tool against the expected correct tool.
2. If the selected tool matches the expected tool exactly, the grade is PASS.
3. If the selected tool differs from the expected tool, the grade is FAIL.
4. If the agent selected no tool but the expected tool is present, the grade is FAIL with abstention noted.
5. If the agent selected a tool but the expected tool indicates no tool should be called, the grade is FAIL with over-action noted.

# OUTPUT FORMAT
Return a JSON object with the following structure:
{
  "grade": "PASS" | "FAIL",
  "selected_tool": "[tool name or null]",
  "expected_tool": "[tool name or null]",
  "justification": "Brief explanation of why the grade was assigned, referencing specific tool capabilities from the catalog.",
  "failure_category": null | "wrong_tool" | "abstention_error" | "over_action" | "hallucinated_tool"
}

# CONSTRAINTS
- Only use tools listed in the TOOL CATALOG for your evaluation.
- If the agent selected a tool not present in the catalog, set failure_category to "hallucinated_tool".
- Do not evaluate argument correctness; only evaluate tool selection.
- Base your judgment solely on the provided context and tool catalog.

To adapt this template for your evaluation pipeline, replace each square-bracket placeholder with your actual data. The [TOOL_CATALOG] should contain the full list of available tools with their names and descriptions, formatted consistently with how they were presented to the agent. The [USER_REQUEST] and [CONTEXT] should match exactly what the agent received. The [SELECTED_TOOL_NAME] comes from the agent's trace, and [EXPECTED_TOOL_NAME] comes from your golden dataset. For batch evaluation, wrap this prompt in a loop that iterates over your test cases, collecting grades and failure categories for precision/recall calculation. If your tool catalog is large, consider truncating it to only relevant tools to reduce token usage and improve grading accuracy. Always validate the output JSON structure before aggregating results, as malformed judge outputs can corrupt your metrics.

The Tool Selection Correctness Grading prompt is designed to operate as a deterministic evaluation step within a larger CI/CD or regression testing pipeline, not as a one-off manual check. To integrate it, you will need a test harness that iterates over a golden dataset of test cases, each containing a user request, the available tool catalog at the time of the request, and the expected correct tool name. For each test case, the harness injects the model's actual tool selection into the [ACTUAL_TOOL_SELECTION] placeholder and the expected tool into [EXPECTED_TOOL_SELECTION], then calls the LLM judge. The judge returns a structured JSON object with a pass boolean and a justification string, which the harness parses to compute aggregate precision and recall across the entire test suite.

A robust implementation must include validation of the judge's output against a strict JSON schema before accepting the result. If the judge returns malformed JSON, a missing pass field, or an unexpected value, the harness should retry the grading call once with a stronger format instruction appended to the prompt. If the retry also fails, the test case should be flagged for human review and excluded from aggregate metrics to avoid corrupting your precision/recall calculations. Log every grading call—including the prompt version, model used, input test case ID, raw judge output, and validation status—so that you can trace judge drift or flakiness over time. For high-stakes tool-use workflows where a wrong tool call could trigger a destructive action, set a minimum precision threshold (e.g., 0.98) as a CI/CD gate and require a human sign-off on the full justification log for any failing test case before a new prompt or model version can be deployed.

When choosing a model for the judge, prefer a fast, cost-efficient option with strong instruction-following and JSON output capabilities. The judge's task is classification with justification, not complex reasoning, so a smaller model often suffices. However, if your tool catalog is large or tools have overlapping capabilities, test the judge's agreement rate with human annotators on a calibration set before trusting it in automation. Avoid wiring this prompt directly into a production agent's runtime decision loop; it is an offline evaluation tool. The next step after establishing your grading harness is to run it against your existing test suite, establish a baseline precision/recall score, and then integrate it into your prompt versioning pipeline so that every proposed change to system instructions or tool descriptions is automatically scored before release.