This Ruby MCP server for Esa (a knowledge base platform) provides 10 tools with explicit schemas and descriptions. Most tools have clear naming following verb_noun convention and non-empty descriptions. However, several quality gaps emerge: (1) Parameter descriptions are present but often generic, lacking constraint details (e.g., 'Items per page (default: 20, max: 100)' is good, but most lack this rigor). (2) Output schemas are not documented, callers cannot predict response fields. (3) Error handling is minimal, errors are caught but responses lack guidance on recovery or retry eligibility. (4) Some parameters lack type information in their descriptions (e.g., 'include' in get_post_tool has no type hint). (5) Parameter descriptions do not explain dependencies or when fields apply. The server does demonstrate competence: tool names are clear and action-oriented; schemas use proper JSON Schema with enums where appropriate (sort, order); required parameters are declared. Overall, this is a competent mid-tier implementation with room for maturity in output documentation and error guidance.
No documented output schemas. Callers cannot predict response structure or fields returned by any tool. This forces LLMs to discover fields empirically, wasting tokens and risking hallucinated field names.
Parameter descriptions lack constraint details. 'Additional information (comments, stargazers, etc.)' for 'include' parameter does not specify valid enum values, format, or type.
Destructive operations (delete_post_tool) lack confirmation or dry-run support. No guidance in error responses on recovery. Per pattern:confirmation-request, irreversible ops should support a confirmation step or clear recovery guidance.
Recommendations
Document output schemas for every tool. Include field names, types, and descriptions. For example, get_posts_tool should document that it returns {posts: [{number: int, full_name: string, wip: bool, ...}], page: int, total_count: int, per_page: int}. This enables LLMs to chain calls and extract correct fields.
Enhance parameter descriptions with explicit constraints. For 'include' parameter in get_post_tool, specify: 'Comma-separated list of additional fields to include. Valid values: comments, stargazers, or omit for basic post data.' Use enums in schemas where possible.
Add recovery guidance to error responses. When a resource is not found, suggest alternatives: 'Post #999 not found. Try calling get_posts_tool to list available posts first.' When auth fails, guide the user to check ESA_ACCESS_TOKEN. Per pattern:recovery-guide.
Implement confirmation step for delete_post_tool. Before deleting, return a response like 'Ready to delete post #123 (title). Confirm by calling delete_post_tool again with confirm=true.' This prevents accidental deletions.
Classify errors in responses by retry eligibility. Include fields like {error: string, retryable: bool, user_fixable: bool, suggestion: string}. E.g., 'Rate limit exceeded' → {retryable: true, suggestion: 'retry after 60 seconds'}, 'Invalid post_number' → {user_fixable: true, suggestion: 'call get_posts_tool to find valid post numbers'}.
Enrich tool descriptions with context and dependencies. E.g., get_post_tool: 'Get details of a specific post. Call get_posts_tool first to find post numbers, then use this to fetch full content, comments, and metadata.' This guides multi-step planning.
Error handling is generic. All errors caught and returned as text, but responses do not classify errors as retryable/user-fixable/fatal, nor do they guide the LLM to next steps. E.g., 'Error: Resource not found' does not suggest calling search or trying alternative parameters.
Parameter 'include' in get_post_tool lacks type information. Description says 'Additional information (comments, stargazers, etc.)' but does not specify if it's a string, enum, or comma-separated list, or what valid values are accepted.
Tool descriptions are brief (average ~60 - 100 chars) and lack context on WHEN to use each tool vs alternatives. E.g., 'Get a list of posts' does not explain pagination, filtering, or when to use get_post_tool instead.
Add minimum/maximum constraints to numeric parameters. E.g., page: {type: integer, minimum: 1}, per_page: {type: integer, minimum: 1, maximum: 100}. This prevents absurd values from reaching the API.
Document parameter relationships. E.g., in create_post_tool, document that 'wip: true marks the post as work-in-progress; set to false to publish immediately. If omitted, defaults to true.' State mutually exclusive params if any exist.
Return structured error responses, not plain text. Use a consistent error object: {type: 'text', text: '...'} is fine, but include machine-readable fields: {code: 'not_found', message: '...', retry_after: 60}. This lets LLMs parse errors programmatically.
Add idempotency hints to write operations. Document that create_post_tool and update_post_tool are idempotent if passed the same parameters; add a request_id parameter to allow clients to enforce exactly-once semantics.