Build, debug and break hosted mock APIs from Claude: endpoints, stateful CRUD data, OpenAPI import, response variants and fault injection.
Scored across 20 tools
Most tools target distinct resources and actions (endpoints, folders, resources, fault rules, diagnostics), so selection is generally clear. Slight overlap exists between specialized heal_mock_endpoint and generic update_endpoint, and between import_openapi/scaffold_backend/create_resource for bulk creation, but descriptions differentiate them well.
All tools use snake_case with a consistent verb_noun pattern (create_endpoint, list_folders, delete_resource, set_fault_rule, simulate_request). Minor variations like heal_mock_endpoint and singular/plural on fault rules do not break the predictable convention.
20 tools is on the high side, but the server spans several subdomains: workspace listing, endpoint CRUD, folder management, stateful resources, fault injection, OpenAPI import, diagnostics, simulation, and scaffolding. Each tool appears to earn its place, though consolidation could reduce mild redundancy.
The surface covers the full mock API lifecycle: endpoint and folder CRUD, stateful resource creation and deletion, fault-rule management, OpenAPI import, failure inspection, request simulation, and backend scaffolding. Workspace creation is absent but appears out of scope, as workspaces are pre-provisioned.
Delete one fault rule (rule_id) or every fault rule in a workspace, restoring normal responses.
| Name | Required | Description | Default |
|---|---|---|---|
| rule_id | No | Delete only this rule. Omit to delete every fault rule in the workspace. | |
| workspace | Yes | Target workspace slug (from list_workspaces). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds the post-deletion outcome 'restoring normal responses' but omits irreversibility, auth, or operational impact detail, so it adds limited value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One front-loaded sentence with no filler; both deletion modes and the effect are packed efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Low-complexity two-param destructive tool; annotations carry safety and schema carries parameters. The description covers both deletion modes and outcome, though it could point to list_fault_rules for discovering rule_id. Complete enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both rule_id and workspace are already documented. The description repeats the omit-rule_id behavior without adding format or semantics beyond the schema; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb 'Delete' and resource 'fault rule(s)' with workspace scope and effect ('restoring normal responses'), making it easy to separate from list_fault_rules and set_fault_rule. Does not explicitly name siblings, so it is clear but not fully differentiating.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives two operating modes (single rule_id or all rules in workspace) but no explicit when-to-use guidance or alternatives, such as using set_fault_rule to edit instead of delete. Usage is implied by the operation itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a mock HTTP endpoint in a workspace. Provide the workspace slug, method, route (must start with /), and response_body (served as-is; JSON is typical). Pass folder_id to place it in a folder.
| Name | Required | Description | Default |
|---|---|---|---|
| route | Yes | Path starting with /, e.g. /api/v1/users/:id (:param matches one segment). | |
| method | Yes | HTTP method. | |
| delay_ms | No | Artificial response delay in ms (default 0). | |
| auth_type | No | Simulated auth scheme shown for the mock (default None). | |
| folder_id | No | Folder id to place the endpoint in (from list_folders / create_folder). Omit for the workspace root. | |
| workspace | Yes | Workspace slug (from list_workspaces). | |
| capture_mode | No | Request-log capture detail (default metadata). | |
| content_type | No | Content-Type header (default application/json). | |
| require_auth | No | Make the mock require an Authorization header (default false). | |
| response_body | Yes | Response body served as-is (usually JSON). | |
| cors_allow_all | No | Send permissive CORS headers (default true). | |
| selection_mode | No | How a response variant is chosen when several match. first_match (default) serves the first matching variant. weighted picks among matching variants by weight (a percentage); the rest goes to the endpoint's own response. | |
| response_status | No | HTTP status code (default 200). | |
| template_enabled | No | Interpret response_body as a response template (default false). | |
| response_variants | No | Alternative responses; replaces the whole list ([] removes them all). Each has a name, status, body and content_type, and optional conditions that must all match: source header | query | path_param | cookie | body (dot path such as customer.email), with operator equals | not_equals | contains | not_contains | starts_with | ends_with | one_of (value is a list) | exists | not_exists | gt | gte | lt | lte | matches (RE2 regex). With no match the endpoint's own response is served. A request can force a variant with the X-APIMock-Variant header. Check the result with simulate_request. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the mutation/safety profile (readOnlyHint=false, destructiveHint=false), so the bar is lower. The description adds that response_body is served as-is with JSON typical, but omits behavioral context like duplicate-route handling, whether the workspace must exist, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with the purpose and required inputs front-loaded; there is minor redundancy in re-listing required params already in the schema, but nothing is padded or buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 15-parameter tool with four enums and a complex nested response_variants structure and no output schema, the description covers only the core create path. The schema carries the detail, so it is workable, but the description offers no guidance on variants, delays, auth simulation, or verification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 15 parameters, including defaults and constraints. The description merely restates the required fields and the route '/' constraint, adding no syntax or format meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create a mock HTTP endpoint in a workspace'), which is clearly distinct in kind from sibling resources like create_folder and create_resource. However, it does not differentiate from bulk/import siblings such as scaffold_backend or import_openapi, which also produce endpoints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It describes the required inputs and how to place the endpoint in a folder, implying usage, but never states when to use create_endpoint versus import_openapi, scaffold_backend, or update_endpoint for modifications. No exclusions or prerequisites are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a folder in a workspace. Pass parent_folder_id to nest it as a subfolder (create the parent first, or find its id with list_folders). Returns the new folder id to use as create_endpoint's folder_id.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Folder name. | |
| workspace | Yes | Workspace slug (from list_workspaces). | |
| parent_folder_id | No | Parent folder id to nest under (omit for a top-level folder). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds non-obvious behavior beyond that: parent folders must exist before nesting, and the tool returns an id whose purpose is chaining into create_endpoint. It does not mention failure modes such as duplicate names, keeping it out of the top band.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences: purpose first, then the nesting prerequisite, then the return value's downstream use. Nothing is repeated from the schema or annotations and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter create with no output schema, the description covers what it does, the prerequisite for nesting, and the shape of the useful return value. The only gap is error/duplicate-name behavior, which is minor for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3 and every parameter is already documented. The description still adds nesting semantics for parent_folder_id and explains what the return value is used for, going slightly beyond the schema's 'omit for a top-level folder'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
'Create a folder in a workspace' gives a specific verb and resource, and the follow-on sentence about nesting and the returned id makes it unambiguous against siblings like create_endpoint, create_resource, and create_folder's counterpart delete_folder. An agent can select this tool without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It tells the agent how to obtain a parent id ('create the parent first, or find its id with list_folders') and where the returned id goes (create_endpoint's folder_id), which is real routing guidance. It stops short of stating when not to use this tool, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Declare a single new stateful CRUD collection with typed fields and initial seed records. Materializes live CRUD endpoints (list, get, create, patch, put, delete) immediately.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Resource slug (e.g. 'reviews'). | |
| fields | Yes | Ordered typed fields. | |
| folder_id | No | Optional folder ID to nest under. | |
| workspace | Yes | Target workspace slug. | |
| seed_records | No | Seed data rows. | |
| access_policy | No | Intended access level. Stored with the resource and used for export; the mock runtime does not enforce it yet. | public |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds genuinely useful behavioral context beyond that: the call immediately materializes six live CRUD endpoints (list, get, create, patch, put, delete), which tells the agent this has lasting side effects in the mock environment. It still omits whether creation is reversible or what permissions are needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, no filler, with the creation intent front-loaded and the behavioral consequence immediately after. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with no output schema, the description explains the main outcome (live CRUD endpoints) but never says what is returned or how to address the created resource afterwards, nor does it warn about slug collisions in the target workspace. Adequate but with clear gaps for an agent that must use the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents slug, fields, workspace, folder_id, seed_records and access_policy. The description only loosely alludes to 'typed fields and initial seed records' and adds no syntax, format, or constraint detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: declaring a single stateful CRUD collection with typed fields and seed records, plus the side effect of materializing CRUD endpoints. It is clear what the tool creates, though it does not explicitly differentiate itself from siblings like create_endpoint, create_folder, or scaffold_backend.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the purpose — you call this when you need a new CRUD collection — but there is no statement of when to prefer it over create_endpoint, import_openapi, or scaffold_backend, and no prerequisites or uniqueness constraints are mentioned. An agent must infer the selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete one endpoint, identified by endpoint_id or by method and route. To remove a resource's generated CRUD routes, use delete_resource.
| Name | Required | Description | Default |
|---|---|---|---|
| route | No | Route starting with /, used with method when endpoint_id is omitted. | |
| method | No | HTTP method, used with route when endpoint_id is omitted. | |
| workspace | Yes | Target workspace slug (from list_workspaces). | |
| endpoint_id | No | Endpoint id (from list_endpoints). Omit to identify it by method and route. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is fully covered by structured data. The description adds only the addressing mode, not behavioral context such as whether deletion cascades to related mock state or whether it is recoverable. Adequate but not rich beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler, with the identification rule front-loaded and the routing advice second. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but for a destructive mutation whose annotations already state destructiveness and idempotency, the description supplies the addressing rule and the sibling routing an agent actually needs. It stops short of describing consequences of deletion, which would have pushed it higher.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters are already documented and the baseline is 3. The description does add one thing the schema cannot express cleanly: that endpoint_id and the method+route pair are mutually exclusive alternatives ('Omit to identify it by method and route'), which is genuinely useful. However, workspace is never mentioned, so the added value is partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (delete) and resource (one endpoint), and immediately distinguishes itself from the look-alike sibling delete_resource. An agent can select this tool without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the alternative (delete_resource) and the condition that selects it (removing a resource's generated CRUD routes). The dual-identification rule ('endpoint_id or method and route') also tells the agent how to target the call in either scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a folder with its subfolders and every endpoint in them. Refuses folders that hold a resource's CRUD routes; delete those resources with delete_resource first.
| Name | Required | Description | Default |
|---|---|---|---|
| folder_id | Yes | Folder id to delete (from list_folders). | |
| workspace | Yes | Target workspace slug (from list_workspaces). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds crucial behavioral context beyond them: the operation cascades to subfolders and all endpoints, and it refuses folders containing resource CRUD routes. It discloses exactly what gets destroyed and what prerequisite must be handled first.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action and cascade effect, followed by the critical refusal condition and alternative. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the cascading delete behavior, the refusal constraint, and full annotation coverage, the description is complete for correct invocation. No output schema exists, so return values need not be explained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters are documented in the schema with source hints (from list_folders, from list_workspaces). The description adds no additional parameter meaning beyond that, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Delete a folder') and immediately defines the cascade scope ('with its subfolders and every endpoint in them'). This distinguishes it from delete_endpoint and delete_resource without needing to inspect schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states a precondition and refusal condition ('Refuses folders that hold a resource's CRUD routes') and names the correct alternative ('delete those resources with delete_resource first'). This gives an agent clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a resource with its fields, records, seed data and generated CRUD routes. Other endpoints in its folder are kept; the folder is removed only if it ends up empty.
| Name | Required | Description | Default |
|---|---|---|---|
| resource | Yes | Resource slug (e.g. 'products') or id, from list_resources. | |
| workspace | Yes | Target workspace slug (from list_workspaces). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint and idempotentHint, but the description adds the crucial detail of exactly what is destroyed (fields, records, seed data, CRUD routes) and the side effect on the containing folder. That is precisely the context annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, with the destructive cascade front-loaded and the folder side effect second. Every clause carries decision-relevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter, fully annotated destructive tool with complete schema coverage and no output schema, the description covers the operation, its cascade, and its side effects. Nothing needed to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters (resource slug/id, workspace slug) are documented in the schema with their sourcing tools. The description adds no syntax or format detail beyond that, so the baseline applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (delete) and resource (resource) plus its full cascade scope: fields, records, seed data and generated CRUD routes. It also distinguishes itself from delete_folder by clarifying other endpoints in the folder are kept and the folder is only removed if empty.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use guidance or named alternatives. The folder-preservation sentence implies this is not the folder-deletion tool, but the agent must infer that delete_folder is the right sibling for removing a whole folder.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one endpoint's full configuration (response body, status, headers, delay, auth, template and validation settings) and its live URL. Identify it by endpoint_id, or by method and route.
| Name | Required | Description | Default |
|---|---|---|---|
| route | No | Route starting with /, used with method when endpoint_id is omitted. | |
| method | No | HTTP method, used with route when endpoint_id is omitted. | |
| workspace | Yes | Target workspace slug (from list_workspaces). | |
| endpoint_id | No | Endpoint id (from list_endpoints). Omit to identify it by method and route. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful disclosure about what the read returns (response body, status, headers, delay, auth, template/validation settings, live URL), which matters since there is no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences: the return content is front-loaded and the identification alternatives follow. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-value burden and does so by enumerating the config fields and live URL. It omits not-found/error behavior, which keeps it short of full completeness for a lookup tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all four parameters are already documented in the schema, and the description's 'or by method and route' merely restates the schema's either/or relationship. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Get) and resource (one endpoint's full configuration) and enumerates what that configuration includes, which clearly distinguishes it from the sibling list_endpoints and update_endpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It tells the agent how to identify the target (by endpoint_id, or by method and route), but gives no explicit guidance on when to prefer this over list_endpoints or how it relates to update_endpoint/create_endpoint workflows.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing mock endpoint's response body, status code, or request schema directly to fix integration failures identified via inspect_failed_requests.
| Name | Required | Description | Default |
|---|---|---|---|
| route | No | Path of the endpoint starting with / (used if endpoint_id is omitted). | |
| method | No | HTTP method of the endpoint (used if endpoint_id is omitted). | |
| workspace | Yes | Target workspace slug. | |
| endpoint_id | No | ID of the endpoint to update (optional if method and route are provided). | |
| update_body | No | New response body. | |
| update_schema | No | Updated JSON schema for validation. | |
| update_status | No | New HTTP status. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description reinforces that edits are applied 'directly' but never says existing response bodies/schemas are overwritten irreversibly or whether a preview/dry-run exists. Useful workflow context, no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the action, the resource, and the fields modified, then closes with the motivating workflow. Nothing is wasted and nothing important is buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter mutation with no output schema, the description covers the what and the why, and the annotations carry the safety semantics. It is only missing guidance on endpoint targeting (endpoint_id vs route+method) and post-update verification, which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is already documented, including the route/method fallback for endpoint_id. The description names the three payload fields but adds no syntax, format, or targeting nuance beyond what the schema states, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (update) and resource (mock endpoint) plus the exact fields it can change, so the purpose is unambiguous. It does not, however, differentiate itself from the sibling update_endpoint, leaving the agent to guess why 'heal' exists separately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It supplies clear triggering context: use this to fix integration failures surfaced by inspect_failed_requests, which ties it to a concrete workflow. It stops short of stating when not to use it or how it relates to update_endpoint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import an OpenAPI/Swagger spec (v2, v3.0, v3.1; JSON or YAML) into a workspace, generating one mock endpoint per operation with responses taken from the spec's examples. Clean CRUD path-groups become live stateful Resources (with inferred fields and seed records) served at the spec's own paths, instead of static endpoints. Provide either spec (the raw text) or url. Generated objects are placed in a folder named after the spec; re-importing the same spec reconciles instead of duplicating.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | URL to fetch the spec from. Provide this or `spec`. | |
| spec | No | Raw spec text (JSON or YAML). Provide this or `url`. | |
| workspace | Yes | Workspace slug (from list_workspaces). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true. The description adds real value by explaining the reconciliation-not-duplication behavior (supporting idempotency) and the folder-naming/output structure, but with destructiveHint=true it never says what existing endpoints or resources might be overwritten or removed on re-import, leaving the most consequential behavior unexplained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core action and supported spec versions/formats, then layers generation semantics. The second sentence is dense, but every clause carries distinct information (Resources vs. static endpoints, folder placement, reconciliation) rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a fairly complex generative tool with no output schema, the description covers what is produced, where it is placed, and how re-imports behave — enough for correct invocation. It stops short of detailing error/partial-import behavior or the destruction semantics implied by the annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters including the `spec`/`url` mutual exclusivity. The description restates that either input is accepted but adds no format or syntax detail beyond what the schema provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb and resource (import an OpenAPI/Swagger spec into a workspace) and enumerates exactly what it produces: one mock endpoint per operation, plus stateful Resources for clean CRUD path-groups. This distinguishes it from siblings like create_endpoint, create_resource, and scaffold_backend without needing to open any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly frames when to use it (bulk-generating endpoints from an existing spec) and gives the input-selection rule ('Provide either `spec` (the raw text) or `url`'), plus re-import behavior. It does not explicitly name alternative siblings for when a spec import is the wrong choice, which is the only gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect recent failed, 404/unmatched, or errored requests in a workspace. Returns paths, methods, headers, offending payloads, and match diagnostics to diagnose integration issues.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum entries to retrieve (1-50, default 10). | |
| workspace | Yes | Target workspace slug (from list_workspaces). | |
| status_filter | No | Optional HTTP status filter (e.g. 404, 422, 500). | |
| include_injected | No | Include failures APIMock injected on purpose (fault rules or the X-APIMock-Fault header). Off by default so they are not mistaken for real integration bugs. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds the shape of the payload (paths, methods, headers, payloads, match diagnostics), but says nothing about retention windows, ordering, permissions, or why include_injected defaults off beyond what the schema already explains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with zero filler; the scope is front-loaded before the return description. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully enumerates the returned fields, and the fully-covered input schema plus read-only annotation cover the rest. Minor gaps remain around filtering/ordering behavior and result volume, but nothing critical for a correct call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% – all four parameters (limit, workspace, status_filter, include_injected) carry their own descriptions with ranges and defaults. The description adds no syntax or semantics beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Inspect') and resource ('recent failed, 404/unmatched, or errored requests in a workspace'), enumerating the failure categories it covers. This is clearly separable from siblings like simulate_request, list_fault_rules, or list_endpoints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The trailing phrase 'to diagnose integration issues' implies the use case but never states when to choose this over simulate_request or list_fault_rules, nor any exclusions or prerequisites. Usage is inferable but not guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List existing endpoints in a workspace. Use this before create_endpoint to avoid a duplicate method+route.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace | Yes | Workspace slug (from list_workspaces). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds a useful pre-write check rationale but says nothing about return shape, pagination, or whether it lists across all folders – only slightly beyond what annotations give.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, no filler; the core purpose comes first and the workflow guidance second.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple single-parameter read tool with annotations covering safety and no output schema. Missing only minor details such as whether results are grouped/paginated, which prevents a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter, already 100% documented in the schema (workspace slug, cross-referencing list_workspaces). No additional semantics or format guidance are provided, which is the expected baseline when schema coverage is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource ('List existing endpoints in a workspace') scoped clearly, and it distinguishes itself from siblings like get_endpoint, create_endpoint, and the other list_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use it: before create_endpoint to avoid a duplicate method+route. This names both the timing and the alternative/preventive purpose, leaving little inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a workspace's active fault rules with their match, probability, config and minutes remaining.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace | Yes | Target workspace slug (from list_workspaces). | |
| include_expired | No | Also list rules that have expired or are disabled. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=false, so the safe read-only nature is covered. The description adds useful context about what is returned (match, probability, config, minutes remaining) and that rules are active, but it does not disclose pagination, rate limits, or what happens when include_expired is true. With annotations carrying the safety profile, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. Purpose and output fields are communicated efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with two parameters and no output schema, the description is nearly complete. It explains the returned fields, which is important without an output schema, but it does not mention the include_expired override or pagination, leaving a small gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented in the input schema. The description implies the default active-only behavior, but it does not explicitly explain include_expired or add syntax beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb 'List' and resource 'workspace's active fault rules', and names the returned fields. An agent can distinguish this from sibling tools like set_fault_rule and clear_fault_rules without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the verb 'List' and the scope 'active fault rules', but there is no explicit when-to-use guidance, no statement about when not to use it, and no routing to alternatives. The schema handles the workspace parameter, but the description leaves context selection to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List folders (and subfolders) in a workspace, with their ids and paths. Use a folder id as create_endpoint's folder_id, or as create_folder's parent_folder_id.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace | Yes | Workspace slug (from list_workspaces). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safe read-only nature is covered by structured data. The description adds the useful fact that ids and paths are returned, which helps since there is no output schema, but says nothing about auth needs, pagination, or ordering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loaded with what is listed and scoped before the downstream usage note. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only list tool, everything an agent needs is present: the resource scope, the returned identifiers, and how those identifiers feed create_endpoint and create_folder. Safety is covered by annotations, so the absence of an output schema is not a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single 'workspace' parameter is documented as a slug from list_workspaces. The description repeats the workspace scoping but adds no format or syntax detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List folders (and subfolders) in a workspace') and clarifies the returned content (ids and paths). The resource name uniquely separates it from list_resources and list_workspaces, though no sibling is named explicitly as a contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete downstream context: use a returned folder id as create_endpoint's folder_id or create_folder's parent_folder_id. That tells an agent when it needs this tool, but there are no exclusions or explicit 'use X instead' routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a workspace's stateful CRUD resources with their live collection URL, typed fields and record count.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace | Yes | Target workspace slug (from list_workspaces). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds return-content context (collection URL, typed fields, record count) which is useful given no output schema, but says nothing about pagination, ordering, or result size limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; the resource and its returned shape are stated immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with an output schema absent, the description usefully covers what is returned and the scope, and annotations cover safety. It is nearly complete, with minor gaps only around pagination/volume behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single workspace parameter is fully documented in the schema (slug source noted). The description mentions the workspace scope but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and resource (stateful CRUD resources) scoped to a workspace, and even previews the returned data (live collection URL, typed fields, record count). This distinguishes it from create_resource/delete_resource by verb, though it does not explicitly contrast against list_endpoints or list_folders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: it lists a workspace's resources, and the workspace param references list_workspaces as the source of the slug. There is no explicit when-to-use guidance or exclusion relative to the many sibling list_* tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the APIMock workspaces you can access, with their slug and your role. Pass a slug as the workspace argument to list_endpoints / create_endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that access is permission-scoped ("you can access") and that slugs and roles are returned, which is useful behavior beyond the annotations. It does not discuss pagination, formatting, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences with no filler. Purpose is front-loaded, and the follow-up sentence immediately explains how to use the resulting slug without repeating structured data.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must carry return-value context; it names the slug and the caller's role. Combined with annotations covering the safety profile and the routing advice for downstream calls, nothing important is missing for a no-parameter list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
This tool has zero parameters, so the baseline is 4. The description references a `workspace` argument, but only for downstream sibling tools, not for list_workspaces itself, so it adds no relevant parameter semantics here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ("List the APIMock workspaces") and scopes it to "workspaces you can access." It also states the returned key fields (slug and your role), making the tool distinguishable from endpoint, folder, resource, and fault-rule siblings without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly tells the agent what to do with the result: pass the slug as the `workspace` argument to list_endpoints / create_endpoint. That gives strong usage context, but it stops short of an explicit when-to-use/when-not statement or naming any alternative workspace listing route.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Atomically scaffold an entire relational domain backend in a single call with structured resources, typed fields, seed records, and custom endpoints. Returns live CRUD URLs, curl snippets, and contract links.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Optional container folder name (e.g. 'E-Commerce Backend'). | |
| endpoints | No | Optional non-CRUD or custom endpoints (e.g. /api/v1/auth/login). | |
| resources | Yes | List of stateful CRUD collections to declare. | |
| workspace | Yes | Target workspace slug (from list_workspaces). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds genuine behavioral content beyond them: the operation is atomic and it returns live CRUD URLs, curl snippets, and contract links, which is important since no output schema exists. It still omits what happens on partial failure or whether repeated calls are safe.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The scope (what gets scaffolded) is front-loaded and the return artifacts follow, so an agent gets the essentials on the first read.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the description usefully covers the return payload and the atomic semantics. It is slightly thin on failure behavior and on how it relates to the granular create_* siblings an agent could otherwise call, leaving a small gap for such a large, all-in-one operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and each parameter is well documented with examples, so the schema carries the parameter burden. The description only restates the content categories (resources, typed fields, seed records, endpoints) without adding format, constraints, or interaction rules, matching the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb ('scaffold') plus a precise resource ('entire relational domain backend') and an enumeration of what it creates (resources, typed fields, seed records, endpoints). The 'atomically... in a single call' framing implicitly distinguishes it from the granular create_resource/create_endpoint siblings, though it never names them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance. The atomic/single-call phrasing hints that this is the bulk alternative to create_resource and create_endpoint, but the description never routes the agent between them or states prerequisites such as needing an existing workspace.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inject failures into a workspace's mock responses so you can test how the client copes: error statuses (e.g. 503, or 429 with Retry-After), latency, null or dropped JSON fields, or empty lists. Matches by optional method and a path glob, fires with the given probability, and expires automatically (default 60 minutes). For a fault on a single request, send the X-APIMock-Fault header instead (e.g. X-APIMock-Fault: 429;retry-after=2).
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | kind=status: response body. Defaults to a gateway-style JSON error. | |
| kind | Yes | status: return an error status. latency: delay the response. nullify / drop_field: damage JSON fields. empty: return an empty list. | |
| name | No | Label shown in the dashboard. | |
| method | No | Only match this HTTP method. Omit to match every method. | |
| status | No | kind=status: HTTP status. | |
| delay_ms | No | kind=latency: base delay in ms (max 30000). | |
| spike_ms | No | kind=latency: extra delay added on a spike. | |
| jitter_ms | No | kind=latency: uniform ± jitter in ms. | |
| workspace | Yes | Target workspace slug (from list_workspaces). | |
| probability | No | Chance (0-1) that a matching request gets this fault. | |
| retry_after | No | kind=status: Retry-After seconds (useful with 429 and 503). | |
| route_pattern | No | Glob over the request path. `*` matches any characters, including `/`. | /* |
| field_probability | No | kind=nullify/drop_field: per-field chance of damage (0-1). | |
| spike_probability | No | kind=latency: chance of an extra spike. | |
| expires_in_minutes | No | Minutes until the rule switches itself off (default 60, max 10080 = 7 days). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover the safety profile (not read-only, not destructive, closed-world); the description adds substantial behavior the annotations do not carry — probabilistic firing, method/glob matching semantics, and automatic expiry with a stated default of 60 minutes. That is exactly the extra context an agent needs before creating a persistent rule.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. The core capability is front-loaded, the matching/expiry mechanics follow, and the alternative mechanism is placed last where it belongs. Every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 15-parameter mutation tool with no output schema but full schema coverage, the description covers the fault taxonomy, matching, probability, and lifetime. It does not mention what is returned on success (e.g. a rule id) or how rules interact, a small remaining gap rather than a blocker.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the structured fields already do the heavy lifting and the baseline is 3. The description rises above that by mapping fault kinds to their effect (429 with Retry-After, null or dropped JSON fields, empty lists) and restating the path-glob match rule, giving the agent a conceptual model of the parameters rather than just names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('inject failures into a workspace's mock responses') and enumerates the five concrete fault kinds (error statuses, latency, null/dropped fields, empty lists). It is clearly distinguishable from siblings like list_fault_rules or clear_fault_rules without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit when-not with a concrete alternative: for a one-off fault, send the X-APIMock-Fault header instead, with a worked example. It does not explicitly mention the sibling tools clear_fault_rules/list_fault_rules for managing existing rules, which would be needed for a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show which endpoint and which response (including response variants) a request would get, and why, without sending it or logging anything. Reports each variant's conditions as matched or not, and probabilities for weighted endpoints. Use it to check response variants after create_endpoint or update_endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Raw request body, e.g. JSON text. | |
| path | Yes | Request path, optionally with a query string, e.g. /api/orders/42?expand=items. | |
| method | Yes | HTTP method of the request. | |
| headers | No | Request headers. Include Content-Type when sending a body, and X-APIMock-Variant to force a variant. | |
| workspace | Yes | Target workspace slug (from list_workspaces). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is partly covered. The description goes further by confirming nothing is sent or logged and by describing the report contents: per-variant condition match status and probabilities for weighted endpoints. That is meaningful behavioral disclosure beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both earning their place: the first defines the dry-run preview and its reporting behavior, the second routes the agent to the relevant workflow. No repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must explain return content — and it does, covering matched endpoint, response selection rationale, variant condition match status, and weighted probabilities. Combined with full schema coverage and safety annotations, an agent has enough to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% across five parameters, so the schema already documents method, path, headers, body, and workspace. The description does not add syntax or semantic detail beyond the schema (e.g., it does not explain the X-APIMock-Variant forcing header). Baseline 3 is appropriate when the schema carries parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a precise verb and resource: preview which endpoint and response a request would resolve to, and explains the 'why'. It explicitly distinguishes this preview behavior from siblings like create_endpoint, update_endpoint, and delete_endpoint by emphasizing 'without sending it or logging anything.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear usage context — use this to check response variants after create_endpoint or update_endpoint — and clarifies the dry-run nature. It does not name explicit when-not conditions or a full set of alternatives, but the routing guidance is concrete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change any setting of an existing endpoint, including its method, route or folder. Pass only the fields to change in changes; the rest keep their current values. Identify the endpoint by endpoint_id, or by method and route. A resource's generated CRUD routes can't be edited.
| Name | Required | Description | Default |
|---|---|---|---|
| route | No | Route starting with /, used with method when endpoint_id is omitted. | |
| method | No | HTTP method, used with route when endpoint_id is omitted. | |
| changes | Yes | Only the fields to change. Everything else keeps its current value. | |
| workspace | Yes | Target workspace slug (from list_workspaces). | |
| endpoint_id | No | Endpoint id (from list_endpoints). Omit to identify it by method and route. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful semantics beyond that: partial-update behavior ('the rest keep their current values'), the dual identification mechanism, and the immutability constraint on generated CRUD routes. It does not explain the destructive aspects (e.g. that replacing a variants list drops the old list), but that behavior surfaces in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: action and editability, update semantics, then identification. Nothing is repeated and the most important constraint is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a nested mutation with no output schema, the description covers the essentials an agent needs to call it correctly: what can change, how to identify the target, and partial-update behavior. The deeply nested `response_variants`/conditions model is left to the schema, which is reasonable but leaves the tool description thin relative to the overall complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and already documents `changes`, `endpoint_id`, `method`, `route`, and `workspace` in detail. The description largely restates the schema's semantics (partial update, endpoint_id vs method+route identification) rather than adding syntax or value domains, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Change any setting of an existing endpoint') and immediately bounds the scope with what can be edited (method, route, folder). The closing constraint about resource-generated CRUD routes distinguishes it from creation/import paths and from editing resource-owned routes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context: use it to change settings on an existing endpoint, pass only the fields to change, and identify the endpoint either by endpoint_id or by method+route. It also states a when-not ('A resource's generated CRUD routes can't be edited') but does not name sibling alternatives such as create_endpoint or delete_endpoint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
clear_fault_rulescreate_endpointcreate_foldercreate_resourcedelete_endpointdelete_folderdelete_resourceget_endpointheal_mock_endpointimport_openapiinspect_failed_requestslist_endpointslist_fault_ruleslist_folderslist_resourceslist_workspacesscaffold_backendset_fault_rulesimulate_requestupdate_endpointHosted mock APIs from OpenAPI, TypeScript or Postman: realistic data, errors and latency on demand.
AI-native mock API server with MCP. Create REST/SOAP mocks from Claude, Cursor, or Windsurf.
AI-callable tools for API mocking, testing, monitoring, security, and automation.
Mock REST APIs, fake OAuth2/OIDC provider, uptime monitors + heartbeats, live badge/QR images.
Add one secure layer between your agents and this server.