> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ada.cx/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server. # Mock API tools Mock an API tool to test every path through a flow, not only the paths your test data supports. You describe the records and rules in the **External systems** field of the test case, and the simulation answers the API tool from that text. You don't need test accounts that you set up and reset between runs. Test edge cases, such as a refused refund or a system that is down, and find the Playbook branch that breaks. The simulation also uses the API tool's **API traffic profile**, a summary of how your API usually answers. The profile is built every week from the API tool's real calls over the last 30 days. ## Overview Without a mock, a simulation tests only what your real systems hold. Each path needs a test account with the right data, and that data changes after every run. A mocked API tool removes this limit. Each test case brings its own records, so you can write one test case for each branch of a Playbook. This opens the improvement loop to flows that use API tools. Find a gap, stage a fix in a change set, and test the fix against every case as often as you need. Every run gets the same answers, so a failed run points at the AI Agent, not at test data that changed. A test against your real API is still the most complete test. Mock the API tools you can't test for real. ## Limitations * **Your text holds the records.** The API traffic profile gives the shape of an answer, never a record. Every record the flow reads must be in the External systems text. A new API tool with no real calls yet has no profile, so its answers come from your text alone. * **Ada's own utilities always run for real.** An API tool that calls one of Ada's utilities, such as one that returns today's date, always gives a real answer. That holds even when it is set to Mock. * **Only API tools have a mock.** Code tools and MCP tools send real requests, and so do HTTP Request blocks in a voice simulation. You can block them instead. See [Code tools, MCP tools, and HTTP Request blocks](#code-tools-mcp-tools-and-http-request-blocks). * **Voice simulations place a real call.** Mock API tools work in voice simulations too. A voice simulation places a real call, and its HTTP Request blocks send real requests. See [Voice simulations](/docs/optimization/testing/simulations#voice-simulations). ## Use cases Mock an API tool for these flows: * **A flow that changes data**: a refund, a cancellation, an address change. * **A path you can't trigger for real**: a refund the system refuses, an order the warehouse has already packed, a system that is down. * **A repeat run**: the same records on every run, so a failed outcome points at the Agent. * **A change set preview**: an API tool that a change set creates is mocked in that change set's previews. You can test it before you promote it. ## Capabilities & configuration ### How a mocked call is answered Every API tool is **Live** by default. A Live API tool sends a real request in a simulation, as in production. To mock an API tool, open it on the **Tools** page and select **Mock in simulations**. To set several API tools at once, select them on the **Tools** page and click **Set simulation mode**. > **Warning** > > A simulation sends real requests by default. Every API tool is Live, code tools and MCP tools run for real, and so do HTTP Request blocks on voice. Before you simulate a flow that changes data, set its API tools to Mock and block the other tools it uses. ![The Simulations section of an API tool, with Mock in simulations selected](/_fern-img/9897499d4276bc9f2b57e4503a79fcb8cbf960bfc911a6752a66cba223fff4f2.webp) A mocked call is answered from two sources: 1. **The External systems field of the test case.** The records and the rules for this test: which orders or accounts exist, their values, and what happens when the Agent acts. 2. **The API tool's API traffic profile.** The shape of a real answer: the fields, their types, common values, and the status codes your API returns. Personal data is removed before the profile is stored. An output is hidden from the Agent when its **Give my AI Agent access to this information** toggle is off. For a hidden output, the profile keeps only the type, never a value. ```mermaid flowchart LR A[Agent calls a mocked API tool] --> M[Simulation] E[External systems text: records and rules] --> M P[API traffic profile: shape of real answers] --> M M --> R[Answer in the shape the API tool expects] ``` A call that neither source describes stops the run. See [What the simulation flags](#what-the-simulation-flags). A change set preview uses the setting staged in the change set, or the API tool's current setting. An API tool that a change set creates is mocked in its previews, and it stays mocked after you promote it. Clear **Mock in simulations** on the API tool to send real requests. ### Code tools, MCP tools, and HTTP Request blocks These have no mock. A simulation runs them for real: * **Code tool**: the code tool runs, and its requests reach your system. * **MCP tool**: the simulation calls the tool on the real server. One exception: an MCP tool that a Playbook step runs is not called. The step continues as if the call succeeded. * **HTTP Request block**: depends on the channel. See below. To stop a code tool, an MCP tool, or an HTTP Request block, select **Block in simulations** on it. A blocked call sends nothing, and the run fails at that call. On the **Tools** page, **Set simulation mode** sets several tools at once. ![The Simulations section of a code tool, with Block in simulations selected](/_fern-img/537f1b28fc38e0aa4a0fb7d0c6e4db1f94219cb50bfa011cddb70b80f07e9c71.webp) What else a simulation sends depends on the channel. #### Web Chat and Email simulations * The greeting is not played. The simulated end user sends the first message. * HTTP Request blocks never send a request, whatever their setting. * A handoff ends the simulation. It does not reach your agents or create a ticket. * None of your webhooks are sent, and nothing is written to Zendesk Messaging. #### Voice simulations * A voice simulation places a real call, so the greeting plays. * An HTTP Request block sends a real request, unless it is set to **Block in simulations**. A blocked request fails the run at that block. * A handoff transfers the call to your agents, as on a real call. * Your webhooks are sent, as on a real call. Nothing is written to Zendesk Messaging. ## Implementation & usage ### Write the External systems field Start from a journey, not from fields. One test case follows one end user down one path. *Check that the refund Playbook works* is not a test. *An end user who bought glasses five days ago asks for a refund* is. Write the happy path first, then one test case for each place the flow can say no. Three fields set up the conversation. Each holds a different kind of fact: | Field | What goes in it | Example | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | **Variables** | What the Agent knows before the first message, such as a signed-in end user's email. | `email = dana.whitfield@example.com` | | **Scenario** | What the end user knows and says. An order number the end user must give goes here, because the simulated end user reads only the Scenario. | *When asked, the order number is 4471.* | | **External systems** | What your systems return: the records, every value the API tool returns, the rules, and what a repeat call does. | *Order 4471 was placed on 2026-10-15 for 84.20 USD. A second refund for it is refused.* | ![The External systems field of a test case, with the refund example](/_fern-img/2ab0ca9e182f99309252963394677fe420bd6db44706aca82f3bc157563634bf.webp) Write the story of this end user as your systems see it, in plain sentences, one fact per sentence. Don't write field names or status codes. The simulation knows your API tools and turns your facts into their answers. Cover these points: * **The records.** Which orders or accounts exist, the numbers the Agent uses to find them, and every value the API tool returns, hidden outputs included. The mock fills a hidden output too. It goes to its variable, and the Playbook reads it there. A value you leave out comes back empty. * **The rules.** What happens when the Agent acts, and what a repeat does: *a refund goes through. A second refund is refused because the first was already processed.* * **Refusals and outages.** Write a refusal as an answer with its reason: *the cancel call answers that the order was already sent to the warehouse.* An outage is a fact too: *the billing system is down.* **Set the variable, or describe the lookup, not both.** A Playbook often skips a lookup when its variable already has a value. To test the lookup, leave the variable empty and describe the record in External systems. To test only what comes after the lookup, set the variable. Write expected outcomes about the Agent, never about your systems. The simulation answers from your text, so an outcome about a system is always true. #### Example: a refund that goes through The happy path of a refund flow at Acme Optical, a fictional store that sells glasses. **Customer inquiry:** *I ordered glasses last week but my plans changed. Can I get a refund?* **Scenario:** *You are Dana Whitfield, an Acme Optical customer. You bought a pair of glasses five days ago and your plans changed, so you want a refund. When asked, your email is [dana.whitfield@example.com](mailto:dana.whitfield@example.com) and your order number is 4471. If the Agent explains the refund and asks you to confirm, say yes. Accept the outcome the Agent reports and end the conversation.* **Variables:** none. The order lookup is under test, so the email is not preset. **External systems:** *Dana Whitfield has one account, under [dana.whitfield@example.com](mailto:dana.whitfield@example.com). She has one order, 4471, placed on 2026-10-15 for 84.20 USD: one pair of Harbor frames with single-vision lenses, delivered on 2026-10-18. The order is inside the 30-day return window, so a refund for it goes through: 84.20 USD returns to the original payment method, and the order shows as refunded. A second refund request for order 4471 is refused because it was already refunded.* **Expected outcomes:** 1. The Agent looks up the order before it says anything about refund eligibility. 2. Before it processes the refund, the Agent asks the end user to confirm. 3. The Agent processes the refund only after the end user confirms. 4. The Agent tells the end user that "84.20 USD" is refunded to the original payment method. #### Example: a cancellation the system refuses What the Agent says when the system refuses. The refusal carries its reason, so the Agent can relay it. **Customer inquiry:** *I need to cancel the sunglasses I ordered yesterday.* **Scenario:** *You are Dana Whitfield, an Acme Optical customer. You ordered sunglasses yesterday and want to cancel that order. When asked, your email is [dana.whitfield@example.com](mailto:dana.whitfield@example.com). If the Agent shows your orders, pick the sunglasses. If the Agent says it can't cancel the order, accept it. If the Agent offers to connect you with support, say yes and end the conversation.* **Variables:** none. **External systems:** *Dana Whitfield has one account, under [dana.whitfield@example.com](mailto:dana.whitfield@example.com), with exactly two orders. Order 4472 was placed on 2026-10-19 for 129.00 USD: one pair of Coastal sunglasses, status processing, not shipped. Every order lookup shows it as cancelable. Order 4471 was placed on 2026-10-15 for 84.20 USD: one pair of Harbor frames, delivered on 2026-10-18, not cancelable. Any attempt to cancel order 4472 is refused because the warehouse has started packing it. The cancel call answers with the message "Order 4472 has already been sent to the warehouse and can no longer be canceled." Nothing changes: the order stays processing, and no refund is issued. A retry gets the same refusal.* **Expected outcomes:** 1. Before it attempts the cancellation, the Agent shows the end user their orders and confirms which one to cancel. 2. After the refusal, the Agent tells the end user that order "4472" could not be canceled because it was already sent to the warehouse. 3. The Agent never says or implies that the order was canceled or that a refund is on its way. 4. The Agent offers a next step, such as the support team. ### Read the results In the transcript, each API tool call shows a **Mocked** or **Live** badge. A blocked call shows no badge. Click the call to open **API tool details**. **Inputs** shows what the Agent sent. **Outputs** shows the answer. A hidden output doesn't appear under Outputs, even though the mock filled it. Find its value in the **Variable updated** row above the call. An empty output means your text left it out. Add the fact and run again. ![A mocked API tool call in a simulation transcript, next to the API tool details panel with its inputs and outputs](/_fern-img/9b0dc23ea8cc3d37b9f326a5c07a292d3435b88f311d87309c831454b87ff128.webp) When an expected outcome fails, work out which of these it is: 1. **The Agent got it wrong.** Your systems answered as you described, and the Agent still did the wrong thing. This is what the mock is for. 2. **The outcome is stricter than you meant.** The evaluation reads outcomes literally. *The last message says X* fails when X was in the message before. Reword it and run again. 3. **Your text left something out.** The Agent acts as if a record is missing or a value is blank. Open the call, check its outputs, add the fact, and run again. 4. **The simulated end user went off script.** This is rare. Read the conversation before you change anything else. ### What the simulation flags When the simulation can't answer a call, the run shows **Run not graded** with the reason: * An API tool call that neither your text nor the API traffic profile describes. A blocked code tool, MCP tool, or HTTP Request block shows this reason too. * A request that the API tool's own definition doesn't allow. * A Live API tool that got no response. * A call to one of Ada's utilities that did not complete. * A step the simulation couldn't finish. Run the test again. An empty output doesn't stop the run. Open the call in the transcript to see which outputs came back empty. ## Best practices * **Start small, run, read, add.** Write the story you have in mind and run it. The first run often fails. Open the run, see which value came back empty or which outcome failed, fix that one thing, and run again. Two or three rounds is normal. * **Check for the mistakes the simulation doesn't flag.** When a run fails and the reason doesn't explain it, look for: * External systems text that contradicts the Scenario or the Variables. * An identifier that appears only in External systems. The simulated end user can't give it. * Values that conflict between sentences. * Facts about the end user in External systems, or facts about your systems in the Scenario. * A variable that makes the Playbook skip the lookup you meant to test. * External systems text on a test case whose API tools are all Live. The text is not used. For Scenario and expected outcome guidance, see [Best practices](/docs/optimization/testing/simulations/best-practices). ## Related features * **[Simulations](/docs/optimization/testing/simulations)**: create test cases, run them, and review the results. * **[Simulations best practices](/docs/optimization/testing/simulations/best-practices)**: write Scenarios and expected outcomes that produce evaluable runs. * **[API tools](/docs/automation/tools/api-tools/api-tool-control)**: the **Mock in simulations** setting on each API tool. * **[Code tools](/docs/automation/tools/code-tools)**, **[MCP tools](/docs/automation/tools/mcp-tools)**, and **[HTTP Request blocks](/docs/automation/greetings/blocks/request-block)**: the **Block in simulations** setting. --- Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).