How to evaluate an agent's tool calls

An agent can say it changed a delivery address without calling the update tool. It can also call the right tool with the wrong order ID and produce a perfectly readable confirmation. Evaluating the final message alone misses both failures.

A tool-use eval needs evidence of the action and its result. Record tool requests, arguments, responses, errors, and the relevant state before and after execution. Then score the properties the task actually requires.

Separate four questions

Valid JSON proves only that arguments parse. A successful HTTP response proves only what that service's response contract establishes. Neither proves that the intended object changed correctly.

Use a language-model judge where interpretation is necessary, such as deciding whether the agent asked an appropriate clarification question. Prefer direct assertions when the expected result is available as structured state.

Write a task with observable constraints

For an illustrative order-management eval, initialize a sandbox with two orders and ask the agent to change the address on one of them. The rubric could require:

1. Only the specified order changes.
2. The final address matches the requested fields.
3. No duplicate write occurs after a successful update.
4. The final message accurately reports success or failure.

Add a second case with an ambiguous order reference. Passing behavior might be to request clarification before writing. Add a third where the update times out after the server has committed it. This tests whether the agent verifies state or safely retries using the application's idempotency mechanism.

Run these against resettable fixtures or mocked tools. A production action is not an appropriate substitute for a test fixture just because the model is being evaluated.

Allow multiple valid paths

Exact sequence matching is useful when a sequence is mandatory. For example, an authorization check may have to precede a write. But two agents can reach the same valid outcome through different harmless read operations.

Express necessary ordering constraints separately from optional steps. Check that required actions occurred, prohibited actions did not occur, and final state is correct. If efficiency matters, add a separate budget for redundant reads, retries, latency, or tokens.

Ragas lists tool-call accuracy and agent-goal metrics as separate evaluation options. That separation is useful: selecting the expected tools and achieving the goal are related but distinct outcomes. Ragas metric catalog.

Treat missing evidence as a result

If a trace stops before the tool response, the outcome is unknown. Report that separately from a confirmed task failure and from a pass. Otherwise instrumentation loss can quietly inflate or depress quality scores.

A useful experiment report includes task pass rate, prohibited-action count, execution errors, incomplete traces, and per-case cost. Break results down by task family and repeat nondeterministic cases. Do not average a critical unauthorized write into a generally good helpfulness score.

Store the trajectory alongside the verdict

Braintrust supports trace-level scorers that can inspect multiple spans, as well as scorers operating on individual spans. Select the scope that contains the evidence your assertion needs. A single response span cannot prove that an entire workflow completed correctly. Braintrust scorer scopes.

Keep the failing trajectory and the fixture version with the case. That makes a later regression explainable: which operation changed, what state it produced, and whether the confirmation matched reality. The production-to-dataset guide covers how to turn those incidents into reusable cases.

Continue with the evals implementation guide for the full workflow.