Tool Mocks

Open in CMS

The Tool Mocks screen is where you build reusable mock sets: scripted answers for your agent's tools, so simulations run against predictable responses instead of calling real tools. Found in the agent sidebar under Simulation → Tool Mocks; this menu item appears only when the mocks feature is enabled. You attach mock sets to a scenario in the Tool Mocks section of the Scenarios form.

The page opens with the text "Script canned tool responses so your test scenarios can run against predictable answers instead of calling real tools. Build reusable mock sets here, then attach them to a scenario."

A response drafted by AI with Suggest can differ each time you ask, so treat a suggestion as a draft to check before you use it.

Library and Private Mock Sets

A mock set is either a Library set or a Private set.

LibraryA shared set. It is built on this screen, appears in its list, and can be attached to any scenario of the agent. Changing a library set changes every scenario that uses it. Every set on this screen's list is a library set. Its edit page shows a Library chip in the header, and inside a scenario's Tool Mocks section it has a book icon.
PrivateA set that belongs to one scenario. It is created from the scenario's Tool Mocks section (Create New) or from a result (Mock This Call, Save as Case), is edited in a side panel inside the scenario form and is not listed on this screen. Inside the scenario's Tool Mocks section it has a lock icon. Use Save to Library on the scenario to turn it into a library set, or Make a Private Copy to copy a library set into the scenario.

Mock Set List

New Mock SetOpens the editor for a new library mock set.
Show Filters / Hide FiltersOpens or closes the filter panel.
NameFilter: shows only mock sets whose name contains the text you type.
ToolFilter: shows only mock sets that mock the selected tool.
Apply / ResetApplies the filters, or clears them.
Sort ByOrders the list by Updated Date (default, newest first) or Name, Ascending or Descending.
Grid View / List ViewShows mock sets as cards or as a table (columns Name, Tools · cases, Used in, Updated).
Count line"n mock sets", with "(more available)" when Load More has another batch.
Mock set card or rowShows the name, description, how many tools and cases it has (for example "2 tools · 5 cases"), the tool names, and how many scenarios use it ("Used in n scenarios"). Click it to open the editor.
⋮ menuEdit, Duplicate (creates a copy and says "<copy>" created as a copy of "<set>"), Delete.
DeleteAsks "Are you sure you want to delete "<set>"?". If the set is still attached to scenarios, This mock set is in use lists where (the scenario, and "Step n" or "Scenario level"), and the confirm button, Remove from n scenarios and delete, detaches it everywhere and then deletes it.
Load MoreShown when more mock sets are available.
Empty stateNo Mock Sets Yet ("Create a mock set to script canned tool responses for your scenarios") with a New Mock Set button. When filters hide every set it says No Mock Sets Match Your Filters ("Try a different name or tool, or reset the filter.") instead.

Mock Set Editor: Header

The editor opens as New Mock Set, or with the set's name when editing. This page always edits a Library set. The editor inside a scenario's side panel works the same way, for a private set or a library set. Below the header, the editor is a stack of tool cards with one open at a time.

LibraryA chip showing that this is a library set.
Used in n scenariosEdit mode only, a link. Opens Used in, a list of the scenarios (and steps) that use this set. A set that is not attached anywhere says "This mock set isn't attached to any scenario yet."
SaveA new set: opens the Save Mock Set dialog (below). An existing set: asks "Save changes to “<set>”?", adding "It’s used in n scenarios, and all of them will get these answers." when scenarios use it, then saves ("Mock set saved successfully"). After either save, the page returns to the list. If someone else changed the set in the meantime, you are asked "Someone else changed this set. Reload?" and can Reload it.
DuplicateEdit mode only. Creates a copy of the set.
Save Mock Set dialogNew sets only. It says "We named it after its tools. Change it if you like." with a Name (required, prefilled from the tools) and a Description (optional), and the buttons Cancel and Save. The name is the tool's name for one tool, "A and B" for two and "A + n more" for more. Success reads "Mock set created successfully".
Mock Set InformationA card at the top when editing an existing set. It holds Name (required, up to 120 characters; for example "Doctor scheduling — happy path") and Description (optional, up to 1000 characters; "What this mock set is for (optional)"). A new set has no such card, and a new private set in a scenario's side panel has none either: its name comes from its tools.

In a scenario's side panel the panel is titled Create mock set or Edit mock set (or the library set's name), and the button reads Apply for a private set and Save for a library set. Editing a library set there adds a notice: "Library set, used in n scenarios. Saving changes all of them." with a Make a Private Copy Instead link when it was opened from Save as Case. While a library set loads the panel says "Loading mock set…", and if it cannot be loaded, "Failed to load this mock set. Close and try again." On a phone the editor's pop-up panels open as sheets from the bottom of the screen.

Mock Set Editor: Tool Cards

Empty stateNo Tools Mocked Yet ("Pick the tool whose answers you want to fake during a simulation.") with an Add Tool button.
Add ToolOpens a searchable list (Search tools…) of the agent's tools, grouped by source (Custom API, Plugins, MCP, Other agents, A2A, Built-in). It lists the tools of the draft and the published agent together. The button sits under the last card once the set has tools, and adding a tool opens its card and closes the others. A set can hold up to 50 tools.
Tool in the pickerShows the tool's name, its description, a chip for its effect (the HTTP method such as GET or POST, Read-only, Writes data or Unknown effect), and what happens when it is not mocked: Blocked unless mocked, Runs live unless mocked or Simulated success. That text follows the agent's Tool Policy, or the tool's built-in default when no rule covers it. A Draft only, Published only or Disabled chip (also Disabled in Draft or Disabled in Published) appears when it applies. A tool that cannot be picked shows why, for example Already in this set.
Picker messages"Loading tool catalog…", "This agent has no tools in its catalog.", "No tools match your search.", "Failed to load the tool catalog. Close and reopen Add Tool to retry." and, when one version's tools could not be loaded, "Couldn't load the draft version's tools; showing the other version's only."
Card headerThe tool's icon and name, and a second line that is the tool's description while the card is open and a summary while it is closed, such as "every call 200 OK", "1 case · otherwise 200 OK" or "2 cases · otherwise passes on". Only one card is open at a time. Click the header to open or close it.
Mode chipUnder the name, Ahead of sets below or Passes to next set when the Otherwise uses one of the non-default options (see Otherwise below).
About This Tool (ⓘ)A pop-up with the tool's name, chips for its source (for example Custom API, GET, MCP, a server name), its description and its Inputs: one line per parameter with its type ("text", "number", "yes/no", and "n options" when it has a fixed list) and an asterisk when it is required. It says "This tool takes no inputs." when there are none.
Remove (trash icon)"Remove this tool from the set": removes the tool and its cases from the set. If it has been changed, you are asked "Remove the tool "<tool>" and all of its cases from this set?"
ChevronOpens or closes the card.
Tool not found in the draft or published agentA warning on a tool that no longer exists in either version of the agent. Use Re-Bind to… to point its cases at another tool.
Not in the loaded catalog"This tool isn't in the loaded catalog — parameters can't be shown."
Tool turned off"This tool is turned off in <version>, so simulations can't call it right now. Its cases are kept and answer again as soon as the tool is enabled. You can still edit them."

Mock Set Editor: Cases

Each case is one scripted answer, used when the tool is called with matching arguments. Cases are checked in order, from the top. A new tool starts with the Every call returns block only. After a case is added, that block is titled Otherwise, every other call returns.

Add CaseAdds a case under the others for the selected tool, opens it, gives it one condition on the tool's first required input (or its first input) and an empty response. A tool can have up to 50 cases. It is greyed out for a tool that has no inputs ("This tool has no inputs a case could match on, so the Otherwise answer covers every call.") and for a tool that is not in the loaded catalog.
Try a CallOpens the Try a Call panel (see below). Not shown when the editor is read-only.
How Cases Work (?)A pop-up that says: cases are checked top to bottom and the first whose conditions all match answers; then Otherwise answers if no case matches; the order of tools does not matter; for several mock sets on one scenario, see More Options under Otherwise.
Order hintWith two or more cases: "Cases are checked from top to bottom. The first one that matches answers. Drag to reorder."
Case headerA drag handle (with two or more cases), the case number, and its label. Closed, it shows the label or "Untitled case", a summary of the conditions (with " + raw match" when there is a raw match) and, for a Custom API tool, the status. Open, you can type the label ("Label this case (optional)").
Drag to reorderThe handle at the left of the case. Cases are checked from the first to the last.
Delete caseThe trash icon. A case with content asks "Delete case n "<label>"? Its conditions and response are removed." first.
Collapse / ExpandThe arrow at the right of the case.
When all of these matchThe conditions on the tool's arguments, with the note "Conditions are combined with AND: the case answers only when every one below matches. An input without a condition matches any value." Add Condition adds one (up to 20 per case).
Add ConditionAdds a condition on the next input that has none. It is greyed out once every input has a condition; its tooltip says "Every input already has a condition. To answer another value, use “is one of” or add another case." On a phone a ? beside it opens the same text under "Add Condition is off".
No parametersA tool with no parameters says "This tool has no parameters — conditions can't be added."
Respond withWhat the tool returns for this case. See Mock Set Editor: Response below.
Advanced — Match Raw ArgumentsOptional extra match on the raw arguments (JSON), checked in addition to the conditions: "Evaluated in addition to the conditions above — this case only matches when every condition AND the raw match (if used) all hold." It opens by itself when it has text. Its Aa button chooses whether text in the raw match is compared case-sensitively.
Warnings on a case"No conditions: this case answers every call, so the cases below it and Otherwise are never used. Add a condition, or use More Options under Otherwise to answer ahead of other sets." and "This case comes after a catch-all case and can never be reached."

Mock Set Editor: Conditions

Each condition is an argument, a comparison and a value, in one row.

ArgumentOne of the tool's inputs. An input already used by another row of the case is greyed out and shows "(has a condition)". Under the row, the input's description, shortened to two lines with See more and See less.
Comparison (Text, also list, object and unknown types)is, is not, contains, starts with, ends with, matches pattern (regular expression), is one of (values separated by commas), is empty, is not empty.
Comparison (Number)=, ≠, <, ≤, >, ≥, is between (a Min and a Max, inclusive).
Comparison (Yes/no)is, followed by true or false.
ValueThe value to compare with. Shows "No value needed" for is empty and is not empty. For is one of it takes "Comma-separated values", or a multi-select when the argument has a fixed list.
Aa (Match case)Shown only for is, is not, contains, starts with, ends with, matches pattern and is one of. Off by default ("Match case (off)"), so text comparisons ignore upper and lower case. Turn it on ("Match case (on)") to compare case-sensitively.
Remove condition (×)Removes the condition. It is greyed out for the only condition of a case that has no raw match ("A case needs at least one condition. To answer every call, set the Otherwise answer instead.").
Stale conditionA highlighted row with a tooltip: ""<argument>" isn't a parameter of this tool (it may have been renamed or removed), so this condition is unlikely to match until it's fixed." For an argument the platform adds itself, ""<argument>" is an argument the platform adds itself, so this condition never matches."

On a phone the row wraps onto two lines: the input and the comparison, then the value, Aa and the delete button.

Mock Set Editor: Response

The same controls appear for a case and for the Otherwise block. The response body can be up to 64 KB. A new case starts with an empty body ("Pick a Template, ask for a Suggestion, or type the response.").

StatusCustom API only. The HTTP status code returned (default 200 OK). A 5xx code reaches the agent as an empty result, as with a real failing API.
Content / MCP errorMCP tools only. Whether the body is normal content or an MCP error.
View switchBeside Respond with. Form | JSON for tools with a form that saves JSON (table queries, document search, conversational forms, reminders, escalations), Form | Text for MCP tools, and JSON | Text for tools with no form (Custom API, plugin tools that are not classified, built-in read tools). The tool of another agent or A2A agent has no switch, because its form is the reply text. Form edits the body with fields that fit the tool's output; the other choice edits the raw body. When a response does not fit the form, it opens as JSON with a notice.
TemplateA menu of the tool's ready-made answers, grouped Success and Error, for example an empty list, Not found (404), Unauthorized (401), Rate limited (429), Invalid request (400) or Service down or timed out for a Custom API, Query fails or No rows found for a table query, No document hits for a document search, Validation errors or Failed for a form or a reminder, Reply text for another agent, Tool error or Empty text for an MCP tool. Picking one fills the response once. The button is hidden when the tool has no templates.
SuggestLets AI draft a response for this case ("AI-draft a response"), using the tool, the case's conditions and the current status, error flag and format. It opens Suggested Response with "Drafted for: <conditions>. Nothing changes until you use it." (or "Drafted from the tool’s description. Nothing changes until you use it." when the case has no conditions), a Drafting… spinner and the draft, with Try Again and Use This Suggestion. A green dot on the button says a draft is ready. The button reads "Suggesting…" while it works.
Use a Real ResponseOnly for Custom APIs that use GET and for the plugin tools that read data (SQL DB Reader, Dynamic Table, Public Documents); hidden for other tools. Opens a pop-up that says "Calls the real endpoint once (read-only GET)…" or "Runs the real query once (read-only)…" with one field per input, prefilled from the case's is conditions. Call (then Call Again) makes the call. It shows the result, the inputs it was called with, and "This call ran live and may contain real data. Using it as a mock response stores that data." For a Custom API, Use This Response copies the status and body, even an error status. For a table query, Use Columns Only keeps the column names and Use Columns and Rows keeps the data. A green dot says a result is ready.
Format"Pretty-print this JSON". Shown in the JSON and text views when the response is JSON, and disabled while the JSON has an error ("Fix the JSON to format it").

Mock Set Editor: Response Forms

When you choose Form in a response, the fields depend on the kind of tool. Values marked "(filled in automatically)" come from the call itself and cannot be typed.

Table query (SQL DB Reader, Dynamic Table)Query succeeds or Query fails. When it succeeds: one name field per column (Column n), Remove column, a grid of cell fields, Remove row, Add column and Add row (disabled until there is a column), and "No rows found." when the table has no rows. When it fails: an Error message field.
Document search (Public Documents)A list of hits, each headed Hit n with Title, Text and Section fields and a Remove hit icon, plus + Add hit. "No document hits found." when the list is empty.
Conversational formSubmitted or Validation errors, and a Message field. When submitted, the Submission ID and Processed at values are filled in automatically. For validation errors: one field per error with Remove, + Add validation error, and "No validation errors yet."
ReminderCreated or Failed, and a Message field. When created, the Reminder ID and Send time values are filled in automatically. When failed, an Error field.
EscalationEscalation ID, Topic, Area and Created are filled in automatically. You choose the Status (Pending, InProgress or Completed) and type the Response message.
Other agent or A2A agentA Reply text field: the reply the other agent sends back.
MCP toolA Content field, or an MCP error message field when MCP error is selected.
Shape noticeWhen the stored response does not fit the form: "This response doesn't match this tool's structured form, so the form below starts empty. Editing it replaces the current response — switch to JSON to keep it." In the JSON view: "This response doesn't match this tool's structured form, so it's shown as JSON."

Mock Set Editor: Otherwise

A block under the cases, titled Every call returns when the tool has no cases and Otherwise, every other call returns when it has some. It decides what happens to a call that matches no case. It opens with a response editor, the same as a case, and the call gets that response. Closed, it shows the status or a summary. More Options opens a section headed "If another mock set on the scenario also mocks this tool", where you choose one of three options. It opens by itself when the option is not the default.

Use only when no other set answersThe default. "Answers calls that no case in any attached mock set matched. If several sets answer this way, the one listed first wins. This is the usual choice."
Use ahead of sets listed below"Answers every call this tool’s cases didn’t match, before the cases of sets listed below this one and before every set’s Otherwise. Sets listed above still check their cases first."
Don’t answer; pass to the next set"Calls this tool’s cases didn’t match go to the next attached set, then to the tool’s policy." The response editor is replaced by "This set doesn’t answer calls its cases didn’t match. They go to the next attached set, then to the tool’s policy." and the response you wrote is kept for when you switch back.
Notes"A case above has no conditions and answers every call, so this is never used." appears when an earlier case would always answer. In the tool list of a scenario, a tool that passes calls on is described as "Mocked for some inputs · otherwise …".

Mock Set Editor: Try a Call

The Try a Call button sits beside Add Case. It opens a panel with the text "See which case would answer a call like this. Nothing is sent to the real tool."

Enter asFields gives one field per input of the tool, with its description shortened to two lines. JSON takes the arguments as a JSON object. Switching carries the values across. Invalid text says "These arguments aren't valid JSON", and anything that is not an object says "These arguments must be a JSON object".
TestRuns the call against the set as it stands in the editor.
Result"Matches case n: <label>", "No case matched — the Otherwise answered." (with the note "In a run, a matching case in another attached set answers first."), or "Otherwise: <outcome>" when the set passes the call on, naming what the tool's policy does ("Blocked", "Simulated success", "Live · allowed" and so on). Each case that was skipped says why ("Case n skipped: …").
Version banner"Try a call may differ from runs." when the CMS and the simulation service use different mock-matching versions.
CloseThe × at the top right of the panel.

How Several Mock Sets Answer a Call

When a scenario attaches several mock sets that mock the same tool, one call is answered in this order, and the order is the same everywhere the CMS reports it (the What the agent’s tools will do panel, the run result and Try a Call).

1. CasesEvery case of every attached set, in this order: the step's own sets from top to bottom, then the scenario's sets from top to bottom. The first case that matches answers. The order of the cases decides, not how specific they are. A case with no conditions, which is what Use ahead of sets listed below stores, matches every call.
2. OtherwiseIf no case matched, the first set, in the same order, whose Otherwise answers with a response. Sets set to Don’t answer; pass to the next set are skipped.
3. PolicyIf every set passes the call on, the scenario's Allow Live setting, the agent's Tool Policy and the tool's built-in default decide.
In a resultA Mocked call names the case and the set that answered, and Checked before the answer lists the cases that did not match, with the reason. A Default call was answered by an Otherwise. Runs from before this rule show "Answered under the previous mock rule: a set's Otherwise ended the search."
Scenario panelWhat the agent’s tools will do lists the order under Checked in this order. It crosses out a set that can never answer a tool and warns when an Otherwise is never used because another set answers every call first. A banner says "What’s shown here may differ from runs: the CMS and the simulation service are on different mock-matching versions right now." when the versions differ.

Related guide: Tool Mocks, Test Tools Safely with Mocks