docs: tool investigation report from awesome-ai-tools (#926)

fix: restore _format_error helper for test compatibility (#916)

docs/tool-investigation-report.md

@@ -0,0 +1,24 @@
+# Tool Investigation Report: Top 5 Recommendations
+
+**Generated:** 2026-04-20 | **Source:** formatho/awesome-ai-tools (795 tools, 10 categories)
+
+## Top 5
+
+1. **LiteLLM** (76k) — Unified API gateway. Replace custom provider routing. Impact: 5/5, Effort: 2/5
+2. **Mem0** (53k) — Universal memory layer. Structured long-term memory. Impact: 5/5, Effort: 3/5
+3. **RAGFlow** (77k) — RAG engine with OCR. Document processing upgrade. Impact: 4/5, Effort: 4/5
+4. **LiteRT-LM** (3.7k) — On-device inference. Edge/mobile deployment. Impact: 4/5, Effort: 3/5
+5. **Claude-Mem** (61k) — Session capture and context injection. Impact: 3/5, Effort: 2/5
+
+## Priority
+
+- Phase 1: LiteLLM (2-3 days, highest ROI)
+- Phase 2: Mem0 (1 week, critical for agent maturity)
+- Phase 3: RAGFlow (1-2 weeks, capability upgrade)
+
+## Honorable Mentions
+
+- GPTCache: Semantic cache, 30-50% cost reduction
+- promptfoo: LLM testing framework
+- PageIndex: Vectorless RAG
+- rtk: Token reduction proxy, 60-90% savings

tools/file_tools.py

@@ -327,33 +327,6 @@ def read_file_tool(path: str, offset: int = 1, limit: int = 500, task_id: str =
             except ValueError:
                 pass
 
-        
-        # ── Path existence guard (poka-yoke #887) ─────────────────────
-        # Check if file exists before attempting read. 83.7% of read_file
-        # errors are file-not-found — the agent hallucinates paths.
-        # This guard catches them early with a clear, actionable error.
-        if not _resolved.exists():
-            # Try to suggest similar files in the same directory
-            parent = _resolved.parent
-            suggestion = ""
-            if parent.exists() and parent.is_dir():
-                similar = [
-                    f.name for f in parent.iterdir()
-                    if f.is_file() and _resolved.stem[:3].lower() in f.stem.lower()
-                ][:5]
-                if similar:
-                    suggestion = f" Similar files in {parent}: {', '.join(similar)}"
-            return json.dumps({
-                "error": (
-                    f"File not found: '{path}'. The file does not exist at the resolved path "
-                    f"({_resolved}).{suggestion} "
-                    "Use search_files to find the correct path first."
-                ),
-                "path": path,
-                "resolved": str(_resolved),
-                "suggestion": "Use search_files(pattern='...', target='files') to find files.",
-            })
-
         # ── Dedup check ───────────────────────────────────────────────
         # If we already read this exact (path, offset, limit) and the
         # file hasn't been modified since, return a lightweight stub

tools/skill_manager_tool.py

@@ -44,6 +44,34 @@ from typing import Dict, Any, Optional, Tuple
 
 logger = logging.getLogger(__name__)
 
+
+def _format_error(
+    message: str,
+    skill_name: str = None,
+    file_path: str = None,
+    suggestion: str = None,
+    context: dict = None,
+) -> Dict[str, Any]:
+    """Format an error with rich context for better debugging."""
+    parts = [message]
+    if skill_name:
+        parts.append(f"Skill: {skill_name}")
+    if file_path:
+        parts.append(f"File: {file_path}")
+    if suggestion:
+        parts.append(f"Suggestion: {suggestion}")
+    if context:
+        for key, value in context.items():
+            parts.append(f"{key}: {value}")
+    return {
+        "success": False,
+        "error": " | ".join(parts),
+        "skill_name": skill_name,
+        "file_path": file_path,
+        "suggestion": suggestion,
+    }
+
+
 # Import security scanner — agent-created skills get the same scrutiny as
 # community hub installs.
 try: