This server demonstrates foundational tool structure but exhibits critical gaps across naming, descriptions, and schema completeness. All 6 tools are explicitly registered in mcp-server/src/index.ts with names, descriptions, and inputSchemas. However, descriptions are generic and often lack actionable context. Parameter descriptions exist but are minimal (typically 10-30 chars, well below the 72-char baseline). Output schemas are entirely undocumented, the code shows tool registration but never specifies what fields each tool returns. Error handling is completely absent from visible code (only CallToolRequestSchema handler shown, not actual implementation). Naming is reasonable but lacks consistency: tools mix imperative verbs (get_*) inconsistently, and no enum constraints appear despite predictable values (company names, feature names, challenge types). The server is STDIO-only, which is a hard transport cap at 50, but definition quality alone merits 48 before that penalty.
No output schemas documented. Tools register input schemas but never specify what fields/structure is returned. LLMs cannot plan downstream calls or extract required data without knowing the response format.
Parameter descriptions are minimal (10-30 chars) and lack actionable context. E.g., 'Optional path to explore (defaults to root)' does not explain what the tool returns, what format to expect, or how the path filtering works. Descriptions should be 10-1024 chars with WHAT, WHEN, and any prerequisites.
Document output schemas for all 6 tools. Specify return types, field names, and structures. Example for get_case_study: {"type": "object", "properties": {"company": {"type": "string"}, "content": {"type": "string"}, "file_path": {"type": "string"}, "sections": {"type": "array", "items": {"type": "object"}}}. This lets LLMs understand what they're getting and plan follow-up calls.
Add JSON Schema enum constraints to enumerable parameters. For get_case_study, replace free-form company description with enum: {"type": "string", "enum": ["airbnb", "facebook", "netflix", "spotify", "twitter", "uber"]} and remove examples from description.
Expand tool descriptions to 50-200 chars, covering WHAT, WHEN, and any prerequisites. Example: 'Retrieves a case study document for a company (airbnb, facebook, netflix, spotify, twitter, uber). Returns the full case study content including sections, code snippets, and design principles. Use this to learn system design patterns from real-world examples.'
Expand parameter descriptions beyond the current minimal format. Example for get_project_structure's 'path': 'A directory path relative to the project root (e.g., "app/features", "mcp-server/src"). If omitted, returns the full project structure. Path must exist or tool returns an error.'
Add pagination support to search_project_content. Add 'limit' (1-100, default 20) and 'offset' (0+, default 0) parameters. Return total_count and next_offset to enable result scrolling. Document in description: 'Results are capped at 100 items per request.'
Score history
Overall score trend
↑ 12 points across a rubric change (v1 → v2)
47/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
F
47
2026-07-28+
v2
2026-03-09
F
35
-
v1
Enum constraints missing for enumerable parameters. Tools like get_case_study accept 'company' as free-form string with examples in description ('airbnb', 'facebook', 'netflix', 'spotify', 'twitter', 'uber') but no enum constraint. LLMs may hallucinate invalid company names. Use JSON Schema enum.
No error handling guidance visible. Code shows request handler setup but not actual tool implementations or error recovery strategies. LLMs need to know: is this error retryable? Should I ask the user? Or is it fatal?
Pagination and result limiting not addressed. search_project_content accepts free-form 'query' but no limit or offset parameters. If a search returns hundreds of results, context window bloat is likely. Production tools should cap results at 20-50 and offer pagination.
Tool composition and chaining not documented. If get_case_study returns a case study, what fields does it contain? Does it include file paths that other tools accept? Without knowing response structure, agents cannot chain calls.
Implement and document error handling. All tools should return structured errors: {"error": "<category>", "message": "<actionable text>", "suggestion": "<next step>"}. Categories: not_found, invalid_input, retryable, permission_denied. Example: If company not found, return {"error": "not_found", "message": "Company 'google' not found", "suggestion": "Try one of: airbnb, facebook, netflix, spotify, twitter, uber"}.
Add tool annotations (readOnlyHint, idempotentHint) to schema. All 6 tools are read-only and idempotent, so update ListToolsRequestSchema response to include: {"readOnlyHint": true, "idempotentHint": true} for each tool. This signals to agentic systems that these are safe to call without user confirmation.
Document relationships between tools. E.g., in get_feature_component description, note: 'To find available features, call search_project_content with query="feature" first.' This helps agents plan multi-step workflows.
Implement input validation with clear error messages. If get_case_study receives an invalid company name, return: 'Invalid company: "xyz". Must be one of: airbnb, facebook, netflix, spotify, twitter, uber.' not a generic 400 error.
Add examples to the server README showing expected input/output for each tool. This helps both LLM implementations and human users understand the contract.