> For the complete documentation index, see [llms.txt](https://learning.contextqa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learning.contextqa.com/ai-agent-testing/agent-evaluation/verify-tool-actions.md).

# Verify AI Agent Tool Actions and Business Outcomes

Use ContextQA verifier tools to compare agent claims with backend state and distinguish verification from setup, variables, and health checks.

> **Documentation owner:** [Deep Barot](https://contextqa.com/academy/) · **Last updated:** November 11, 2026

## Quick answer

To verify an AI agent’s business outcome, compare its claim with authoritative backend state for the same test. ContextQA tools can use REST API or AWS Lambda transports and have explicit roles. Assign a read-only tool the Verifier role when a judge must check a transaction; keep environment setup and variable loading in their separate roles.

## Key takeaways

* A spoken or written success message is not proof of a persisted transaction.
* Only the Verifier role exposes a tool to the judge; new tools start as Not in use.
* Correlate backend evidence to the test and keep verification read-only.

## Choose the right role

Open the project’s **Tools** page. Each tool has one role. The live form distinguishes these responsibilities:

| Role                     | Purpose                                                                    |
| ------------------------ | -------------------------------------------------------------------------- |
| Not in use               | Nothing calls it; the judge cannot see it                                  |
| Verifier                 | The judge checks actual state; this is the role visible to the judge       |
| Variable Source          | Loads values when the run starts, unattended; not visible to the judge     |
| Health check probe       | One per project; a read-only, no-argument check before the run             |
| Pre-Run Environment Hook | One per project; prepares or resets the test environment and may mutate it |

![Tools form showing REST API and AWS Lambda transports and the tool role selector](https://4255556216-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKlyaXxb76z3Dn47TrZkU%2Fuploads%2Fgit-blob-8b28d57bfd7f9c21040649de7867b89790619291%2Fverifier-tools.jpg?alt=media)

## Configure a verifier

1. Choose **REST API** or **AWS Lambda** according to the backend integration.
2. Give the tool a description that clearly explains the fact it can verify. The judge uses descriptions to discover relevant tools.
3. Select **Verifier** as its role.
4. Define required parameters with precise descriptions so the correct values can be extracted from the case.
5. For REST, configure the method, endpoint, headers, and body as required by your service. Use a read-only operation for verification.
6. Use `{arg}` for a runtime tool argument and `{{variable}}` for a project variable where the form supports substitution. Set a response path if only part of the payload is relevant.
7. Store credentials in the protected authentication mechanism. Literal secrets are write-only; variable references remain visible.
8. Enable tool verification on the relevant custom metric and exercise it with a known case.

An illustrative endpoint is `GET /test-bookings/{booking_id}`. This is an example contract for your service, not a ContextQA API. Its response should include the fields required for the assertion, such as the booking identifier, customer identifier, final date/time/timezone, and status.

## Define three independent assertions

| Layer     | Example question                                       | Evidence                                    |
| --------- | ------------------------------------------------------ | ------------------------------------------- |
| Requested | What did the user finally ask for?                     | Conversation with corrections resolved      |
| Confirmed | What did the agent read back and receive approval for? | Confirmation exchange                       |
| Persisted | What was actually created or changed?                  | Authoritative record returned by a verifier |

Pass a booking workflow only when the required layers agree. A verifier contradiction causes the associated tool-grounded LLM criterion to fail; the rubric still defines what the criterion means. Missing evidence must not be interpreted as a successful transaction.

## Avoid false verification

Query by a unique record or test correlation identifier rather than by “latest booking.” Otherwise, an older success or another parallel test may satisfy the check accidentally. Check duplicate creation as well as existence when the requirement is exactly one transaction.

For asynchronous work, define when the outcome should become visible and how it is correlated. A call ending successfully does not automatically verify a later summary, CRM update, notification, or other post-call process. Test that later workflow separately unless the configured evaluation explicitly captures the required evidence.

Use the environment hook only for authorized test setup. Do not make a verifier repair the state it is supposed to inspect. See [test design](https://learning.contextqa.com/ai-agent-testing/agent-evaluation/design-test-cases.md) and [booking outcome examples](https://learning.contextqa.com/ai-agent-testing/voice-ai-testing/booking-outcomes.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://learning.contextqa.com/ai-agent-testing/agent-evaluation/verify-tool-actions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
