> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cekura.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Mock Tools
> Learn how to create and manage mock tools for testing AI agents with predictable tool responses
export const CopyPageButton = () => {
if (typeof window !== 'undefined') {
setTimeout(function () {
if (document.getElementById('ck-tools')) return;
var anchor = document.getElementById('content-area') || document.querySelector('.mdx-content');
if (!anchor) return;
if (!document.getElementById('ck-style')) {
var s = document.createElement('style');
s.id = 'ck-style';
s.textContent = '#ck-tools{position:absolute;top:6px;right:0;z-index:100;font-family:inherit;}' + '.ck-row{display:inline-flex;align-items:stretch;border:1px solid rgba(0,0,0,0.15);border-radius:8px;overflow:hidden;background:#fff;}' + ':root.dark .ck-row{background:rgba(255,255,255,0.06);border-color:rgba(255,255,255,0.12);}' + '.ck-btn{padding:5px 12px;border:none;background:none;cursor:pointer;font-size:13px;font-weight:500;font-family:inherit;color:#374151;}' + ':root.dark .ck-btn{color:#d1d5db;}' + '.ck-btn:hover{background:rgba(0,0,0,0.04);}' + ':root.dark .ck-btn:hover{background:rgba(255,255,255,0.06);}' + '.ck-chevron{padding:5px 8px;border:none;background:none;cursor:pointer;font-size:14px;font-family:inherit;color:#374151;}' + ':root.dark .ck-chevron{color:#d1d5db;}' + '.ck-chevron:hover{background:rgba(0,0,0,0.04);}' + ':root.dark .ck-chevron:hover{background:rgba(255,255,255,0.06);}' + '.ck-divider{width:1px;background:rgba(0,0,0,0.12);flex-shrink:0;}' + ':root.dark .ck-divider{background:rgba(255,255,255,0.12);}' + '.ck-dd{position:absolute;top:calc(100% + 4px);right:0;min-width:180px;background:#fff;border:1px solid rgba(0,0,0,0.12);border-radius:8px;box-shadow:0 4px 12px rgba(0,0,0,0.1);padding:4px;display:none;z-index:200;}' + ':root.dark .ck-dd{background:#1f2937;border-color:rgba(255,255,255,0.1);box-shadow:0 4px 16px rgba(0,0,0,0.35);}' + '.ck-item{display:block;width:100%;padding:7px 12px;border:none;background:none;border-radius:6px;cursor:pointer;font-size:13px;font-family:inherit;text-align:left;color:#374151;}' + ':root.dark .ck-item{color:#d1d5db;}' + '.ck-item:hover{background:rgba(0,0,0,0.05);}' + ':root.dark .ck-item:hover{background:rgba(255,255,255,0.07);}';
document.head.appendChild(s);
}
var wrap = document.createElement('div');
wrap.id = 'ck-tools';
var row = document.createElement('div');
row.className = 'ck-row';
var mainBtn = document.createElement('button');
mainBtn.className = 'ck-btn';
mainBtn.textContent = 'Copy page';
var divider = document.createElement('span');
divider.className = 'ck-divider';
var chevron = document.createElement('button');
chevron.className = 'ck-chevron';
chevron.textContent = '▾';
var dd = document.createElement('div');
dd.className = 'ck-dd';
function closeDD() {
dd.style.display = 'none';
}
function openDD() {
dd.style.display = 'block';
}
chevron.onclick = function (e) {
e.stopPropagation();
if (dd.style.display === 'block') {
closeDD();
} else {
openDD();
}
};
document.addEventListener('click', function (e) {
if (!e.target.closest('#ck-tools')) {
closeDD();
}
});
document.addEventListener('keydown', function (e) {
if (e.key === 'Escape') {
closeDD();
}
});
function makeItem(label, fn) {
var b = document.createElement('button');
b.className = 'ck-item';
b.textContent = label;
b.onclick = function () {
fn();
closeDD();
};
return b;
}
function getMarkdown() {
var walk = function (node) {
if (!node) return '';
if (node.nodeType === 3) return node.textContent || '';
if (node.nodeType !== 1) return '';
var tag = node.tagName.toLowerCase();
var skip = ['script', 'style', 'svg', 'noscript', 'button', 'iframe'];
if (skip.indexOf(tag) !== -1) return '';
if (node.id === 'ck-tools') return '';
var ch = Array.from(node.childNodes).map(walk).join('');
if (tag === 'h1') return '\n# ' + ch.trim() + '\n\n';
if (tag === 'h2') return '\n## ' + ch.trim() + '\n\n';
if (tag === 'h3') return '\n### ' + ch.trim() + '\n\n';
if (tag === 'p') return '\n' + ch.trim() + '\n\n';
if (tag === 'pre') return '\n```\n' + node.textContent.trim() + '\n```\n\n';
if (tag === 'li') return '- ' + ch.trim() + '\n';
if (tag === 'code') return '`' + ch.trim() + '`';
return ch;
};
var content = document.querySelector('.mdx-content') || document.getElementById('content-area') || document.body;
return walk(content).replace(/\n\n\n+/g, '\n\n').trim();
}
function copyMd() {
var md = getMarkdown();
navigator.clipboard.writeText(md).then(function () {
mainBtn.textContent = 'Copied!';
setTimeout(function () {
mainBtn.textContent = 'Copy page';
}, 2000);
});
}
function viewMd() {
var md = getMarkdown();
var safe = md.split('&').join('&').split('<').join('<').split('>').join('>');
var html = '' + safe + '';
window.open(URL.createObjectURL(new Blob([html], {
type: 'text/html'
})), '_blank');
}
function openClaude() {
var prompt = 'Can you read this Cekura docs page ' + window.location.href + ' so I can ask you questions?';
window.open('https://claude.ai/new?q=' + encodeURIComponent(prompt), '_blank');
}
mainBtn.onclick = copyMd;
dd.appendChild(makeItem('Copy page', copyMd));
dd.appendChild(makeItem('View as Markdown', viewMd));
dd.appendChild(makeItem('Open in Claude', openClaude));
row.appendChild(mainBtn);
row.appendChild(divider);
row.appendChild(chevron);
wrap.appendChild(row);
wrap.appendChild(dd);
anchor.style.position = 'relative';
anchor.insertBefore(wrap, anchor.firstChild);
}, 50);
}
return null;
};
## Overview
Mock tools allow you to simulate external tool calls during agent testing by providing predefined input-output mappings. This ensures consistent, predictable responses during testing scenarios, making it easier to evaluate your agent's performance and behavior.
Mock tools are particularly useful when:
* Testing agents that rely on external APIs or databases
* Creating reproducible test scenarios
* Avoiding dependencies on live third-party services
* Testing edge cases with specific response data
* Ensuring consistent test results across multiple runs
## How to Attach Mock Tool Data to Your Agent
There are two ways to set up mock tools for your agent:
1. **Auto-Fetch (Recommended)**: Automatically fetch tool configurations and generate mock data from your provider
2. **Manual Setup**: Manually add tool configurations and mock data
### Option 1: Auto-Fetch Tools (Recommended)
Auto-fetch reads your tool configurations from your provider (VAPI, Retell, or ElevenLabs) and uses AI to generate realistic sample input/output data based on your agent's context and recent call transcripts.
Auto-fetch is a **read-only** operation — it fetches tool definitions and populates mock data, but does not change any URLs or settings on your provider. Use the **Mock Enable/Disable toggle** (described below) to redirect your provider's tools to Cekura's mock endpoints.
**Prerequisites:**
* Your agent must have a provider configured (VAPI, Retell, or ElevenLabs)
* You must have entered an Assistant ID in your agent's provider settings
**To use Auto-Fetch:**
1. **Configure Your Provider Settings**
* Go to the Cekura Dashboard and select your agent
* In the agent settings, configure your provider (VAPI, Retell, or ElevenLabs)
* Enter your Assistant ID (or Squad ID for VAPI squads) in the provider settings
2. **Open Mock Tools Section**
* Scroll to the right-hand panel of the agent settings page
* Click on **Mock Tools** to expand the section
3. **Click Auto-Fetch**
* Click the **"Auto-Fetch"** button
* A confirmation dialog will appear explaining what will happen
* Click **"Auto-Fetch"** to confirm
4. **What Happens:**
* Cekura fetches all tool configurations from your provider
* AI generates realistic sample input/output data based on your agent's context and recent call transcripts
* The generated mock data is saved to your agent in Cekura — your provider's configuration is not changed at this point
Auto-fetch supports VAPI (including squads), Retell, and ElevenLabs providers. For VAPI squads, tools from all member assistants are fetched and prefixed with the assistant name to avoid naming conflicts (e.g., `SalesAssistant_check_availability`).
**LiveKit**: Auto-fetch is not supported for LiveKit. To use mock tools with LiveKit, you can manually create mock tools and integrate the Cekura SDK in your LiveKit agent. See the [LiveKit Tracing guide](/documentation/integrations/livekit/tracing) for setup instructions.
#### Viewing Generated Mock Tool Data
When Auto-Fetch generates mock data for scenarios whose agent has mock tools attached, the expected mock tool calls are stored on each scenario as `generated_mock_tool_entries`. This data includes:
* **Tool ID**: The identifier for the mock tool
* **Tool Name**: The name of the tool being mocked
* **Expected Input**: The input parameters the tool expects
* **Expected Output**: The response the tool will return
You can view this data in two ways:
1. **Via the Evaluator UI**: When viewing a scenario in the Cekura dashboard, the generated mock tool entries are displayed so you can see what tool calls the evaluator will make during testing
2. **Via the API**: Retrieve a scenario using the scenarios retrieve endpoint to access the `generated_mock_tool_entries` field programmatically
This visibility helps you understand exactly what mock tool interactions will occur during each test run, making it easier to debug and validate your agent's tool-calling behavior.
#### Enabling and Disabling Mock Mode
After running Auto-Fetch, use the **Mock** toggle to control whether your provider's tools are redirected to Cekura's mock endpoints.
**Mock toggle is disabled by default** — your provider's tools continue using their original URLs until you explicitly enable it.
**To enable mock mode:**
1. In the Mock Tools section, flip the **Mock** toggle to enabled
2. A confirmation dialog will describe what will change
3. Confirm to activate — Cekura will update your provider's tool configuration:
* **VAPI**: Creates cloned tools with Cekura mock URLs (original tools are preserved since VAPI tools are shared globally)
* **Retell**: Updates tool URLs directly in your LLM/Flow configuration
* **ElevenLabs**: Updates webhook tool URLs directly in your agent configuration
**To disable mock mode:**
1. Flip the **Mock** toggle back to disabled
2. Confirm the dialog — Cekura will restore your provider's original tool configuration:
* **VAPI**: Deletes the cloned mock tools
* **Retell/ElevenLabs**: Restores the original tool URLs
When mock mode is disabled, your provider's tools revert to their original endpoints. Run Auto-Fetch again if you need to refresh the mock data, then re-enable the toggle.
### Option 2: Manual Setup
If you prefer to manually configure your mock tools, or need more control over the mock data, you can add tools manually.
**Provide Agent tool details with mock tool data:**
1. **Navigate to Agent Settings**
* Go to the Cekura Dashboard
* Select the agent for which you want to add mock tools
2. **Add Mock Tool Data**
* On the right-hand panel, click on **Mock Tools**
* Click **"+ Add Tool"** button to add mock tool data
* For each tool you need to add:
* **Tool Name**: Must be the same as mentioned in the agent description
* **Tool Description**: Describe what the tool does
* **Input/Output Mock Data**: Provide sample data to define the format for keys and values (this also serves as initial test data)
The tool name must exactly match what's mentioned in your agent description. Any mismatch will result in the mock tool not being triggered during testing.
#### Example Mock Tool Configurations
```json User Data Tool theme={null}
[
{
"input": {"user_id": 1},
"output": {
"name": "John Doe",
"age": 30,
"email": "john@example.com",
"status": "active"
}
},
{
"input": {"user_id": 2},
"output": {
"name": "Jane Smith",
"age": 25,
"email": "jane@example.com",
"status": "premium"
}
}
]
```
```json Inventory Check Tool theme={null}
[
{
"input": {"product_id": "SKU123", "quantity": 5},
"output": {
"available": true,
"in_stock": 50,
"can_fulfill": true,
"estimated_delivery": "2-3 business days"
}
},
{
"input": {"product_id": "SKU456", "quantity": 100},
"output": {
"available": false,
"in_stock": 10,
"can_fulfill": false,
"message": "Insufficient stock"
}
}
]
```
```json Weather API Tool theme={null}
[
{
"input": {"city": "New York", "unit": "celsius"},
"output": {
"temperature": 22,
"conditions": "partly cloudy",
"humidity": 65,
"wind_speed": 10
}
},
{
"input": {"city": "London", "unit": "celsius"},
"output": {
"temperature": 15,
"conditions": "rainy",
"humidity": 80,
"wind_speed": 15
}
}
]
```
### Step 2: Create New Evaluators
After setting up your mock tools, create evaluators to test your agent:
1. **Navigate to Evaluators Section**
* Go to the Evaluators tab in your Cekura dashboard
* Click on **"Create New Workflow Evaluator"**
### Step 3: Run the Evaluators
Execute your evaluators to test the agent with mock tools:
1. **Enable Mock Mode**
* If you used Auto-Fetch: make sure the **Mock** toggle is enabled so your provider's tools are redirected to Cekura's mock endpoints
* If you used Manual Setup: configure your agent with Cekura's mock tool endpoints instead of the actual tool URLs on your provider. Each tool's endpoint URL is shown in the dashboard and returned as `mock_tools[].served_via.url` on the [agent](/api-reference/test_framework/get-agent)
2. **Start Test Execution**
* Select the evaluators you created
* Click **"Run Evaluator"** to start testing
* Choose the number of test iterations if needed
## Handling Dynamic Input Parameters
When a mock tool is called during a test run, Cekura selects the variation whose `input` **best matches** the actual input the agent sends — it does not require an exact match. If you define multiple variations (for example, five entries for a `make_payment` tool with `{"amount": 1}` through `{"amount": 5}`), the one whose input is closest to what the agent sends at runtime is returned automatically.
To get reliable, predictable results across a range of input values:
* **Provide multiple input-output entries.** Each variation covers a different realistic input your evaluators exercise. Use [Auto-Fetch](#option-1-auto-fetch-tools-recommended) — Cekura generates mock data from your agent's real call history, giving you coverage of the input variations that actually occur.
* **Pin dynamic values in your evaluator instructions.** If a parameter like a date or appointment slot is completely open-ended, use [Test Profiles](/documentation/key-concepts/evaluators/test-profile) to fix the value: set `{{test_profile.appointment_date}}` in your evaluator scenario, and add a corresponding mock entry for that pinned value. This keeps both the mock response and the evaluator assertion deterministic.
* **Check the tool name matches exactly.** Any casing or underscore mismatch between the tool name in your mock config and the name in your provider (Retell LLM/Flow, VAPI, ElevenLabs) will prevent the mock from firing, regardless of the input.
## Verifying Tool Calls: the Mock Tool Call Accuracy Metric
The **Mock Tool Call Accuracy** metric checks whether your agent called the expected mock tools, with the expected inputs, during a run. Understanding how it detects tool calls is important — especially for custom and self-hosted integrations.
### How the metric detects tool calls
The metric reads the **run transcript** and looks only at entries whose role is `Function Call`:
* **Called** — a `Function Call` entry with a matching tool `name` is present in the transcript.
* **Correct input** — the `arguments` on that entry match one of the tool's expected inputs. Numeric and format variations are handled, and a tool whose expected input is `{}` matches any input.
* The metric scores precision/recall across expected vs. actually-called vs. correctly-called tools (an F1-style score, 0–5). The explanation lists each tool as `called with correct input ✓`, `called but wrong input ✗`, or `not called ✗`.
Detection is **transcript-based**, not endpoint-based. A tool call that genuinely happened at runtime is still reported as **not called** if it is missing from the transcript Cekura evaluates. The mock endpoint returning the right data is not sufficient on its own — the function call must also appear in the transcript.
### Provider behavior
* **VAPI, Retell, ElevenLabs (managed integrations):** function-call events are reported automatically as part of the call data, so `Function Call` entries appear in the transcript without extra work on your side.
* **Custom / self-hosted integrations:** Cekura only knows what your webhook sends. You **must** include `function_call` (and ideally `function_call_result`) messages in the transcript you post — otherwise tool-based metrics have nothing to score against. See [Mock Tools with Custom Integration](/documentation/integrations/custom-integration#mock-tools-optional).
### Required transcript shape
Each tool call must be sent as a `function_call` message carrying the tool `name` and `arguments` in its `data` object. A tool that takes no input still needs `"arguments": {}`:
```json theme={null}
{
"role": "function_call",
"data": {
"id": "call_abc",
"name": "pre_call_lookup",
"arguments": {}
}
}
```
And, recommended, the paired result:
```json theme={null}
{
"role": "function_call_result",
"data": {
"id": "call_abc",
"name": "pre_call_lookup",
"result": { "account_id": "TEST-90210", "account_tier": "Premium" }
}
}
```
See [Transcript Format](/documentation/advanced/transcript-format) for a full transcript example including function calls.
## API Reference
For programmatic access to mock tools — they are managed directly on the agent:
* [Get Agent](/api-reference/test_framework/get-agent) — read the agent's `mock_tools` (each entry includes its mock data and runtime access URL)
* [Update Agent](/api-reference/test_framework/update-agent-partial) — create, update, or delete mock tools via the `mock_tools` field
* [Auto-Fetch Agent from Provider](/api-reference/test_framework/auto-fetch-agent) — re-fetch the agent's full configuration (including tools + mock data) from its provider
* [Toggle Mock Tools](/api-reference/test_framework/toggle-mock-tools) — enable or disable mock mode on the provider