Agent8 MCP Server implements a single tool (search_code_examples) with a well-structured input schema and comprehensive parameter descriptions. However, critical gaps in output schema documentation, error handling guidance, and composition patterns prevent a higher score. The tool has good naming (verb_noun pattern: search_code_examples) and detailed parameter descriptions, but lacks documented return structure and error recovery guidance. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) present despite the tool being marked READ_ONLY. Output is returned as raw JSON string in a text field, with no documented schema for the returned structure.

• Add explicit output schema documentation to search_code_examples. Document the structure of returned code examples (e.g., example_id, title, language, engine, code_snippet, relevance_score, tags). Example: 'Returns an array of code_example objects, each containing: {example_id: string, title: string, code: string, language: string, engine: string, relevance_score: number}.'
• Implement and document error handling: Add to tool description what happens on empty results, vector DB connection failures, or invalid input. Example: 'If no examples match the tags, returns empty array with suggestion to broaden tags. If vector DB is unavailable, returns error code VECTOR_DB_UNAVAILABLE with guidance to retry in 30 seconds.'
• Add toolAnnotations to the tool definition. Set readOnlyHint=true since the tool only searches/retrieves data. This communicates safety to MCP clients and complies with current spec patterns.
• Document result limits and pagination. Specify maximum results returned (e.g., 'Returns up to 20 most relevant examples'). Add optional limit parameter (default 20, max 100) to control result size. Mention support for offset-based pagination if applicable.
• Formalize parameter constraints. Replace descriptive text 'ENGLISH ONLY' with validation logic. Document: userMessage min 10 chars, max 1000 chars; tags array min 1 item, max 10 items; each tag min 2 chars, max 50 chars, alphanumeric + underscore only.
• Add idempotency guarantee. Document: 'Calling with identical userMessage and tags always returns identical results. Safe to retry without side effects.' Assign idempotentHint=true if applicable.

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry