Threadwork MCP exposes 9 tools (with 2 duplicates: trace_record appears in both packages/mcp-server and experiments/w1). Tools have descriptions and basic schemas, but critical gaps undermine production readiness. Parameter descriptions are sparse or missing entirely (e.g., memory_write_episode lacks descriptions for 'role' and 'content' beyond type). Output schemas are undocumented, callers cannot predict response structure. Error handling is absent; no guidance on retryability or recovery. Naming follows verb_noun convention (memory_*, trace_*) but lacks clarity on when to use memory_recall_episodes vs memory_recall_facts. The echo tool is a spike validation artifact. Overall, definitions are functional but fall short of LLM-optimized quality.

• Document output schemas for all tools. Example: memory_recall_episodes should return {episodes: [{id, task_id, role, content, created_at}], total_count}. This enables LLMs to chain tools correctly.
• Add parameter descriptions to all tools. For memory_write_episode, clarify: 'role: Agent role identifier (e.g., "planner", "executor"). Used for audit trails.' For 'content': 'Episode content as plain text or JSON. Max 1MB per task after deduplication.'
• Consolidate trace_record definitions. Choose one canonical schema (prefer the packages/mcp-server version as production-grade) and remove the spike version from experiments/w1.
• Add error handling guidance. E.g., memory_recall_episodes: 'If no results, try a broader query or check task_id exists. Call memory_recall_facts for exact key lookups instead.'
• Remove or clearly deprecate the echo tool. If it must remain for testing, add a description: 'TESTING ONLY: Returns input unchanged. Not for production use.'