> ## 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.

# Configure Project-Level Mock Tools for Simulations

> Create, update, delete, and list project-level mock tools that intercept agent tool calls during simulations with controlled responses and delays.

Mock tools let you control what your agent "hears back" when it calls an external tool during a simulation. When Egma runs a test, it intercepts each tool call your agent makes and returns the configured answer (or error) instead of hitting your real backend. This lets you test exactly how your agent handles any outcome — including errors, edge cases, and slow responses — without depending on live external systems.

Project-level mock tools apply to every run started in the project unless a test overrides them for a specific tool. Unlike tests, mock tools are not versioned: edits take effect for runs started after the edit, and runs already in progress keep answering the world they froze at start. Unknown keys in a request body are refused by name rather than silently ignored, so a typo surfaces immediately.

***

## Create a mock tool

`POST /api/mock-tools`

Create a new project-level mock tool. Returns `201 Created` with the full mock tool object. If a mock tool for the same `tool` name already exists in the project, Egma returns `409 Conflict`.

### Request body

<ParamField body="tool" type="string" required>
  The tool name to intercept, e.g. `check_availability`. Must match exactly what your agent calls.
</ParamField>

<ParamField body="answer" type="any">
  The value to return when the agent calls this tool. Provide either `answer` or `error`, not both. `null` is a valid answer value.
</ParamField>

<ParamField body="error" type="string">
  An error string to return instead of an answer. Provide either `answer` or `error`, not both.
</ParamField>

<ParamField body="delay_ms" type="integer">
  How long Egma holds the answer back, in milliseconds. Use this to test your agent's behavior when a tool call is slow.
</ParamField>

<ParamField body="agents" type="string[]">
  Restrict this mock tool to specific agents, by name or `agt_…` identifier. Omit (or supply an empty array) to apply to every agent in the project.
</ParamField>

<ParamField body="project" type="string">
  Project to create the mock tool in. Defaults to the project your API key belongs to.
</ParamField>

### Response fields

<ResponseField name="id" type="string">
  Unique mock tool identifier (`mck_…`).
</ResponseField>

<ResponseField name="tool" type="string">
  The tool name this mock tool answers for.
</ResponseField>

<ResponseField name="answer" type="any">
  The configured answer value. Present only when the mock tool answers with a value (not an error).
</ResponseField>

<ResponseField name="error" type="string">
  The configured error string. Present only when the mock tool answers with an error.
</ResponseField>

<ResponseField name="delay_ms" type="integer">
  Configured delay in milliseconds. `0` means no delay.
</ResponseField>

<ResponseField name="agents" type="object[]">
  The agents this mock tool is scoped to. Empty array means it applies to all agents.

  <Expandable title="agent fields">
    <ResponseField name="id" type="string">Agent identifier (`agt_…`).</ResponseField>
    <ResponseField name="name" type="string">Agent display name.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

### Example — answer with a value

```bash theme={null}
curl -X POST https://your-egma-host/api/mock-tools \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "check_availability",
    "answer": { "slots": ["9 a.m.", "2 p.m.", "4 p.m."] }
  }'
```

### Example — answer with an error and a delay

```bash theme={null}
curl -X POST https://your-egma-host/api/mock-tools \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "book_appointment",
    "error": "the calendar service is temporarily unavailable",
    "delay_ms": 3000,
    "agents": ["front-desk"]
  }'
```

***

## Update a mock tool

`PATCH /api/mock-tools/:mockToolId`

Update one or more fields of an existing mock tool. Fields you omit are kept as-is. There is no version check here — edits overwrite in place and take effect immediately for future runs.

Sending an explicit `agents: []` sets the mock tool back to applying to all agents. Omitting `agents` entirely leaves the current scope unchanged.

### Path parameters

<ParamField path="mockToolId" type="string" required>
  The `mck_…` identifier of the mock tool to update.
</ParamField>

### Request body

<ParamField body="tool" type="string">
  New tool name.
</ParamField>

<ParamField body="answer" type="any">
  New answer value. To switch from an error answer to a value answer, supply `answer` in the body.
</ParamField>

<ParamField body="error" type="string">
  New error string. To switch from a value answer to an error answer, supply `error` in the body.
</ParamField>

<ParamField body="delay_ms" type="integer">
  New delay in milliseconds.
</ParamField>

<ParamField body="agents" type="string[]">
  Replacement agent scope list. An empty array means apply to all agents.
</ParamField>

### Response fields

Same shape as the create response: the full mock tool object after the update.

### Example

```bash theme={null}
curl -X PATCH "https://your-egma-host/api/mock-tools/mck_01abc" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "answer": { "slots": ["10 a.m.", "3 p.m."] },
    "delay_ms": 0
  }'
```

***

## Delete a mock tool

`DELETE /api/mock-tools/:mockToolId`

Remove a mock tool permanently. Runs already in progress keep answering the world they froze at start, so deleting a mock tool never affects an active run.

Delete a mock tool when you want to stop intercepting a tool call entirely. Editing it to return a benign value is the right move when you want to keep the interception but change the answer.

### Path parameters

<ParamField path="mockToolId" type="string" required>
  The `mck_…` identifier of the mock tool to delete.
</ParamField>

### Response fields

<ResponseField name="id" type="string">
  The identifier of the deleted mock tool.
</ResponseField>

<ResponseField name="tool" type="string">
  The tool name that was intercepted.
</ResponseField>

<ResponseField name="deleted_at" type="string">
  ISO 8601 timestamp of when the deletion was processed.
</ResponseField>

### Example

```bash theme={null}
curl -X DELETE "https://your-egma-host/api/mock-tools/mck_01abc" \
  -H "Authorization: Bearer <api-key>"
```

***

## List mock tools

`GET /api/mock-tools`

Return a paginated list of project-level mock tools your credential can reach, ordered newest first.

### Query parameters

<ParamField query="project" type="string">
  Filter to a specific project by id or name.
</ParamField>

<ParamField query="cursor" type="string">
  The `next_cursor` value from the previous page. Omit to start from the newest mock tool.
</ParamField>

### Response fields

<ResponseField name="items" type="array">
  Array of mock tool objects. Each has the same shape as the create response.
</ResponseField>

<ResponseField name="next_cursor" type="string | null">
  Pass as `?cursor` to fetch the next page. `null` means you are on the last page.
</ResponseField>

### Example

```bash theme={null}
curl "https://your-egma-host/api/mock-tools?project=my-project" \
  -H "Authorization: Bearer <api-key>"
```