SCAPO MCP server has 4 tools with explicit schemas and descriptions visible in mcp/index.js. Naming follows verb_noun pattern (get_*, search_*, list_) and is reasonably clear. All tools have input schemas with type definitions and descriptions. However, there are significant gaps: (1) Output schemas are NOT documented, LLMs cannot see what fields are returned; (2) Parameter descriptions lack constraint details (ranges, valid formats, examples of what 'use_case' values are acceptable); (3) No error handling guidance, tools silently catch errors and return 'Error: <message>' without recovery hints; (4) No pagination support documented for list_models or search_models, which could return large result sets; (5) The descriptions are brief (mostly 50-80 chars) but lack WHEN to use each tool vs. alternatives. The code shows fuzzy matching fallback and local models support, but this functionality is not exposed in descriptions. Tool composition is reasonable, tools are single-purpose and could chain (search_models → get_best_practices). Parameter defaults are sensible (practice_type='all', limit=10, category='all'). Overall: definitions are present and structured, but lack the depth (output schemas, error guidance, constraint details) expected of production-grade agent tools.

• Add output schema documentation to each tool. Document the response structure, e.g.: get_best_practices returns { model_name: string, practices: { prompting: string[], parameters: string[], pitfalls: string[] } }. Make it visible to the client so LLMs can plan downstream uses of the data.
• Implement error classification: wrap errors in structured responses like { type: 'not_found' | 'retryable' | 'user_error' | 'fatal', message: '...', suggestion: 'Try search_models() first' }. This enables agents to adapt their strategy.
• Add enum constraints or examples to 'use_case' and 'query' parameters. E.g., use_case enum: ['code_generation', 'creative_writing', 'image_generation', 'summarization', 'translation']. This prevents hallucination.
• Document pagination limits for search_models and list_models. State: 'Results capped at 100. Use limit parameter (1 - 100) to control batch size.' Include next_cursor or total_count in responses.
• Extend tool descriptions to clarify selection logic. search_models: 'For free-form keyword searches across model names and descriptions.' list_models: 'To browse all models by category (text, image, code, etc.). Use when you need to explore available model types.'
• Document the API backend behavior and local fallback in tool descriptions. Mention that tools work online (via SCAPO_API_URL) or offline (local models directory), so LLMs understand potential latency and coverage differences.
• Add a 'confidence' or 'source' field to responses (e.g., { model: 'gpt-4', source: 'api' | 'local', confidence: 0.95 }) so agents know whether data is fresh or cached.