---
title: "Mock a tool call during a test call"
method: POST
path: "/v1/simulation/tool-mock"
tags: ["Simulation"]
---

# Mock a tool call during a test call

`POST /v1/simulation/tool-mock`

## Request

- Base URL: `https://api.roark.ai`
- URL: `https://api.roark.ai/v1/simulation/tool-mock`
- Auth: HTTP bearer

The server half of the tool guard for code-first agents. When a guarded tool fires during a Roark test call, send the invocation here instead of executing it: Roark answers with a simulated backend response that is valid JSON, shaped by the tool contract you pass, consistent with the test scenario, and consistent with earlier mocked responses in the same call. Real callers are never affected: the guard only diverts when the agent-config resolve response identified the session as a Roark simulation, and this endpoint independently re-validates the simulation before answering.

Failure contract for your wrapper: `404` means the simulation id is unknown to this project (treat the session as real). `409` means the simulation has already ended (stale session state: do NOT execute the real tool; return your static fallback). `5xx` means generation failed (return your static fallback).

Identical retries (same tool, same arguments) within a few minutes return the stored response, so double-fired handlers stay consistent.

## Request body

- SimulationToolMockRequest
  - `simulationJobId` string, uuid, required: The simulation this session belongs to, from the agent-config resolve response (`simulationJobId`). Roark re-validates it against the live simulation before answering.
  - `sessionId` string: Your session or room identifier, echoed back in logs for correlation.
  - `toolName` string, required: The tool the agent invoked.
  - `toolDescription` string: The tool's contract: its description and, ideally, its parameter and return shape. The more contract you pass, the more faithful the simulated response.
  - `arguments` object: The arguments the agent called the tool with, verbatim.

## Response `200`

The simulated tool response. Return `result` from your tool.

- object
  - `data` SimulationToolMockResponse, required: A simulated backend response for a guarded tool during a Roark test call. The real tool was not, and must not be, executed.
    - `simulationJobId` string, uuid, required
    - `toolName` string, required
    - `result` unknown
    - `source` 'GENERATED' | 'FIXTURE', required: GENERATED = the scenario-aware model answered; FIXTURE = a pinned deterministic response you configured answered.
    - `reused` boolean, required: True when this exact invocation (same tool, same arguments) was answered moments ago and the stored response was returned, e.g. on a retry.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: No simulation with this id is known to this project.
- `409`: The simulation has ended. Do not execute the real tool; use your static fallback.
- `429`: Too Many Requests
- `500`: Internal Server Error

## Changes

> 188 revisions in range; 1 not diffed.

- **2026-09-23** `1ecd4d7c5fe7`: 1 info
  - added the required property `data/source` to the response with the `200` status
- **2026-09-23** `db1bd5df30cc`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/roarkhq/apis/roark-analytics-api/changes/v1/simulation/tool-mock/post.md)

---

[API](https://skmtc.dev/roarkhq/apis/roark-analytics-api.md) - [All operations](https://skmtc.dev/roarkhq/apis/roark-analytics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/roarkhq/apis/roark-analytics-api/revisions/1a91a5c90e44?raw)