> ## Documentation Index
> Fetch the complete documentation index at: https://docs.egma.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Mock tool responses

Use a mock to set the response your agent gets from a backend or replace a
write during a simulation.
For example, return no appointment slots or make a booking call fail.

Each mock belongs to one test and is saved with that test's version. Other
tests can use different answers for the same tool.

## Add an answer

After `## Expected behaviors`, add `## Mock tools`. Use the exact tool name as
the subheading and put the tool's normal result inside `answer`:

````markdown theme={null}
## Mock tools

### check_availability

```json
{
  "answer": {
    "slots": []
  }
}
```
````

`answer` can contain any JSON value that matches the tool's real response
shape. The mock returns the same configured result each time that named tool
is called in the simulation.

The mock does not check the tool's arguments. Add an expected behavior if you
need to check that the agent used the right caller, provider, date, or other
arguments.

## Test a failure

Use `error` with a string to make the tool fail:

````markdown theme={null}
## Mock tools

### book_appointment

```json
{
  "error": "The booking service is unavailable."
}
```
````

Write the expected behavior for the agent's response to that failure, such as:

```text theme={null}
The agent explains that the appointment could not be booked and does not
claim that the booking was confirmed.
```

Each JSON block must contain exactly one of `answer` or `error`. Do not add
delay, status, or matching rules to the envelope.

## Use a connection that supports mocks

| Connection       | Setup                                                                                                                                                                    |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Retell text mode | Egma sends the test's mock answers with the conversation.                                                                                                                |
| Retell web call  | Egma prepares a temporary agent version for the run. Your Egma instance must be reachable by Retell.                                                                     |
| LiveKit          | Call `await simulation(agent, ctx, session)` from the [Python SDK](/tools/livekit-python-sdk) or [JavaScript SDK](/tools/livekit-javascript-sdk) before `session.start`. |

Retell phone calls do not apply these mock answers. Use text mode or a web call
when your Retell test depends on mocks.

For LiveKit, the `simulation` helper is required even when a test has no mocks.
It sends the agent's spans, reports its tools, and applies the running test's
mock answers. Set `EGMA_URL` and `EGMA_API_KEY` in the worker environment.
If the setup exchange fails, the helper raises `NotReported` and the agent
session does not start. The `monitor` helper is for production conversations;
it does not enable simulations.

<Warning>
  Only the tools named in the test are mocked. Every other tool runs normally.
  Include each write you need to replace, and verify the supported connection
  before running a test against a production backend.
</Warning>

## Check the result

Run `egma push`, then [start a run](/guides/start-and-follow-a-run). Open the
simulation's transcript and inspect the tool call, its arguments, and its
result. The agent's trace records both real and mocked tool calls. Calls
answered by the test's mocks are marked **mocked**. The transcript prefers the
agent's tool evidence when it is available.

A misspelled mock name does not match a tool. It creates no tool call or warning,
and the correctly named tool can still run its real implementation.

If a real backend was called, check the exact tool name, connection type, and
LiveKit setup. If the agent reacts incorrectly to the answer, compare
the mock's response shape with the tool's actual contract.