Validate tool trajectories beyond final answers

Learning objective

Evaluate tool selection, call parameters, execution results, and fallback correctness.

Core idea

A convincing final answer can conceal a wrong tool, an invented argument, a failed execution, or a fallback that bypasses a restriction. For an architect, tool evaluation must examine what the agent proposed, what actually ran, what returned, and how the agent used the result. Each stage answers a different question.

Microsoft Foundry provides process evaluators for tool behavior and a trajectory evaluator for comparisons with expected actions. Combine those signals with deterministic assertions over business results and failure-path fixtures. See 2.3.1 for typed tool enforcement, 2.3.8 for retry and fallback design, and 2.3.10 for runtime result validation. Here, evaluation fixtures and scores test those implementations and the agent’s choices.

How it works

Preserve the available tools and observed interaction

Foundry’s evaluation dataset can represent an interaction in messages. Include the user request, relevant trusted instructions, assistant tool calls, tool responses, and final assistant response. A call records its name, arguments, and tool_call_id; the matching tool response carries that call identifier. Preserve this relationship so a judge does not associate a result with the wrong call.

The separate tool_definitions field describes the tools available to the agent, including their names, descriptions, and parameter schemas. An interaction shows what the agent called; definitions show what it could have selected. If you include only the selected tool, you remove the alternatives required to judge selection quality.

For target-generated cloud evaluation, map structured output through {{sample.output_items}}, rather than passing only {{sample.output_text}} to process evaluators. For recorded interactions, map the stored structured fields. See 3.1.2 for the run configuration. Retain failed and canceled paths instead of building a dataset containing only successful final answers.

Separate selection from parameter accuracy

builtin.tool_selection evaluates whether the agent chooses the necessary tools without unnecessary calls. Test both required calls and cases where the available tools should remain unused.

builtin.tool_input_accuracy evaluates call parameters against strict criteria: groundedness, type compliance, format compliance, required parameters, no unexpected parameters, and value appropriateness. A valid integer can still be the wrong customer’s identifier. Supply the request context and tool definitions needed to judge where each value should come from.

builtin.tool_call_accuracy gives a broader assessment of tool choice, parameters, and efficiency. It uses a 1–5 score converted to pass/fail; the documented default threshold is 3. Tool Selection and Tool Input Accuracy instead provide binary outcomes. Use the broader score for diagnosis without replacing the strict parameter check when every argument must be correct.

These evaluators use a model judge. Pair them with deterministic assertions when the fixture gives an exact expected identifier, allowed value, or prohibited call. Use the custom grade() contract described in 3.1.3 to express those assertions. A judge’s favorable explanation does not override a recorded unauthorized operation or an exact-value mismatch.

Distinguish execution from use of results

builtin.tool_call_success measures whether calls complete without technical errors or exceptions. Its required input can be response or messages. Give it actual tool-result evidence, not an assistant’s unsupported assertion that the call succeeded.

builtin.tool_output_utilization measures whether the agent interprets and uses returned results correctly in its final response and subsequent calls. A call can succeed while the agent ignores a negative result, selects the wrong row, or claims that a requested change occurred when the tool returned a business rejection.

Each evaluator scores a different stage of the same tool exchange.

For evaluation, retain the recorded result and fixture assertions as evidence of the expected business outcome, then score the agent’s interpretation separately. Neither a tool-use judge nor a success score independently proves the external system’s final state.

The Tool Use Quality (preview) composite, builtin.tool_use_quality, batches Tool Call Accuracy, Tool Call Success, Tool Input Accuracy, Tool Output Utilization, and Tool Selection in one judge call. Its primary result passes only when every applicable component passes; skipped components do not cause failure. If every component is skipped, the primary result is not_applicable. Inspect applicability and component results rather than treating an absent tool check as evidence of correct tool behavior.

Test fallback against expected actions

Turn the fallback policy designed in 2.3.8 into fixtures for transient failure, invalid input, denied access, empty successful results, and uncertain writes. Each fixture records the policy’s expected actions and terminal outcome.

Foundry’s builtin.task_navigation_efficiency provides a deterministic trajectory comparison of observed actions or messages against expected_actions; it needs no judge deployment. Its optional matching_mode values carry different acceptance rules:

For a fallback regression test that must forbid extra writes, use exact_match when the expected trajectory is fully specified, or supplement a permissive match with an explicit prohibited-call assertion. any_order_match is unsuitable when checking whether a failure occurs before fallback begins. A sequence comparison validates the recorded path; it does not prove that every call’s business result is correct.

Include no-fallback fixtures and assert the expected terminal outcome, prohibited calls, and any required reconciliation step from the policy. Evaluate fallback responses with the same output-contract and instruction checks from 3.1.3.

Respect evaluator support limits

The agent-evaluator reference lists support for File Search, user-defined Function Tool, MCP, and knowledge-based MCP. It warns of limited support for Azure AI Search, Bing Grounding, Bing Custom Search, SharePoint Grounding, Code Interpreter, Fabric Data Agent, and Web Search, and advises avoiding several tool and groundedness evaluators for interactions containing those tools.

Do not interpret a missing or unsuitable score as a pass on those interactions. Use deterministic fixtures or appropriately scoped human review for evidence that the supported evaluator cannot establish. See 3.1.1 for human evaluation design. Preserve the tool type in the experiment record so results from supported function-tool cases are not generalized to every integration.

Key distinctions and trade-offs

Selection versus execution: Choosing the right tool does not mean its call succeeds. A successful call to the wrong tool still fails the task.

Parameter validity versus correctness: Schema validation protects shape and types; contextual evaluation and exact assertions protect the intended values.

Execution success versus business success: A technically completed call can return an unsuccessful business outcome that the agent must report accurately.

Trajectory match versus safe fallback: A matching path supplies process evidence. Constraints, side effects, and result validity remain separate acceptance checks.

Architecture / decision scenario

A support agent can call primary and alternate read-only order lookup tools, then request a refund through a separate write tool. The test suite includes a healthy lookup, a primary timeout, denied access, and a refund whose completion is uncertain. Tool definitions expose all available choices, and messages retain each call and matched result.

Tool Selection scores the choices; Tool Input Accuracy checks the order identifier; Tool Call Success captures the primary timeout; Tool Output Utilization checks that the agent reports the alternate result accurately. A timeout fixture expects primary lookup followed by the authorized alternate lookup. Task Navigation Efficiency uses exact_match, and a deterministic assertion forbids a refund call in that case.

The denied-access fixture expects escalation rather than a weaker lookup path. The uncertain-refund fixture requires the application’s reconciliation result before any repeated write. Even if a final response sounds helpful, promotion fails when the candidate bypasses either rule. A technically failed primary call is visible in the diagnostic score while the permitted read-only fallback can still satisfy the case’s end-to-end acceptance rule.

Common exam traps

• Supplying only a final answer to an evaluator that needs tool-call evidence.
• Omitting available alternatives from tool_definitions.
• Treating type-correct arguments as proof that their values are grounded.
• Equating Tool Call Success with correct business state or correct result interpretation.
• Choosing an order-insensitive or extra-step-permitting trajectory match for a strict fallback rule.
• Treating skipped components or unsupported tool integrations as passing evidence.

What to remember

Evaluate selection, arguments, technical execution, and result use independently. Preserve calls, matching results, and available definitions. Test allowed and prohibited fallback paths with explicit expected actions and deterministic assertions, and interpret each evaluator within its documented support and applicability.

Knowledge check

References

• Microsoft, Agent evaluators for generative AI
• Microsoft, Evaluation dataset schema in Microsoft Foundry
• Microsoft, Custom evaluators
• Microsoft, Tool selection evaluation sample