Theorex exhibits significant definition quality gaps. While 14 tools are registered with schemas and descriptions, most descriptions are terse (10-50 chars), parameter documentation is sparse, and output schemas are entirely absent from the source. Tool names lack clear action verbs (e.g., 'synthesize' vs 'write_observation', 'span_tool' is generic). No error handling guidance, no pagination support, and no indication of idempotency or side-effect classification. The codebase shows sophisticated memory architecture but the MCP interface does not expose it clearly to LLMs.

• Add output schemas to every tool. Document return type (object/array), required fields, and field types. Example: retrieve should document {results: [{id, label, score, memory_type, created_at}], total_count, next_cursor}.
• Expand descriptions to 100-200 chars. Include WHAT the tool does, WHEN to use it, and any prerequisites. Example: 'synthesize' → 'Write a new observation to an agent's semantic memory (axon). Use this to inject facts, events, or context that the agent should remember. Observations are indexed and decay over time.'
• Rename tools to verb_noun pattern. synthesize → write_observation; span_tool → emit_span; meta_review → review_agent_state; compress_aaak → compress_concepts_to_aaak.
• Add descriptions to all parameters. For object/array params (traits, metadata, steps), specify expected structure. Example: traits should be {trait_name: string, value: string|number, confidence: 0-1}.
• Document error cases and recovery paths. Example: 'If agent_id not found, returns 404 with available agent IDs. Retry with a valid agent_id or call list_agents() first.'