feat(mcp): update tool descriptions for LLM context optimization

server/src/tools.rs

@@ -679,7 +679,7 @@ pub struct ToggleClipboardWatchModeTool {
 pub struct ReadFileSkeletonTool {
     pub file_path: String,
 }
-/// Replace a specific AST node in a file (robust structural editing)
+/// Replace a specific AST node in a file (robust structural editing). Use this instead of regex or line-based string replacement to prevent indentation bugs and matching failures.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct ReplaceAstNodeTool {
     pub file_path: String,
@@ -688,14 +688,14 @@ pub struct ReplaceAstNodeTool {
     pub new_content: String,
 }
 
-/// Semantic code search using local vector embeddings
+/// Semantic code search using local vector embeddings. Use this conceptual search instead of raw regex (grep) when trying to locate abstract logic or exploring new patterns.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct SemanticCodeSearchTool {
     pub query: String,
     pub directory: Option<String>,
 }
 
-/// Get a bird's-eye view of directory architecture
+/// Get a bird's-eye view of directory architecture. Use this when first exploring a new repository to get a summary of what each file is responsible for, instead of blindly reading files.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct ReadDirectoryArchitectureTool {
     pub directory: String,