v0.6.6: LLM-optimize MCP responses — structured hints, diagnostic empties, prescriptive schemas

Structured next_steps: hints are now {"tool", "args", "reason"} dicts
instead of prose strings, so LLM agents can directly invoke suggestions.
Non-tool guidance uses {"action", "reason"}.

Diagnostic diff_impact: returns {status: "no_changes", ref, branch, message}
instead of bare [] when no diff found — LLMs can now reason about why.

Stats coupling_threshold: exposes the adaptive threshold so LLMs can
explain coupling=0.0 (threshold too high for project's change patterns).

Schema descriptions rewritten with prescriptive "Use when..." language
and cross-references between related tools.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: IronAdamant

CLAUDE.md

@@ -46,7 +46,9 @@ chisel/
 - **Numstat validation**: `_parse_log_output` in `git_analyzer.py` validates tab-separated fields are digits or `-` before treating them as numstat. Diff lines with tabs were being misidentified as numstat entries in `git log -L` output.
 - **Encoding safety**: All `subprocess.run()` calls use `encoding="utf-8", errors="replace"`. Git history may contain non-UTF-8 bytes (Latin-1 commit messages, binary diff fragments); these are replaced with `�` instead of crashing. File reads in `engine.py` and `test_mapper.py` already used `errors="replace"`.
 - **Empty-state detection**: All 12 query tools return `{"status": "no_data", "message": "...", "hint": "chisel analyze"}` when the DB has no analysis data, instead of `[]`. `_check_analysis_data()` in `engine.py` calls `storage.has_analysis_data()` (`SELECT 1 FROM code_units LIMIT 1`). Write tools (`analyze`, `update`, `record_result`) and `stats` are unaffected. `stats` adds a `hint` key when all counts are zero. CLI detects this via `_is_no_data()` in `cli.py`.
-- **Next-step suggestions**: `next_steps.py` provides `compute_next_steps(tool_name, result)` which returns contextual follow-up suggestions per tool. Integrated at the dispatch level in `mcp_server.py` — HTTP responses include `"next_steps": [...]` as a sibling to `"result"`, stdio wraps both in a `{"result": ..., "next_steps": [...]}` envelope. CLI is unaffected. Only tools with registered hint functions get suggestions; others return empty.
+- **Next-step suggestions**: `next_steps.py` provides `compute_next_steps(tool_name, result)` which returns structured suggestions per tool. Each hint is a dict: `{"tool": "...", "args": {...}, "reason": "..."}` for tool invocations, or `{"action": "...", "reason": "..."}` for non-tool guidance. LLM agents can directly invoke suggested tools without parsing prose. Integrated at the dispatch level in `mcp_server.py` — HTTP responses include `"next_steps": [...]` as a sibling to `"result"`, stdio wraps both in a `{"result": ..., "next_steps": [...]}` envelope. CLI is unaffected. Only tools with registered hint functions get suggestions; others return empty.
+- **Diagnostic empty responses**: `diff_impact` returns `{"status": "no_changes", "ref": ..., "branch": ..., "message": ...}` instead of bare `[]` when no diff is found. CLI `_is_no_data()` handles both `"no_data"` and `"no_changes"` status values. `_hints_diff_impact` in `next_steps.py` handles the diagnostic dict case, suggesting `diff_impact` with `HEAD~1` or `update`.
+- **LLM-prescriptive schema descriptions**: Tool descriptions in `schemas.py` use prescriptive language ("Use when...", "Use after...") to help LLM agents decide which tool to call. Cross-references between related tools (ownership↔who_reviews, analyze↔update, impact↔diff_impact). Coupling description references `stats` for threshold visibility.
 - **Inline coupling partners**: `risk_map` includes `"coupling_partners"` (top 3 by co-commit count) in each file entry alongside the breakdown. Data is already fetched in the batch query — no extra DB calls.
 - **Triage tool**: Composite `triage` runs `risk_map` (top-N) + `test_gaps` (filtered to top-N files) + `stale_tests` in a single read lock. Returns a dict, not a list, so `limit` is not injected.
 
@@ -81,11 +83,11 @@ next_steps.py → (no internal deps)
 
 Each wired through: engine.tool_*() → CLI subcommand, HTTP POST /call, stdio MCP.
 
-- **`diff_impact`**: Auto-detects changed files/functions from `git diff` and returns impacted tests. Branch-aware: on feature branches diffs against main; on main diffs against HEAD.
+- **`diff_impact`**: Auto-detects changed files/functions from `git diff` and returns impacted tests. Branch-aware: on feature branches diffs against main; on main diffs against HEAD. Returns diagnostic dict (`status: "no_changes"`) with `ref`, `branch`, `message` when no diff is found, instead of bare `[]`.
 - **`update`**: Incremental re-analysis — only re-processes changed files and new commits.
 - **`test_gaps`**: Finds code units with zero test coverage, prioritized by churn risk. Excludes test files by default.
 - **`record_result`**: Records test pass/fail outcomes. Feeds into `suggest_tests` (failure rate boost) and `risk_map` (test instability component).
-- **`stats`**: Returns summary counts for all database tables (code units, tests, edges, commits, etc.).
+- **`stats`**: Returns summary counts for all database tables plus `coupling_threshold` (when commits > 0) so LLM agents can diagnose coupling=0.0 results.
 - **`triage`**: Combined risk_map + test_gaps + stale_tests for top-N riskiest files. Single command for pre-audit/refactor prioritization. Returns `{top_risk_files, test_gaps, stale_tests, summary}`.
 - **`limit` parameter**: All list-returning tools accept `limit` to cap result size.
 - **Adaptive coupling threshold**: `max(3, total_commits // 4)` — scales with project maturity.

chisel/cli.py

@@ -173,8 +173,8 @@ def _limit(result, args):
 
 
 def _is_no_data(result):
-    """Check if *result* is a no-analysis-data warning from the engine."""
-    return isinstance(result, dict) and result.get("status") == "no_data"
+    """Check if *result* is a status response (no-data, no-changes, etc.)."""
+    return isinstance(result, dict) and result.get("status") in ("no_data", "no_changes")
 
 
 def _run_tool(args, method, kwargs, formatter, use_limit=True):

chisel/engine.py

@@ -253,6 +253,9 @@ def tool_diff_impact(self, ref=None):
 
         If ref is not provided, auto-detects: on a feature branch diffs against
         main/master; on main diffs against HEAD (unstaged changes).
+
+        Returns a diagnostic dict (status="no_changes") instead of bare []
+        when no diff is found, so LLM agents can reason about why.
         """
         with self._process_lock.shared():
             with self.lock.read_lock():
@@ -263,7 +266,16 @@ def tool_diff_impact(self, ref=None):
             ref = self._detect_diff_base()
         changed_files = self.git.get_changed_files(ref)
         if not changed_files:
-            return []
+            try:
+                branch = self.git.get_current_branch()
+            except RuntimeError:
+                branch = None
+            return {
+                "status": "no_changes",
+                "ref": ref,
+                "branch": branch,
+                "message": f"No files differ against '{ref}'",
+            }
         functions = []
         for fp in changed_files:
             try:
@@ -328,6 +340,10 @@ def tool_stats(self):
                 stats = self.storage.get_stats()
                 if all(v == 0 for v in stats.values()):
                     stats["hint"] = "All counts are zero. Run 'chisel analyze' to populate."
+                else:
+                    commit_count = stats.get("commits", 0)
+                    if commit_count > 0:
+                        stats["coupling_threshold"] = max(3, commit_count // 4)
                 return stats
 
     # ------------------------------------------------------------------ #

chisel/next_steps.py

@@ -1,21 +1,28 @@
 """Contextual next-step suggestions for MCP tool responses.
 
 Computes follow-up tool suggestions based on what a tool returned,
-so LLM agents know what to invoke next. Only used by MCP servers
-(HTTP and stdio), not the CLI.
+so LLM agents can directly invoke the suggested next tool. Only used
+by MCP servers (HTTP and stdio), not the CLI.
+
+Each suggestion is a dict with:
+    - tool: Chisel tool name to invoke (omitted for non-tool actions)
+    - args: Arguments dict for the tool call (may be partial — LLM
+            fills remaining required args from context)
+    - action: Descriptive action label (only for non-tool suggestions)
+    - reason: Why this step is recommended
 """
 
 
 def compute_next_steps(tool_name, result):
-    """Return a list of next-step suggestion strings for a tool result.
+    """Return a list of structured next-step suggestions for a tool result.
 
     Args:
         tool_name: Name of the tool that produced the result.
         result: The tool's return value (dict or list).
 
     Returns:
-        List of strings, each a brief actionable suggestion. Empty list
-        if no suggestions apply.
+        List of dicts, each a structured suggestion with ``tool``/``args``
+        or ``action`` plus ``reason``. Empty list if no suggestions apply.
     """
     fn = _TOOL_HINTS.get(tool_name)
     if fn is None:
@@ -30,18 +37,18 @@ def compute_next_steps(tool_name, result):
 def _hints_analyze(result):
     if isinstance(result, dict) and "code_files_scanned" in result:
         return [
-            "Run 'risk_map' to identify high-risk files.",
-            "Run 'test_gaps' to find untested code.",
-            "Run 'triage' for a combined risk + gap + stale overview.",
+            {"tool": "risk_map", "args": {}, "reason": "Identify high-risk files"},
+            {"tool": "test_gaps", "args": {}, "reason": "Find untested code"},
+            {"tool": "triage", "args": {}, "reason": "Combined risk + gap + stale overview"},
         ]
     return []
 
 
 def _hints_update(result):
     if isinstance(result, dict) and result.get("files_updated", 0) > 0:
         return [
-            "Run 'diff_impact' to see which tests are affected by the changes.",
-            "Run 'risk_map' to check updated risk scores.",
+            {"tool": "diff_impact", "args": {}, "reason": "See which tests are affected by changes"},
+            {"tool": "risk_map", "args": {}, "reason": "Check updated risk scores"},
         ]
     return []
 
@@ -51,46 +58,50 @@ def _hints_risk_map(result):
         top = result[:3]
         files = [r["file_path"] for r in top]
         steps = [
-            "Run 'test_gaps' to find missing test coverage for high-risk files.",
+            {"tool": "test_gaps", "args": {}, "reason": "Find missing coverage for high-risk files"},
         ]
-        # Suggest coupling drilldown for files with high coupling scores
         high_coupling = [
             r["file_path"] for r in top
             if r.get("breakdown", {}).get("coupling", 0) > 0.3
         ]
         if high_coupling:
             steps.append(
-                f"Run 'coupling {high_coupling[0]}' to see co-change partners."
+                {"tool": "coupling", "args": {"file_path": high_coupling[0]}, "reason": "Investigate co-change partners"}
             )
-        # Suggest churn drilldown for high-churn files
         high_churn = [
             r["file_path"] for r in top
             if r.get("breakdown", {}).get("churn", 0) > 0.5
         ]
         if high_churn:
             steps.append(
-                f"Run 'churn {high_churn[0]}' for detailed change history."
+                {"tool": "churn", "args": {"file_path": high_churn[0]}, "reason": "Detailed change history"}
             )
         steps.append(
-            f"Run 'suggest_tests {files[0]}' for test recommendations on the riskiest file."
+            {"tool": "suggest_tests", "args": {"file_path": files[0]}, "reason": "Test recommendations for riskiest file"}
         )
         return steps
     if isinstance(result, list):
-        return ["Run 'analyze' to populate risk data."]
+        return [{"tool": "analyze", "args": {}, "reason": "Populate risk data"}]
     return []
 
 
 def _hints_diff_impact(result):
+    # Diagnostic dict when no changes detected
+    if isinstance(result, dict) and result.get("status") == "no_changes":
+        return [
+            {"tool": "diff_impact", "args": {"ref": "HEAD~1"}, "reason": "Try diffing against previous commit"},
+            {"tool": "update", "args": {}, "reason": "Re-analyze if working tree has new files"},
+        ]
     if isinstance(result, list) and result:
         return [
-            "Run the listed tests to verify your changes.",
-            "Use 'record_result' to log outcomes for future prioritization.",
-            "Run 'coupling' on changed files to check for hidden dependents.",
+            {"action": "run_tests", "reason": "Execute impacted tests to verify changes"},
+            {"tool": "record_result", "args": {}, "reason": "Log outcomes for future prioritization"},
+            {"tool": "coupling", "args": {}, "reason": "Check changed files for hidden dependents"},
         ]
     if isinstance(result, list):
         return [
-            "Run 'test_gaps' to check if new code needs tests.",
-            "Run 'update' if you've made changes since last analysis.",
+            {"tool": "test_gaps", "args": {}, "reason": "Check if new code needs tests"},
+            {"tool": "update", "args": {}, "reason": "Re-analyze if changes were made since last analysis"},
         ]
     return []
 
@@ -99,40 +110,40 @@ def _hints_test_gaps(result):
     if isinstance(result, list) and result:
         top_file = result[0]["file_path"]
         return [
-            "Write tests for the highest-churn untested units first.",
-            f"Run 'churn {top_file}' to see change frequency.",
-            f"Run 'ownership {top_file}' to find who can help write tests.",
+            {"action": "write_tests", "reason": "Prioritize highest-churn untested units"},
+            {"tool": "churn", "args": {"file_path": top_file}, "reason": "Check change frequency"},
+            {"tool": "ownership", "args": {"file_path": top_file}, "reason": "Find who can help write tests"},
         ]
     if isinstance(result, list):
-        return ["All code units have test coverage."]
+        return [{"action": "complete", "reason": "All code units have test coverage"}]
     return []
 
 
 def _hints_stale_tests(result):
     if isinstance(result, list) and result:
         return [
-            "Update or remove the stale tests listed above.",
-            "Run 'update' to re-analyze after fixing test files.",
+            {"action": "fix_tests", "reason": "Update or remove stale tests listed above"},
+            {"tool": "update", "args": {}, "reason": "Re-analyze after fixing test files"},
         ]
     if isinstance(result, list):
-        return ["All tests reference current code."]
+        return [{"action": "complete", "reason": "All tests reference current code"}]
     return []
 
 
 def _hints_impact(result):
     if isinstance(result, list) and result:
         return [
-            "Run the impacted tests to verify correctness.",
-            "Use 'record_result' to log outcomes for future prioritization.",
+            {"action": "run_tests", "reason": "Execute impacted tests to verify correctness"},
+            {"tool": "record_result", "args": {}, "reason": "Log outcomes for future prioritization"},
         ]
     return []
 
 
 def _hints_suggest_tests(result):
     if isinstance(result, list) and result:
         return [
-            "Run the suggested tests in order of relevance.",
-            "Use 'record_result' to log outcomes for future prioritization.",
+            {"action": "run_tests", "reason": "Execute suggested tests in order of relevance"},
+            {"tool": "record_result", "args": {}, "reason": "Log outcomes for future prioritization"},
         ]
     return []
 
@@ -142,12 +153,12 @@ def _hints_triage(result):
         steps = []
         if result["summary"].get("total_test_gaps", 0) > 0:
             steps.append(
-                "Focus on files appearing in both risk and gap sections."
+                {"action": "prioritize", "reason": "Focus on files appearing in both risk and gap sections"}
             )
         if result["top_risk_files"]:
             top = result["top_risk_files"][0]["file_path"]
-            steps.append(f"Run 'suggest_tests {top}' on the highest-risk file.")
-            steps.append(f"Run 'ownership {top}' to find who owns the riskiest code.")
+            steps.append({"tool": "suggest_tests", "args": {"file_path": top}, "reason": "Test recommendations for riskiest file"})
+            steps.append({"tool": "ownership", "args": {"file_path": top}, "reason": "Identify who owns the riskiest code"})
         return steps
     return []