claude-flow 3.7.0-alpha.21 → 3.7.0-alpha.23

package/v3/@claude-flow/cli/dist/src/mcp-tools/memory-tools.js

@@ -582,7 +582,7 @@ export const memoryTools = [
     },
     {
         name: 'memory_stats',
-        description: 'Get memory storage statistics including HNSW index status',
+        description: 'Get memory storage statistics including HNSW index status Use when native Read/Write is wrong because you need (a) cross-session retrieval by semantic similarity (vector embeddings) not by file path, (b) namespacing across projects without managing directory layout, or (c) the .swarm/memory.db audit trail. For one-shot file I/O, native Read/Write is fine.',
         category: 'memory',
         inputSchema: {
             type: 'object',
@@ -629,7 +629,7 @@ export const memoryTools = [
     },
     {
         name: 'memory_migrate',
-        description: 'Manually trigger migration from legacy JSON store to sql.js',
+        description: 'Manually trigger migration from legacy JSON store to sql.js Use when native Read/Write is wrong because you need (a) cross-session retrieval by semantic similarity (vector embeddings) not by file path, (b) namespacing across projects without managing directory layout, or (c) the .swarm/memory.db audit trail. For one-shot file I/O, native Read/Write is fine.',
         category: 'memory',
         inputSchema: {
             type: 'object',
@@ -668,7 +668,7 @@ export const memoryTools = [
     // ===== Claude Code Memory Bridge Tools =====
     {
         name: 'memory_import_claude',
-        description: 'Import Claude Code auto-memory files into AgentDB with ONNX vector embeddings. Reads ~/.claude/projects/*/memory/*.md files, parses YAML frontmatter, splits into sections, and stores with 384-dim embeddings for semantic search. Use allProjects=true to import from ALL Claude projects. Pass projectPath to override cwd-based detection (#1883 — required when Ruflo runs in WSL but Claude Code is on Windows).',
+        description: 'Import Claude Code auto-memory files into AgentDB with ONNX vector embeddings. Reads ~/.claude/projects/*/memory/*.md files, parses YAML frontmatter, splits into sections, and stores with 384-dim embeddings for semantic search. Use allProjects=true to import from ALL Claude projects. Pass projectPath to override cwd-based detection (#1883 — required when Ruflo runs in WSL but Claude Code is on Windows). Use when native Read/Write is wrong because you need (a) cross-session retrieval by semantic similarity (vector embeddings) not by file path, (b) namespacing across projects without managing directory layout, or (c) the .swarm/memory.db audit trail. For one-shot file I/O, native Read/Write is fine.',
         category: 'memory',
         inputSchema: {
             type: 'object',
@@ -802,7 +802,7 @@ export const memoryTools = [
     },
     {
         name: 'memory_bridge_status',
-        description: 'Show Claude Code memory bridge status — AgentDB vectors, SONA learning, intelligence patterns, and connection health.',
+        description: 'Show Claude Code memory bridge status — AgentDB vectors, SONA learning, intelligence patterns, and connection health. Use when native Read/Write is wrong because you need (a) cross-session retrieval by semantic similarity (vector embeddings) not by file path, (b) namespacing across projects without managing directory layout, or (c) the .swarm/memory.db audit trail. For one-shot file I/O, native Read/Write is fine.',
         category: 'memory',
         inputSchema: { type: 'object', properties: {} },
         handler: async () => {
@@ -858,7 +858,7 @@ export const memoryTools = [
     },
     {
         name: 'memory_search_unified',
-        description: 'Search across both Claude Code memories and AgentDB entries using semantic vector similarity. Returns merged, deduplicated results from all namespaces.',
+        description: 'Search across both Claude Code memories and AgentDB entries using semantic vector similarity. Returns merged, deduplicated results from all namespaces. Use when native Read/Write is wrong because you need (a) cross-session retrieval by semantic similarity (vector embeddings) not by file path, (b) namespacing across projects without managing directory layout, or (c) the .swarm/memory.db audit trail. For one-shot file I/O, native Read/Write is fine.',
         category: 'memory',
         inputSchema: {
             type: 'object',

package/v3/@claude-flow/cli/dist/src/mcp-tools/neural-tools.js

@@ -155,7 +155,7 @@ function cosineSimilarity(a, b) {
 export const neuralTools = [
     {
         name: 'neural_train',
-        description: 'Train a neural model',
+        description: 'Train a neural model Use when nothing native trains on your workflow — Claude Code has no learning loop. Use to train SONA/MoE/EWC patterns from successful task outcomes; query via neural_predict before spawning agents. Off-path for one-shot work.',
         category: 'neural',
         inputSchema: {
             type: 'object',
@@ -273,7 +273,7 @@ export const neuralTools = [
     },
     {
         name: 'neural_predict',
-        description: 'Make predictions using a neural model',
+        description: 'Make predictions using a neural model Use when nothing native trains on your workflow — Claude Code has no learning loop. Use to train SONA/MoE/EWC patterns from successful task outcomes; query via neural_predict before spawning agents. Off-path for one-shot work.',
         category: 'neural',
         inputSchema: {
             type: 'object',
@@ -374,7 +374,7 @@ export const neuralTools = [
     },
     {
         name: 'neural_patterns',
-        description: 'Get or manage neural patterns',
+        description: 'Get or manage neural patterns Use when nothing native trains on your workflow — Claude Code has no learning loop. Use to train SONA/MoE/EWC patterns from successful task outcomes; query via neural_predict before spawning agents. Off-path for one-shot work.',
         category: 'neural',
         inputSchema: {
             type: 'object',
@@ -501,7 +501,7 @@ export const neuralTools = [
     },
     {
         name: 'neural_compress',
-        description: 'Compress neural model or embeddings',
+        description: 'Compress neural model or embeddings Use when nothing native trains on your workflow — Claude Code has no learning loop. Use to train SONA/MoE/EWC patterns from successful task outcomes; query via neural_predict before spawning agents. Off-path for one-shot work.',
         category: 'neural',
         inputSchema: {
             type: 'object',
@@ -615,7 +615,7 @@ export const neuralTools = [
     },
     {
         name: 'neural_status',
-        description: 'Get neural system status',
+        description: 'Get neural system status Use when nothing native trains on your workflow — Claude Code has no learning loop. Use to train SONA/MoE/EWC patterns from successful task outcomes; query via neural_predict before spawning agents. Off-path for one-shot work.',
         category: 'neural',
         inputSchema: {
             type: 'object',
@@ -683,7 +683,7 @@ export const neuralTools = [
     },
     {
         name: 'neural_optimize',
-        description: 'Optimize neural model performance',
+        description: 'Optimize neural model performance Use when nothing native trains on your workflow — Claude Code has no learning loop. Use to train SONA/MoE/EWC patterns from successful task outcomes; query via neural_predict before spawning agents. Off-path for one-shot work.',
         category: 'neural',
         inputSchema: {
             type: 'object',

package/v3/@claude-flow/cli/dist/src/mcp-tools/performance-tools.js

@@ -52,7 +52,7 @@ function savePerfStore(store) {
 export const performanceTools = [
     {
         name: 'performance_report',
-        description: 'Generate performance report',
+        description: 'Generate performance report Use when native shell timing (`time`, `hyperfine`) is wrong because you want Ruflo-aware benchmarks — HNSW search latency, breaker decisions/sec, MCP response p50/p95, embeddings throughput. For OS-level process profiling, native shell + perf are fine.',
         category: 'performance',
         inputSchema: {
             type: 'object',
@@ -171,7 +171,7 @@ export const performanceTools = [
     },
     {
         name: 'performance_bottleneck',
-        description: 'Detect performance bottlenecks',
+        description: 'Detect performance bottlenecks Use when native shell timing (`time`, `hyperfine`) is wrong because you want Ruflo-aware benchmarks — HNSW search latency, breaker decisions/sec, MCP response p50/p95, embeddings throughput. For OS-level process profiling, native shell + perf are fine.',
         category: 'performance',
         inputSchema: {
             type: 'object',
@@ -240,7 +240,7 @@ export const performanceTools = [
     },
     {
         name: 'performance_benchmark',
-        description: 'Run performance benchmarks',
+        description: 'Run performance benchmarks Use when native shell timing (`time`, `hyperfine`) is wrong because you want Ruflo-aware benchmarks — HNSW search latency, breaker decisions/sec, MCP response p50/p95, embeddings throughput. For OS-level process profiling, native shell + perf are fine.',
         category: 'performance',
         inputSchema: {
             type: 'object',
@@ -365,7 +365,7 @@ export const performanceTools = [
     },
     {
         name: 'performance_profile',
-        description: 'Profile specific component or operation',
+        description: 'Profile specific component or operation Use when native shell timing (`time`, `hyperfine`) is wrong because you want Ruflo-aware benchmarks — HNSW search latency, breaker decisions/sec, MCP response p50/p95, embeddings throughput. For OS-level process profiling, native shell + perf are fine.',
         category: 'performance',
         inputSchema: {
             type: 'object',
@@ -466,7 +466,7 @@ export const performanceTools = [
     },
     {
         name: 'performance_optimize',
-        description: 'Apply performance optimizations',
+        description: 'Apply performance optimizations Use when native shell timing (`time`, `hyperfine`) is wrong because you want Ruflo-aware benchmarks — HNSW search latency, breaker decisions/sec, MCP response p50/p95, embeddings throughput. For OS-level process profiling, native shell + perf are fine.',
         category: 'performance',
         inputSchema: {
             type: 'object',
@@ -567,7 +567,7 @@ export const performanceTools = [
     },
     {
         name: 'performance_metrics',
-        description: 'Get detailed performance metrics',
+        description: 'Get detailed performance metrics Use when native shell timing (`time`, `hyperfine`) is wrong because you want Ruflo-aware benchmarks — HNSW search latency, breaker decisions/sec, MCP response p50/p95, embeddings throughput. For OS-level process profiling, native shell + perf are fine.',
         category: 'performance',
         inputSchema: {
             type: 'object',

package/v3/@claude-flow/cli/dist/src/mcp-tools/progress-tools.js

@@ -231,7 +231,7 @@ function getSummary(metrics) {
  */
 const progressCheck = {
     name: 'progress_check',
-    description: 'Get current V3 implementation progress percentage and metrics',
+    description: 'Get current V3 implementation progress percentage and metrics Use when native TodoWrite is wrong because you need cross-session goal-completion tracking with witness/audit trail. For in-session checklists, native TodoWrite is simpler.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -275,7 +275,7 @@ const progressCheck = {
  */
 const progressSync = {
     name: 'progress_sync',
-    description: 'Calculate and persist V3 progress metrics to file',
+    description: 'Calculate and persist V3 progress metrics to file Use when native TodoWrite is wrong because you need cross-session goal-completion tracking with witness/audit trail. For in-session checklists, native TodoWrite is simpler.',
     inputSchema: {
         type: 'object',
         properties: {},
@@ -296,7 +296,7 @@ const progressSync = {
  */
 const progressSummary = {
     name: 'progress_summary',
-    description: 'Get human-readable V3 implementation progress summary',
+    description: 'Get human-readable V3 implementation progress summary Use when native TodoWrite is wrong because you need cross-session goal-completion tracking with witness/audit trail. For in-session checklists, native TodoWrite is simpler.',
     inputSchema: {
         type: 'object',
         properties: {},
@@ -314,7 +314,7 @@ const progressSummary = {
  */
 const progressWatch = {
     name: 'progress_watch',
-    description: 'Get current watch status for progress monitoring',
+    description: 'Get current watch status for progress monitoring Use when native TodoWrite is wrong because you need cross-session goal-completion tracking with witness/audit trail. For in-session checklists, native TodoWrite is simpler.',
     inputSchema: {
         type: 'object',
         properties: {

package/v3/@claude-flow/cli/dist/src/mcp-tools/ruvllm-tools.js

@@ -11,7 +11,7 @@ async function loadRuvllmWasm() {
 export const ruvllmWasmTools = [
     {
         name: 'ruvllm_status',
-        description: 'Get ruvllm-wasm availability and initialization status.',
+        description: 'Get ruvllm-wasm availability and initialization status. Use when sending every prompt to the Anthropic API is wrong because you need local inference — air-gapped environments, MicroLoRA-fine-tuned per-task adapters, or sub-cent per-call cost. For general Claude work native Task is the right call.',
         inputSchema: { type: 'object', properties: {} },
         handler: async () => {
             try {
@@ -50,7 +50,7 @@ export const ruvllmWasmTools = [
     },
     {
         name: 'ruvllm_hnsw_create',
-        description: 'Create a WASM HNSW router for semantic pattern routing. Max ~11 patterns (v2.0.1 limit).',
+        description: 'Create a WASM HNSW router for semantic pattern routing. Max ~11 patterns (v2.0.1 limit). Use when sending every prompt to the Anthropic API is wrong because you need local inference — air-gapped environments, MicroLoRA-fine-tuned per-task adapters, or sub-cent per-call cost. For general Claude work native Task is the right call.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -80,7 +80,7 @@ export const ruvllmWasmTools = [
     },
     {
         name: 'ruvllm_hnsw_add',
-        description: 'Add a pattern to an HNSW router. Embedding must match router dimensions.',
+        description: 'Add a pattern to an HNSW router. Embedding must match router dimensions. Use when sending every prompt to the Anthropic API is wrong because you need local inference — air-gapped environments, MicroLoRA-fine-tuned per-task adapters, or sub-cent per-call cost. For general Claude work native Task is the right call.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -121,7 +121,7 @@ export const ruvllmWasmTools = [
     },
     {
         name: 'ruvllm_hnsw_route',
-        description: 'Route a query embedding to nearest patterns in HNSW index.',
+        description: 'Route a query embedding to nearest patterns in HNSW index. Use when sending every prompt to the Anthropic API is wrong because you need local inference — air-gapped environments, MicroLoRA-fine-tuned per-task adapters, or sub-cent per-call cost. For general Claude work native Task is the right call.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -152,7 +152,7 @@ export const ruvllmWasmTools = [
     },
     {
         name: 'ruvllm_sona_create',
-        description: 'Create a SONA instant adaptation loop (<1ms adaptation cycles).',
+        description: 'Create a SONA instant adaptation loop (<1ms adaptation cycles). Use when sending every prompt to the Anthropic API is wrong because you need local inference — air-gapped environments, MicroLoRA-fine-tuned per-task adapters, or sub-cent per-call cost. For general Claude work native Task is the right call.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -180,7 +180,7 @@ export const ruvllmWasmTools = [
     },
     {
         name: 'ruvllm_sona_adapt',
-        description: 'Run SONA instant adaptation with a quality signal.',
+        description: 'Run SONA instant adaptation with a quality signal. Use when sending every prompt to the Anthropic API is wrong because you need local inference — air-gapped environments, MicroLoRA-fine-tuned per-task adapters, or sub-cent per-call cost. For general Claude work native Task is the right call.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -209,7 +209,7 @@ export const ruvllmWasmTools = [
     },
     {
         name: 'ruvllm_microlora_create',
-        description: 'Create a MicroLoRA adapter (ultra-lightweight LoRA, ranks 1-4).',
+        description: 'Create a MicroLoRA adapter (ultra-lightweight LoRA, ranks 1-4). Use when sending every prompt to the Anthropic API is wrong because you need local inference — air-gapped environments, MicroLoRA-fine-tuned per-task adapters, or sub-cent per-call cost. For general Claude work native Task is the right call.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -240,7 +240,7 @@ export const ruvllmWasmTools = [
     },
     {
         name: 'ruvllm_microlora_adapt',
-        description: 'Adapt MicroLoRA weights with quality feedback.',
+        description: 'Adapt MicroLoRA weights with quality feedback. Use when sending every prompt to the Anthropic API is wrong because you need local inference — air-gapped environments, MicroLoRA-fine-tuned per-task adapters, or sub-cent per-call cost. For general Claude work native Task is the right call.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -271,7 +271,7 @@ export const ruvllmWasmTools = [
     },
     {
         name: 'ruvllm_chat_format',
-        description: 'Format chat messages using a template (llama3, mistral, chatml, phi, gemma, or auto-detect).',
+        description: 'Format chat messages using a template (llama3, mistral, chatml, phi, gemma, or auto-detect). Use when sending every prompt to the Anthropic API is wrong because you need local inference — air-gapped environments, MicroLoRA-fine-tuned per-task adapters, or sub-cent per-call cost. For general Claude work native Task is the right call.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -308,7 +308,7 @@ export const ruvllmWasmTools = [
     },
     {
         name: 'ruvllm_generate_config',
-        description: 'Create a generation config (maxTokens, temperature, topP, etc.) as JSON.',
+        description: 'Create a generation config (maxTokens, temperature, topP, etc.) as JSON. Use when sending every prompt to the Anthropic API is wrong because you need local inference — air-gapped environments, MicroLoRA-fine-tuned per-task adapters, or sub-cent per-call cost. For general Claude work native Task is the right call.',
         inputSchema: {
             type: 'object',
             properties: {

package/v3/@claude-flow/cli/dist/src/mcp-tools/security-tools.js

@@ -116,7 +116,7 @@ async function getAIDefence() {
  */
 const aidefenceScanTool = {
     name: 'aidefence_scan',
-    description: 'Scan input text for AI manipulation threats (prompt injection, jailbreaks, PII). Returns threat assessment with <10ms latency.',
+    description: 'Scan input text for AI manipulation threats (prompt injection, jailbreaks, PII). Returns threat assessment with <10ms latency. Use when nothing native exists — Claude Code does not have a PII / prompt-injection / adversarial-text scanner. Pair with any tool that ingests untrusted input (browser scrape, federation envelope, memory_import_claude).',
     inputSchema: {
         type: 'object',
         properties: {
@@ -204,7 +204,7 @@ const aidefenceScanTool = {
  */
 const aidefenceAnalyzeTool = {
     name: 'aidefence_analyze',
-    description: 'Deep analysis of input for specific threat types with similar pattern search and mitigation recommendations.',
+    description: 'Deep analysis of input for specific threat types with similar pattern search and mitigation recommendations. Use when nothing native exists — Claude Code does not have a PII / prompt-injection / adversarial-text scanner. Pair with any tool that ingests untrusted input (browser scrape, federation envelope, memory_import_claude).',
     inputSchema: {
         type: 'object',
         properties: {
@@ -289,7 +289,7 @@ const aidefenceAnalyzeTool = {
  */
 const aidefenceStatsTool = {
     name: 'aidefence_stats',
-    description: 'Get AIDefence detection and learning statistics.',
+    description: 'Get AIDefence detection and learning statistics. Use when nothing native exists — Claude Code does not have a PII / prompt-injection / adversarial-text scanner. Pair with any tool that ingests untrusted input (browser scrape, federation envelope, memory_import_claude).',
     inputSchema: {
         type: 'object',
         properties: {},
@@ -340,7 +340,7 @@ const aidefenceStatsTool = {
  */
 const aidefenceLearnTool = {
     name: 'aidefence_learn',
-    description: 'Record detection feedback for pattern learning. Improves future detection accuracy.',
+    description: 'Record detection feedback for pattern learning. Improves future detection accuracy. Use when nothing native exists — Claude Code does not have a PII / prompt-injection / adversarial-text scanner. Pair with any tool that ingests untrusted input (browser scrape, federation envelope, memory_import_claude).',
     inputSchema: {
         type: 'object',
         properties: {
@@ -438,7 +438,7 @@ const aidefenceLearnTool = {
  */
 const aidefenceIsSafeTool = {
     name: 'aidefence_is_safe',
-    description: 'Quick boolean check if input is safe. Fastest option for simple validation.',
+    description: 'Quick boolean check if input is safe. Fastest option for simple validation. Use when nothing native exists — Claude Code does not have a PII / prompt-injection / adversarial-text scanner. Pair with any tool that ingests untrusted input (browser scrape, federation envelope, memory_import_claude).',
     inputSchema: {
         type: 'object',
         properties: {
@@ -499,7 +499,7 @@ const aidefenceIsSafeTool = {
  */
 const aidefenceHasPIITool = {
     name: 'aidefence_has_pii',
-    description: 'Check if input contains PII (emails, SSNs, API keys, passwords, etc.).',
+    description: 'Check if input contains PII (emails, SSNs, API keys, passwords, etc.). Use when nothing native exists — Claude Code does not have a PII / prompt-injection / adversarial-text scanner. Pair with any tool that ingests untrusted input (browser scrape, federation envelope, memory_import_claude).',
     inputSchema: {
         type: 'object',
         properties: {

package/v3/@claude-flow/cli/dist/src/mcp-tools/session-tools.js

@@ -103,7 +103,7 @@ function loadRelatedStores(options) {
 export const sessionTools = [
     {
         name: 'session_save',
-        description: 'Save current session state',
+        description: 'Save current session state Use when native conversation memory is wrong because you need durable cross-session state — restoring agent definitions, swarm topology, memory store, breaker history. For in-session continuation only, no tool needed. Pair with session_save before exiting and session_restore on resume.',
         category: 'session',
         inputSchema: {
             type: 'object',
@@ -163,7 +163,7 @@ export const sessionTools = [
     },
     {
         name: 'session_restore',
-        description: 'Restore a saved session',
+        description: 'Restore a saved session Use when native conversation memory is wrong because you need durable cross-session state — restoring agent definitions, swarm topology, memory store, breaker history. For in-session continuation only, no tool needed. Pair with session_save before exiting and session_restore on resume.',
         category: 'session',
         inputSchema: {
             type: 'object',
@@ -262,7 +262,7 @@ export const sessionTools = [
     },
     {
         name: 'session_list',
-        description: 'List saved sessions',
+        description: 'List saved sessions Use when native conversation memory is wrong because you need durable cross-session state — restoring agent definitions, swarm topology, memory store, breaker history. For in-session continuation only, no tool needed. Pair with session_save before exiting and session_restore on resume.',
         category: 'session',
         inputSchema: {
             type: 'object',
@@ -316,7 +316,7 @@ export const sessionTools = [
     },
     {
         name: 'session_delete',
-        description: 'Delete a saved session',
+        description: 'Delete a saved session Use when native conversation memory is wrong because you need durable cross-session state — restoring agent definitions, swarm topology, memory store, breaker history. For in-session continuation only, no tool needed. Pair with session_save before exiting and session_restore on resume.',
         category: 'session',
         inputSchema: {
             type: 'object',
@@ -349,7 +349,7 @@ export const sessionTools = [
     },
     {
         name: 'session_info',
-        description: 'Get detailed session information',
+        description: 'Get detailed session information Use when native conversation memory is wrong because you need durable cross-session state — restoring agent definitions, swarm topology, memory store, breaker history. For in-session continuation only, no tool needed. Pair with session_save before exiting and session_restore on resume.',
         category: 'session',
         inputSchema: {
             type: 'object',

package/v3/@claude-flow/cli/dist/src/mcp-tools/swarm-tools.js

@@ -110,7 +110,7 @@ const VALID_TOPOLOGIES = new Set([
 export const swarmTools = [
     {
         name: 'swarm_init',
-        description: 'Initialize a swarm with persistent state tracking',
+        description: 'Initialize a swarm with persistent state tracking Use when native Task tool is wrong because you need multi-agent coordination — topology (hierarchical/mesh/star), consensus (raft/byzantine/gossip/crdt/quorum), shared memory namespace, or anti-drift gates. For independent one-shot subagents, native Task is fine; spawn each separately.',
         category: 'swarm',
         inputSchema: {
             type: 'object',
@@ -183,7 +183,7 @@ export const swarmTools = [
     },
     {
         name: 'swarm_status',
-        description: 'Get swarm status from persistent state',
+        description: 'Get swarm status from persistent state Use when native Task tool is wrong because you need multi-agent coordination — topology (hierarchical/mesh/star), consensus (raft/byzantine/gossip/crdt/quorum), shared memory namespace, or anti-drift gates. For independent one-shot subagents, native Task is fine; spawn each separately.',
         category: 'swarm',
         inputSchema: {
             type: 'object',
@@ -242,7 +242,7 @@ export const swarmTools = [
     },
     {
         name: 'swarm_shutdown',
-        description: 'Shutdown a swarm and update persistent state',
+        description: 'Shutdown a swarm and update persistent state Use when native Task tool is wrong because you need multi-agent coordination — topology (hierarchical/mesh/star), consensus (raft/byzantine/gossip/crdt/quorum), shared memory namespace, or anti-drift gates. For independent one-shot subagents, native Task is fine; spawn each separately.',
         category: 'swarm',
         inputSchema: {
             type: 'object',
@@ -300,7 +300,7 @@ export const swarmTools = [
     },
     {
         name: 'swarm_health',
-        description: 'Check swarm health status with real state inspection',
+        description: 'Check swarm health status with real state inspection Use when native Task tool is wrong because you need multi-agent coordination — topology (hierarchical/mesh/star), consensus (raft/byzantine/gossip/crdt/quorum), shared memory namespace, or anti-drift gates. For independent one-shot subagents, native Task is fine; spawn each separately.',
         category: 'swarm',
         inputSchema: {
             type: 'object',

package/v3/@claude-flow/cli/dist/src/mcp-tools/system-tools.js

@@ -82,7 +82,7 @@ function saveMetrics(metrics) {
 export const systemTools = [
     {
         name: 'system_status',
-        description: 'Get overall system status',
+        description: 'Get overall system status Use when native Bash is wrong because you need Ruflo runtime metrics (HNSW index size, ReasoningBank state, swarm health, breaker status) — those are not in /proc, only in the running daemon. For OS-level info (uptime, disk, mem), native Bash + standard tools are fine.',
         category: 'system',
         inputSchema: {
             type: 'object',
@@ -123,7 +123,7 @@ export const systemTools = [
     },
     {
         name: 'system_metrics',
-        description: 'Get system metrics and performance data',
+        description: 'Get system metrics and performance data Use when native Bash is wrong because you need Ruflo runtime metrics (HNSW index size, ReasoningBank state, swarm health, breaker status) — those are not in /proc, only in the running daemon. For OS-level info (uptime, disk, mem), native Bash + standard tools are fine.',
         category: 'system',
         inputSchema: {
             type: 'object',
@@ -277,7 +277,7 @@ export const systemTools = [
     },
     {
         name: 'system_health',
-        description: 'Perform system health check',
+        description: 'Perform system health check Use when native Bash is wrong because you need Ruflo runtime metrics (HNSW index size, ReasoningBank state, swarm health, breaker status) — those are not in /proc, only in the running daemon. For OS-level info (uptime, disk, mem), native Bash + standard tools are fine.',
         category: 'system',
         inputSchema: {
             type: 'object',
@@ -458,7 +458,7 @@ export const systemTools = [
     },
     {
         name: 'system_info',
-        description: 'Get system information',
+        description: 'Get system information Use when native Bash is wrong because you need Ruflo runtime metrics (HNSW index size, ReasoningBank state, swarm health, breaker status) — those are not in /proc, only in the running daemon. For OS-level info (uptime, disk, mem), native Bash + standard tools are fine.',
         category: 'system',
         inputSchema: {
             type: 'object',
@@ -493,7 +493,7 @@ export const systemTools = [
     },
     {
         name: 'system_reset',
-        description: 'Reset system state',
+        description: 'Reset system state Use when native Bash is wrong because you need Ruflo runtime metrics (HNSW index size, ReasoningBank state, swarm health, breaker status) — those are not in /proc, only in the running daemon. For OS-level info (uptime, disk, mem), native Bash + standard tools are fine.',
         category: 'system',
         inputSchema: {
             type: 'object',
@@ -536,7 +536,7 @@ export const systemTools = [
     },
     {
         name: 'mcp_status',
-        description: 'Get MCP server status, including stdio mode detection',
+        description: 'Get MCP server status, including stdio mode detection Use when native Claude Code MCP status is wrong because you need Ruflo-side server detail — tool counts per namespace, transport stats, MCP handshake errors. For just "is MCP up?", `claude mcp list` is fine.',
         category: 'system',
         inputSchema: {
             type: 'object',
@@ -593,7 +593,7 @@ export const systemTools = [
     },
     {
         name: 'task_summary',
-        description: 'Get a summary of all tasks by status',
+        description: 'Get a summary of all tasks by status Use when native TodoWrite is wrong because you need cross-session task persistence, agent assignment, dependency tracking, or completion analytics in the .swarm/memory.db. For in-session checklists native TodoWrite is simpler and faster.',
         category: 'task',
         inputSchema: {
             type: 'object',

package/v3/@claude-flow/cli/dist/src/mcp-tools/task-tools.js

@@ -43,7 +43,7 @@ function saveTaskStore(store) {
 export const taskTools = [
     {
         name: 'task_create',
-        description: 'Create a new task',
+        description: 'Create a new task Use when native TodoWrite is wrong because you need cross-session task persistence, agent assignment, dependency tracking, or completion analytics in the .swarm/memory.db. For in-session checklists native TodoWrite is simpler and faster.',
         category: 'task',
         inputSchema: {
             type: 'object',
@@ -95,7 +95,7 @@ export const taskTools = [
     },
     {
         name: 'task_status',
-        description: 'Get task status',
+        description: 'Get task status Use when native TodoWrite is wrong because you need cross-session task persistence, agent assignment, dependency tracking, or completion analytics in the .swarm/memory.db. For in-session checklists native TodoWrite is simpler and faster.',
         category: 'task',
         inputSchema: {
             type: 'object',
@@ -137,7 +137,7 @@ export const taskTools = [
     },
     {
         name: 'task_list',
-        description: 'List all tasks',
+        description: 'List all tasks Use when native TodoWrite is wrong because you need cross-session task persistence, agent assignment, dependency tracking, or completion analytics in the .swarm/memory.db. For in-session checklists native TodoWrite is simpler and faster.',
         category: 'task',
         inputSchema: {
             type: 'object',
@@ -195,7 +195,7 @@ export const taskTools = [
     },
     {
         name: 'task_complete',
-        description: 'Mark task as complete',
+        description: 'Mark task as complete Use when native TodoWrite is wrong because you need cross-session task persistence, agent assignment, dependency tracking, or completion analytics in the .swarm/memory.db. For in-session checklists native TodoWrite is simpler and faster.',
         category: 'task',
         inputSchema: {
             type: 'object',
@@ -257,7 +257,7 @@ export const taskTools = [
     },
     {
         name: 'task_update',
-        description: 'Update task status or progress',
+        description: 'Update task status or progress Use when native TodoWrite is wrong because you need cross-session task persistence, agent assignment, dependency tracking, or completion analytics in the .swarm/memory.db. For in-session checklists native TodoWrite is simpler and faster.',
         category: 'task',
         inputSchema: {
             type: 'object',
@@ -309,7 +309,7 @@ export const taskTools = [
     },
     {
         name: 'task_assign',
-        description: 'Assign a task to one or more agents',
+        description: 'Assign a task to one or more agents Use when native TodoWrite is wrong because you need cross-session task persistence, agent assignment, dependency tracking, or completion analytics in the .swarm/memory.db. For in-session checklists native TodoWrite is simpler and faster.',
         category: 'task',
         inputSchema: {
             type: 'object',
@@ -393,7 +393,7 @@ export const taskTools = [
     },
     {
         name: 'task_cancel',
-        description: 'Cancel a task',
+        description: 'Cancel a task Use when native TodoWrite is wrong because you need cross-session task persistence, agent assignment, dependency tracking, or completion analytics in the .swarm/memory.db. For in-session checklists native TodoWrite is simpler and faster.',
         category: 'task',
         inputSchema: {
             type: 'object',

package/v3/@claude-flow/cli/dist/src/mcp-tools/terminal-tools.js

@@ -52,7 +52,7 @@ function saveTerminalStore(store) {
 export const terminalTools = [
     {
         name: 'terminal_create',
-        description: 'Create a new terminal session',
+        description: 'Create a new terminal session Use when native Bash is wrong because you need a persistent terminal session across turns/agents with output capture and replay. For one-shot shell commands, native Bash is fine.',
         category: 'terminal',
         inputSchema: {
             type: 'object',
@@ -106,7 +106,7 @@ export const terminalTools = [
     },
     {
         name: 'terminal_execute',
-        description: 'Execute a command in a terminal session',
+        description: 'Execute a command in a terminal session Use when native Bash is wrong because you need a persistent terminal session across turns/agents with output capture and replay. For one-shot shell commands, native Bash is fine.',
         category: 'terminal',
         inputSchema: {
             type: 'object',
@@ -193,7 +193,7 @@ export const terminalTools = [
     },
     {
         name: 'terminal_list',
-        description: 'List all terminal sessions',
+        description: 'List all terminal sessions Use when native Bash is wrong because you need a persistent terminal session across turns/agents with output capture and replay. For one-shot shell commands, native Bash is fine.',
         category: 'terminal',
         inputSchema: {
             type: 'object',
@@ -226,7 +226,7 @@ export const terminalTools = [
     },
     {
         name: 'terminal_close',
-        description: 'Close a terminal session',
+        description: 'Close a terminal session Use when native Bash is wrong because you need a persistent terminal session across turns/agents with output capture and replay. For one-shot shell commands, native Bash is fine.',
         category: 'terminal',
         inputSchema: {
             type: 'object',
@@ -258,7 +258,7 @@ export const terminalTools = [
     },
     {
         name: 'terminal_history',
-        description: 'Get command history for a terminal session',
+        description: 'Get command history for a terminal session Use when native Bash is wrong because you need a persistent terminal session across turns/agents with output capture and replay. For one-shot shell commands, native Bash is fine.',
         category: 'terminal',
         inputSchema: {
             type: 'object',