Create a mock tool
POST /api/mock-tools
Create a new project-level mock tool. Returns 201 Created with the full mock tool object. If a mock tool for the same tool name already exists in the project, Egma returns 409 Conflict.
Request body
string
required
The tool name to intercept, e.g.
check_availability. Must match exactly what your agent calls.any
The value to return when the agent calls this tool. Provide either
answer or error, not both. null is a valid answer value.string
An error string to return instead of an answer. Provide either
answer or error, not both.integer
How long Egma holds the answer back, in milliseconds. Use this to test your agent’s behavior when a tool call is slow.
string[]
Restrict this mock tool to specific agents, by name or
agt_… identifier. Omit (or supply an empty array) to apply to every agent in the project.string
Project to create the mock tool in. Defaults to the project your API key belongs to.
Response fields
string
Unique mock tool identifier (
mck_…).string
The tool name this mock tool answers for.
any
The configured answer value. Present only when the mock tool answers with a value (not an error).
string
The configured error string. Present only when the mock tool answers with an error.
integer
Configured delay in milliseconds.
0 means no delay.object[]
The agents this mock tool is scoped to. Empty array means it applies to all agents.
string
ISO 8601 timestamp.
string
ISO 8601 timestamp.
Example — answer with a value
Example — answer with an error and a delay
Update a mock tool
PATCH /api/mock-tools/:mockToolId
Update one or more fields of an existing mock tool. Fields you omit are kept as-is. There is no version check here — edits overwrite in place and take effect immediately for future runs.
Sending an explicit agents: [] sets the mock tool back to applying to all agents. Omitting agents entirely leaves the current scope unchanged.
Path parameters
string
required
The
mck_… identifier of the mock tool to update.Request body
string
New tool name.
any
New answer value. To switch from an error answer to a value answer, supply
answer in the body.string
New error string. To switch from a value answer to an error answer, supply
error in the body.integer
New delay in milliseconds.
string[]
Replacement agent scope list. An empty array means apply to all agents.
Response fields
Same shape as the create response: the full mock tool object after the update.Example
Delete a mock tool
DELETE /api/mock-tools/:mockToolId
Remove a mock tool permanently. Runs already in progress keep answering the world they froze at start, so deleting a mock tool never affects an active run.
Delete a mock tool when you want to stop intercepting a tool call entirely. Editing it to return a benign value is the right move when you want to keep the interception but change the answer.
Path parameters
string
required
The
mck_… identifier of the mock tool to delete.Response fields
string
The identifier of the deleted mock tool.
string
The tool name that was intercepted.
string
ISO 8601 timestamp of when the deletion was processed.
Example
List mock tools
GET /api/mock-tools
Return a paginated list of project-level mock tools your credential can reach, ordered newest first.
Query parameters
string
Filter to a specific project by id or name.
string
The
next_cursor value from the previous page. Omit to start from the newest mock tool.Response fields
array
Array of mock tool objects. Each has the same shape as the create response.
string | null
Pass as
?cursor to fetch the next page. null means you are on the last page.