Expand MCP usage guide

[evansenter]

Summary

• Expand guide.md from 68 to 297 lines
• Add tool tables for all Phase 2-9 features
• Add usage examples for session classification, failure analysis, git integration, trend analysis
• Document session category definitions with thresholds

🤖 Generated with Claude Code

[claude]

PR Review: Expand MCP usage guide

This is a well-intentioned documentation expansion that improves the guide significantly. However, there are some issues that should be addressed before merging.

Documentation Quality ✅

Strengths:

• Clear structure with logical organization (Status & Ingestion → Core Queries → Pattern Analysis, etc.)
• Helpful example outputs showing expected response formats
• Best practices section is practical and useful
• Good coverage of the /improve-workflow integration

Critical Issue: Documented Tools That Don't Exist ❌

The guide documents several tools that do not exist in the actual server implementation (server.py):

Documented Tool	Exists?	Notes
query_failure_correlation(days?, project?)	❌	Not in server.py
query_common_failures(days?, min_count?)	❌	Not in server.py
query_session_progression(session_id)	❌	Not in server.py
compare_periods(days?, metric?)	❌	Not in server.py
query_session_commits(session_id)	❌	Not in server.py

The actual failure analysis tool is analyze_failures(days?, rework_window_minutes?), which is documented in CLAUDE.md but not mentioned in this guide.

Missing Tools That Do Exist

The guide is also missing some tools that are in server.py:

Actual Tool	Purpose
sample_sequences(pattern, count?, context_events?, days?)	Get random samples of sequence patterns with context
detect_parallel_sessions(hours?, min_overlap_minutes?)	Find sessions active simultaneously
get_handoff_context(session_id?, hours?, message_limit?)	Get context for session handoff

Parameter Discrepancies

Some documented parameters don't match the actual implementation:

1. query_timeline: Guide says (hours?, tool?, session_id?) but actual signature is (start?, end?, tool?, project?, limit?) - uses ISO datetime strings, not hours
2. get_user_journey: Guide says (days?, project?) but actual is (hours?, include_projects?, limit?)

Suggestions

1. Remove or mark as "planned" the five non-existent tools
2. Add documentation for sample_sequences, detect_parallel_sessions, and get_handoff_context
3. Correct the query_timeline documentation to reflect the actual start/end ISO datetime parameters
4. Correct the get_user_journey signature to match the implementation
5. Consider updating the Failure Analysis section to reference analyze_failures instead of the non-existent tools

Minor Suggestions

• The example JSON responses use unquoted property names (JavaScript style) but actual JSON output would have quoted keys
• Line 170-175 category definitions are helpful - consider making the thresholds configurable or at least mentioning they could change

---

Verdict: The documentation expansion is valuable but needs fixes for accuracy. The discrepancy between documented and actual tools would confuse users trying to use non-existent functionality.