feat(handlers): enrich semantic error messages with prescriptive tool hints to prevent LLM hallucination traps

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())
     }

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())
         }
     }
 }

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())
         }
     }
 }

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())
         }
     }
 }