From a24ef598a22872e067471018c029dae01c6c378b Mon Sep 17 00:00:00 2001
From: Riz Ashraf <reazul.ashraf@inseinc.com>
Date: Sat, 26 Sep 2026 08:47:52 +0100
Subject: [PATCH] feat(handlers): enrich semantic error messages with
 prescriptive tool hints to prevent LLM hallucination traps

---
 server/src/handlers/graph.rs      | 10 +++++-----
 server/src/handlers/meta.rs       |  2 +-
 server/src/handlers/tasks.rs      |  8 ++++----
 server/src/handlers/workspaces.rs |  2 +-
 4 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/server/src/handlers/graph.rs b/server/src/handlers/graph.rs
index 7151c8b..68ae6df 100644
--- a/server/src/handlers/graph.rs
+++ b/server/src/handlers/graph.rs
@@ -230,7 +230,7 @@ impl McpTool for DeleteEntitiesHandler {
         });
 
         if !missing.is_empty() {
-            return Err(format!("Error: Entities not found: {}", missing.join(", ")));
+            return Err(format!("Error: Entities not found: {}. Please use the search_nodes or read_graph tools to verify the exact entity names.", missing.join(", ")));
         }
 
         let idx = state.get_search_index();
@@ -271,7 +271,7 @@ impl McpTool for DeleteObservationsHandler {
             }
         });
         if !missing.is_empty() {
-            return Err(format!("Error: Entities not found: {}", missing.join(", ")));
+            return Err(format!("Error: Entities not found: {}. Please use the search_nodes or read_graph tools to verify the exact entity names.", missing.join(", ")));
         }
         Ok("Observations deleted".to_string())
     }
@@ -299,7 +299,7 @@ impl McpTool for DeleteRelationsHandler {
             missing_count = to_rem.len() - (initial_len - master.relations.len());
         });
         if missing_count > 0 {
-            return Err(format!("Error: {} relation(s) not found in graph", missing_count));
+            return Err(format!("Error: {} relation(s) not found in graph. Please verify exact relation properties using read_graph.", missing_count));
         }
         Ok("Relations deleted".to_string())
     }
@@ -527,7 +527,7 @@ impl McpTool for CondenseEntityHandler {
             }
         });
         if missing {
-            return Err(format!("Error: Entity '{}' not found", req.entity_name));
+            return Err(format!("Error: Entity '{}' not found. Please verify the exact entity name using search_nodes.", req.entity_name));
         }
         Ok("Entity condensed".to_string())
     }
@@ -579,7 +579,7 @@ impl McpTool for MergeEntitiesHandler {
             });
         });
         if missing {
-            return Err(format!("Error: Source entity '{}' not found", req.source_entity));
+            return Err(format!("Error: Source entity '{}' not found. Please verify the exact entity name using search_nodes.", req.source_entity));
         }
         Ok("Entities merged".to_string())
     }
diff --git a/server/src/handlers/meta.rs b/server/src/handlers/meta.rs
index 3d18ba1..f10a256 100644
--- a/server/src/handlers/meta.rs
+++ b/server/src/handlers/meta.rs
@@ -293,7 +293,7 @@ impl McpTool for ResolveTechDebtHandler {
         if found {
             Ok("Tech debt resolved".to_string())
         } else {
-            Err("Tech debt not found".to_string())
+            Err("Tech debt not found. Please verify the tech debt ID using list_tech_debt.".to_string())
         }
     }
 }
diff --git a/server/src/handlers/tasks.rs b/server/src/handlers/tasks.rs
index acd079c..a31beb6 100644
--- a/server/src/handlers/tasks.rs
+++ b/server/src/handlers/tasks.rs
@@ -113,7 +113,7 @@ impl McpTool for DeleteTaskHandler {
             ][0]
             .clone())
         } else {
-            Err("Task not found.".to_string())
+            Err("Task not found. Please use the list_active_tasks tool to verify the correct task ID.".to_string())
         }
     }
 }
@@ -256,7 +256,7 @@ impl McpTool for UpdateTaskStatusHandler {
         } else if found {
             Ok("Task status updated.".to_string())
         } else {
-            Err("Task not found.".to_string())
+            Err("Task not found. Please use the list_active_tasks tool to verify the correct task ID.".to_string())
         }
     }
 }
@@ -336,7 +336,7 @@ impl McpTool for SetAcceptanceCriteriaHandler {
         if success {
             Ok("Acceptance criteria set successfully.".to_string())
         } else {
-            Err("Task not found.".to_string())
+            Err("Task not found. Please use the list_active_tasks tool to verify the correct task ID.".to_string())
         }
     }
 }
@@ -444,7 +444,7 @@ impl McpTool for UpdateMilestoneHandler {
         if found {
             Ok("Milestone updated".to_string())
         } else {
-            Err("Milestone not found".to_string())
+            Err("Milestone not found. Please verify the milestone ID using list_milestones.".to_string())
         }
     }
 }
diff --git a/server/src/handlers/workspaces.rs b/server/src/handlers/workspaces.rs
index d9badea..5b0bf70 100644
--- a/server/src/handlers/workspaces.rs
+++ b/server/src/handlers/workspaces.rs
@@ -185,7 +185,7 @@ impl McpTool for DeleteSnippetHandler {
             drop(idx.delete_document(&req.name));
             Ok("Snippet deleted.".to_string())
         } else {
-            Err("Snippet not found.".to_string())
+            Err("Snippet not found. Please verify the snippet ID using search_snippets.".to_string())
         }
     }
 }