ContextMCP exposes two tools, both named 'search_docs', with identical naming and schemas but slightly different descriptions. The input schema is present and properly typed (query: string, limit: number with min constraint), but critical issues undermine quality: (1) duplicate tool name violates composition patterns and confuses LLM dispatch; (2) descriptions are brief (59-65 chars) and lack context for when/why to use the tool or what it returns; (3) output schema is not documented anywhere in the source, LLMs cannot predict response structure; (4) no error handling guidance (what happens on empty results, bad queries, or API timeouts?); (5) no parameter descriptions explain 'query' semantics or 'limit' defaults; (6) no indication whether results are paginated or bounded; (7) tool annotations (readOnlyHint, idempotentHint) are absent despite being safe, read-only operations.

• Rename the two tools to distinguish them. E.g., 'search_docs_api_reference' and 'search_docs_guides', or consolidate into a single 'search_docs' tool with a 'section' parameter (enum: ['api_reference', 'sdk_docs', 'guides']).
• Add a dedicated 'output' section to the tool definition documenting the return schema. E.g.: 'Returns: array of {title: string, content: string, url: string, section: string, relevance_score: number}'.
• Add parameter descriptions: 'query' → 'Search query, be specific; include framework/language names for better results'; 'limit' → 'Number of results to return (default: 10, max: 20); results ranked by relevance'.
• Expand tool descriptions to 100 - 200 chars explaining WHAT it does, WHEN to use it, and WHAT it returns. Example: 'Search the documentation using semantic search. Returns the most relevant documents (API reference, SDK guides, tutorials) matching your query, ranked by relevance score. Use to answer how-to questions, find API endpoints, or discover framework features.'
• Document error handling: 'On empty query or no results: returns empty array. On rate limit: returns 429 with retry-after header. On invalid limit: returns 400 with constraint message.'
• Add pagination metadata to response: 'Returns {results: [{...}], total_count: number, offset: number}' so agents know whether more results exist.
• Declare tool annotations: set readOnlyHint: true and idempotentHint: true to signal to agents these calls are safe to retry and do not mutate state.