> ## Documentation Index > Fetch the complete documentation index at: https://docs.roark.ai/llms.txt > Use this file to discover all available pages before exploring further. # Mock a tool call during a test call > 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. ## OpenAPI ````yaml /api-reference/openapi.documented.json post /v1/simulation/tool-mock openapi: 3.1.0 info: title: Roark Analytics API description: >- The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform. version: 1.0.0 servers: - description: Production url: https://api.roark.ai security: - Bearer: [] tags: - name: Agent - name: Agent Endpoint - name: Call - name: Chat - name: Metric - name: Metric Policy - name: Metric Collection Job - name: Customer Flow - name: Customer Flow Edge Case - name: Simulation - name: Simulation Persona - name: Simulation Environment - name: Simulation Scenario - name: Simulation Run Plan - name: Simulation Template - name: Simulation Run Plan Job - name: Simulation Job - name: HTTP Request Definition - name: Webhook - name: Issue - name: Autoimprove - name: Agent Config - name: Knowledge Base - name: Config - name: CLI Auth - name: Call Analysis - name: Benchmark - name: Health paths: /v1/simulation/tool-mock: post: tags: - Simulation summary: Mock a tool call during a test call description: >- 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. operationId: postV1SimulationTool-mock requestBody: content: application/json: schema: $ref: '#/components/schemas/SimulationToolMockRequest' responses: '200': description: The simulated tool response. Return `result` from your tool. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/SimulationToolMockResponse' required: - data '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Validation error example: type: validation code: invalid_parameter message: The request was invalid param: email description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication error example: type: authentication code: unauthorized message: Authentication required description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Permission error example: type: forbidden code: permission_denied message: You do not have permission to access this resource description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not found error example: type: not_found code: resource_not_found message: The requested resource could not be found description: No simulation with this id is known to this project. '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Conflict error example: type: conflict code: resource_in_use message: The resource is in use and cannot be deleted description: >- The simulation has ended. Do not execute the real tool; use your static fallback. '429': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Rate limit error example: type: rate_limit code: too_many_requests message: Rate limit exceeded description: Too Many Requests '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Server error example: type: internal code: internal_error message: Internal server error description: Internal Server Error x-codeSamples: - lang: JavaScript source: |- import Roark from '@roarkanalytics/sdk'; const client = new Roark({ bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted }); const response = await client.simulation.mockTool({ simulationJobId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', toolName: 'book_appointment', }); console.log(response.data); - lang: Python source: |- import os from roark_analytics import Roark client = Roark( bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"), # This is the default and can be omitted ) response = client.simulation.mock_tool( simulation_job_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", tool_name="book_appointment", ) print(response.data) components: schemas: SimulationToolMockRequest: type: object properties: simulationJobId: type: string format: uuid description: >- The simulation this session belongs to, from the agent-config resolve response (`simulationJobId`). Roark re-validates it against the live simulation before answering. sessionId: type: string maxLength: 256 description: >- Your session or room identifier, echoed back in logs for correlation. toolName: type: string minLength: 1 maxLength: 200 description: The tool the agent invoked. example: book_appointment toolDescription: type: string maxLength: 4000 description: >- The tool's contract: its description and, ideally, its parameter and return shape. The more contract you pass, the more faithful the simulated response. example: >- Books an appointment. Args: date (YYYY-MM-DD), time (HH:MM). Returns {confirmationId, status}. arguments: type: object additionalProperties: {} description: The arguments the agent called the tool with, verbatim. example: date: '2026-10-01' time: '15:00' required: - simulationJobId - toolName SimulationToolMockResponse: type: object properties: simulationJobId: type: string format: uuid toolName: type: string result: description: >- The simulated tool response: valid JSON, shaped by the tool contract, consistent with the test scenario and with earlier mocked responses in the same call. Return this from your tool instead of executing it. reused: type: boolean description: >- True when this exact invocation (same tool, same arguments) was answered moments ago and the stored response was returned, e.g. on a retry. required: - simulationJobId - toolName - reused description: >- A simulated backend response for a guarded tool during a Roark test call. The real tool was not, and must not be, executed. ErrorResponse: type: object properties: type: type: string enum: - validation - authentication - forbidden - not_found - conflict - payment_required - rate_limit - internal description: The error type category examples: - validation - authentication code: type: string description: Machine-readable error code identifier examples: - invalid_parameter - missing_required_field - unauthorized message: type: string description: Human-readable error message examples: - The request was invalid - Authentication required param: type: string description: The parameter that caused the error (if applicable) examples: - email - user_id details: description: Additional error context information required: - type - code - message securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ````