This server exhibits severe definition quality issues across both tools. Neither tool has descriptions in the source code (descriptions are null in the schema), violating critical pattern:tool-description requirements. Parameter descriptions are universally missing or null. While schemas are technically present via Zod validation, they lack any descriptive metadata that would guide LLM selection or usage. The tool names are verb-based but lack sufficient context for an LLM to distinguish between them or understand when to invoke each. Error handling is minimal, both tools will fail silently or return raw JSON without actionable recovery guidance. The 'make-request' tool is particularly risky as a WRITE operation with no confirmation mechanism, dry-run option, or destructive-hint annotation. No output schemas are documented.
Tool descriptions are completely absent (null in schema). LLMs cannot select between tools without non-empty descriptions explaining WHAT each does and WHEN to use it.
make-request lacks destructive-hint annotation despite being a WRITE operation (POST/PUT/DELETE methods). No error handling, no dry-run option, no confirmation mechanism. Agents can irreversibly modify external systems without safety guardrails.
Parameter 'method' uses enum constraint but lacks description explaining when to use GET vs POST vs PUT vs DELETE, or what side effects each has. 'headers' and 'reqBody' parameters are undescribed, leaving LLMs guessing about format and purpose.
Recommendations
Add non-empty descriptions to EVERY tool. For make-request: 'Send HTTP requests (GET/POST/PUT/DELETE) to any REST API. Use discover-endpoints first to see available API operations. WARNING: POST/PUT/DELETE operations are irreversible and may modify external systems.' (120+ chars, action-oriented). For discover-endpoints: 'Retrieve API specification (OpenAPI/Swagger JSON) from a REST API to see available endpoints and operations. Pass the base URL of the API (e.g., https://api.example.com). Returns full OpenAPI spec or an error.' (140+ chars).
Add descriptions to EVERY parameter. Examples: url → 'Base URL of the REST API or OpenAPI specification endpoint (e.g., https://api.example.com or https://api.example.com/openapi.json)'. method → 'HTTP verb: GET (read-only, safe to retry), POST (creates resource), PUT (updates resource), DELETE (removes resource, irreversible)'. headers → 'Optional HTTP headers as key-value pairs (e.g., {"Authorization": "Bearer token", "X-Custom-Header": "value"})'. reqBody → 'Optional JSON request body for POST/PUT. Must be valid JSON string. Ignored for GET and DELETE requests.'
Add destructiveHint and readOnlyHint annotations to tools. In tool registration: make-request should include {destructiveHint: true} for POST/PUT/DELETE paths. discover-endpoints should include {readOnlyHint: true}. This signals to LLMs and clients which operations are safe.
Implement proper error handling with actionable recovery messages. Example: catch JSON parsing errors and return 'Failed to parse response as JSON. Response was: [truncated response]. Try a different endpoint or check if the API returns JSON.' For discover-endpoints, if all paths fail, suggest 'Could not find OpenAPI spec at standard paths. Try passing the exact spec URL, or use make-request with GET to /api-docs, /api/v1/docs, or /api-spec.'
discover-endpoints accepts a bare 'url' parameter with no description of expected format (base URL? OpenAPI endpoint? Swagger path?). The tool tries multiple hardcoded paths but does not document this behavior or explain what it returns.
make-request returns raw JSON from external APIs without validation, pagination, or result limiting. A large API response will blow the context window. No output schema documented for LLM planning.
Error handling is non-existent. Both tools will return raw fetch errors or JSON parsing failures without actionable recovery guidance. LLM cannot distinguish retryable failures from user errors or fatal ones.
discover-endpoints silently falls back to returning {error: 'Could not find API specification'} without telling the LLM what to try next. No enumeration of attempted paths or actionable next steps.
make-request forces LLMs to construct arbitrary URLs and HTTP requests without domain-specific guidance. No tool composition, LLM must manually chain discovery → request, with no output guarantees that downstream tools will receive the format they expect.
make-request
Add output schema documentation (structured response objects). For make-request: document that responses will be {content: [{type: 'text', text: '...'}]} containing the JSON response or error. For discover-endpoints: document that responses contain the full OpenAPI spec or an error object.
Implement pagination/result limiting for make-request. Cap JSON responses at 10KB or 500 lines. Add optional limit parameter. Document in description: 'Large responses will be truncated to prevent context overflow.'
Add idempotentHint: true to discover-endpoints (read-only operations are always safe to retry).
Consider splitting make-request into separate GET and MUTATE tools to clarify intent and safety: get_api_data (GET only, readOnlyHint) and mutate_api_data (POST/PUT/DELETE only, destructiveHint, with confirmation logic). This aligns with pattern:tool single-responsibility.
Add parameter validation: url must be a valid HTTP(S) URL; method must be one of the enum values (already constrained); headers must be valid header names (no colons); reqBody must be valid JSON if provided. Return clear error messages: 'Invalid URL: must start with http:// or https://. Got: [value]'
Document the relationship between the two tools: 'Step 1: Call discover-endpoints to see available API operations. Step 2: Call make-request to invoke one of those operations. The endpoint path from discover-endpoints feeds into the url parameter of make-request.'
Return per-tool output schema examples in descriptions or comments. E.g., make-request always returns {content: [{type: 'text', text: '<json response or error>'}]}. This helps LLMs understand what to expect and how to chain tools.