This MCP server exhibits significant definition quality issues across all four tools. While tool names follow verb_noun convention (get_, extract_, refine_, check_), descriptions are generic and lack actionable context for LLM selection. Input schemas are present but parameter descriptions are minimal (1-2 words). Output schemas are entirely undocumented, LLMs cannot infer return types or structure. Error handling is absent; exceptions return JSON error strings without recovery guidance. The server conflates the MCP server role (server.py using FastMCP) with client-side tool invocation logic (mcp-client.py), creating confusion about tool ownership and where validation occurs. Most critically, three tools (extract_entities_tool, refine_query_tool, check_relevance) are defined in mcp-client.py, which is a CLIENT file, not the server, suggesting incomplete tooling exposure or code organization issues.

• Add complete output schema documentation for all tools. For extract_entities_tool, document: 'Returns JSON object with entity type keys (PERSON, LOCATION, ORGANIZATION, etc.) and arrays of extracted entity strings as values. Example: {"PERSON": ["John"], "LOCATION": ["Sri Lanka"]}'
• Expand parameter descriptions to 50-100 chars each. For 'query', write: 'Text to analyze for named entities. Supports English text up to 2000 characters. Examples: news article snippets, user search queries. Entities are categorized by type (PERSON, LOCATION, ORGANIZATION, EVENT, DATE, FACILITY, PRODUCT, WORK_OF_ART).'
• Add 'when to use' clarity to tool descriptions. For refine_query_tool: 'Use to improve vague or ambiguous user queries for vector search. Adds specificity and context without changing intent. Call before extract_entities_tool if the original query is poorly formed. Returns a single refined query string.'
• Implement error recovery guidance. Replace 'return json.dumps({"error": str(e)})' with structured errors like 'OpenAI API call failed: {error_message}. Check API key in environment. Retry in 30 seconds if rate limited.'
• Move all tool definitions into server.py and register via @mcp.tool() decorator. Remove tool logic from mcp-client.py, clients should not define server tools.
• Add parameter validation: check query length before API call, validate that relevance scores are floats 0-1, raise clear errors with constraint details.
• Document refine_query_tool output explicitly: 'Returns a single string containing the refined query. Preserves original intent but increases specificity. Output length usually 20-50% longer than input.'