OST MCP has well-structured tool definitions with consistent naming (verb_noun pattern), clear descriptions (avg 80 chars), and proper JSON Schema with Zod validation. All 7 tools are READ_ONLY and follow a coherent discovery/retrieval pattern. However, output schemas are not documented, responses are returned as plain text strings rather than structured objects, forcing LLMs to parse unstructured data. Parameter descriptions are adequate but lack actionable constraints (e.g., search_projects lacks guidance on when to use category vs domain vs techstack). Error handling is present in the client but not surfaced in tool descriptions. No tool annotations (readOnlyHint, idempotentHint) despite all being read-only operations.

• Convert all tool responses from plain text to structured JSON objects. Define explicit output schemas (e.g., Project with fields: id, name, description, categories[], domains[], techstacks[], url, stars). Document these schemas in tool descriptions or via a separate schema registry.
• Add tool annotations to all 7 tools: set readOnlyHint=true and idempotentHint=true in tool registration. This enables clients to optimize caching and retry behavior.
• Enhance search_projects description with filter guidance: 'Use category to narrow by project type (e.g., "Web Framework"), domain for problem space (e.g., "DevOps"), and techstack for implementation language (e.g., "Python"). Combine filters to refine results.'
• Document error recovery in tool descriptions. Add: 'If rate-limited, retry after the Retry-After header. If auth fails, verify OST_API_KEY is set. If backend is unavailable (5xx), retry shortly.'
• Add discovery guidance to reference tools: 'Call list_categories, list_domains, and list_techstacks first to see available filter values for search_projects. Use these names in the filter parameters.'