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

nvim-core/src/lib.rs

@@ -1121,7 +1121,7 @@ pub async fn run_mcp_loop(app_name: &str, app_version: &str) {
                                 },
                                 {
                                     "name": "nvim_send_to_terminal",
-                                    "description": "Send a given command string to a Neovim split terminal.",
+                                    "description": "Send a given command string to a visible Neovim split terminal. Use this instead of running background commands when you need to see ANSI colors or interact with command prompts.",
                                     "inputSchema": {
                                         "type": "object",
                                         "properties": {

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,