Claude Gladiator MCP has two tools with reasonable naming and documented schemas, but suffers from significant gaps in parameter descriptions, missing output schema documentation, and weak error guidance. The tool names (gladiator_observe, gladiator_reflect) use verb-noun patterns appropriate for an observation/reflection domain, but descriptions are generic and lack actionable guidance on when/why to call each tool. Input schemas are present and properly typed (Zod), but parameter descriptions are sparse (e.g., 'Optional query string to filter observations' provides no guidance on syntax or capabilities). Output schemas are entirely undocumented, LLMs have no way to know what structure they'll receive or what fields to extract for downstream planning. Error handling is absent from tool definitions; the code catches errors silently but tool definitions include no recovery guidance. The 'tags' parameter in gladiator_observe lacks enum constraints, inviting hallucinated tag values.

• Add explicit output schema documentation to tool definitions. For gladiator_observe, document that it returns {id: string, timestamp: number}. For gladiator_reflect, document the structure of clusters and recommendations (e.g., {groups: [{summary: string, observations: [...], recommendation: string}], stats: {total: number, processed: number}}).
• Expand tool descriptions to 100-200 characters with explicit WHEN/WHY guidance. Example: 'Record observations about patterns, errors, and edge cases encountered. Use this after each non-trivial debugging session or tool interaction to build a learning database. Returns an observation ID for reference.'
• Document parameter constraints in descriptions. For 'query', specify: 'Free-text keyword search (case-insensitive) across summaries, tags, and recommendations. Multiple words treated as AND. Supports 'tag:name' syntax for tag filtering.' For 'limit', add: 'Maximum observations to analyze (1-500; default 50). Results are returned in reverse chronological order.'
• Convert 'tags' from free-form string array to an enum or provide a discovery tool (list_available_tags) so the LLM knows valid values before calling gladiator_observe.
• Add error scenarios to tool descriptions. Example: 'Returns error if observations.jsonl is corrupted; returns empty result if no observations match the query.'
• Restructure gladiator_reflect description to separate concerns or clarify interaction. Consider: 'Analyze recent observations to identify patterns and recommend whether to create new rules/skills or update existing ones. Internally clusters observations by topic, ranks by relevance, and generates actionable recommendations.'