No documented output schemas for any tool. LLMs cannot plan downstream calls or extract required fields for chaining. Tool responses are completely opaque from the agent's perspective.
Enumerated parameters (mode: 'mock'/'proxy'/'hybrid', test_focus: 'basic'/'functional'/'comprehensive', validation_mode: 'strict'/'soft') are not declared as JSON Schema enums. LLMs may hallucinate invalid values.
create_mcp_pluginexecute_test_plan
Recommendations
Add property-level JSON Schema definitions for auth_config and proxy_config parameters in create_mcp_plugin. Include required fields, types, and examples: {"type":"object","properties":{"auth_type":{"type":"string","enum":["basic","bearer","oauth2"]},"credentials":{"type":"object"},"location":{"type":"string","enum":["header","query","body"]},"name":{"type":"string"}},"required":["auth_type","credentials"]}
Document output schemas for all tools. Example for list_available_mocks: {"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"path":{"type":"string"},"last_updated":{"type":"string","format":"date-time"}},"required":["name","path"]}}
Convert mode, test_focus, and validation_mode parameters to JSON Schema enums instead of free-form strings. E.g., "mode":{"type":"string","enum":["mock","proxy","hybrid"],"description":"Plugin mode..."}
Add error recovery guidance to all tool descriptions. Example: 'If the OpenAPI spec URL is invalid, verify the URL is reachable and follows OpenAPI 3.0 or 3.1 format. For file paths, ensure the file exists and is readable.'
Enhance parameter descriptions with format constraints. E.g., spec_url_or_path: 'URL (http://, https://, or file://) or local file path to OpenAPI specification (max 10MB, JSON or YAML).'
Add pagination support to discovery tools. Include limit (default 20, max 100) and offset parameters. Return total_count in response so agents know if more results exist.
Document prerequisites in tool descriptions. Example for execute_test_plan: 'Ensure the OpenAPI spec is valid and the mock/proxy server is running at server_url. Test scenarios should be defined in the specification or auto-generated by setting auto_generate_scenarios=true.'
No error handling guidance. Error responses do not tell LLMs what to do next or how to recover. No categorization of errors as retryable vs user-fixable vs fatal.
Parameter descriptions are generic and lack actionable constraints. E.g., 'URL or file path to OpenAPI specification' does not specify format, file size limits, or accepted URL schemes. Descriptions should include format constraints (ISO 8601 dates, regex patterns, length limits).
Destructive operation (create_mcp_plugin with auto_register=true) lacks confirmation or dry-run support. No pattern to prevent accidental plugin creation.
List tools (list_available_mocks, discover_running_servers, comprehensive_discovery) lack pagination parameters (limit, offset, page_size). Large result sets could exhaust context window.
Tool descriptions do not document prerequisites or dependencies. E.g., execute_test_plan does not explain whether test plan must be generated first or what 'server_url' should point to.
Add a dry_run parameter to create_mcp_plugin to allow agents to validate configuration before actually creating the plugin. Include expected generated files in response.
For get_mock_by_name and similar lookup tools, add fallback guidance: 'If mock not found by exact name, returns available mocks for discovery. Call list_available_mocks() to see all mock names.'
Add rate limiting and timeout information to tool descriptions. Example: 'This tool may take 5-30 seconds depending on OpenAPI spec complexity. Timeout is 60 seconds.'
Include links to API documentation or examples in descriptions where applicable. Example: 'For auth_config, see supported auth types at https://mockloop.dev/auth-guide'
Add idempotency guarantees to descriptions. Example for create_mcp_plugin: 'Calling with the same plugin_name and spec will update the existing plugin. This is idempotent.' or 'Multiple calls will create duplicate plugins. Use update_mcp_plugin for modifications.'