diff --git a/internal/agent/tools/diagnostics.md b/internal/agent/tools/diagnostics.md
index 37a893aed2ba4e50d7f7187a90c28fc5266f9cc7..3f59a673ebdf25c924e45295b72d46911bb753df 100644
--- a/internal/agent/tools/diagnostics.md
+++ b/internal/agent/tools/diagnostics.md
@@ -1,4 +1,4 @@
-Get diagnostics for file and/or project.
+Get LSP errors, warnings, and hints for a file or the whole project.
 
 <usage>
 - Provide file path to get diagnostics for that file
diff --git a/internal/agent/tools/lsp_restart.md b/internal/agent/tools/lsp_restart.md
index 118ebd645391d9c73b01ff35a8a73094b6f766a3..72728db6f915fba8a98422e0fc19d96fe70f1a0b 100644
--- a/internal/agent/tools/lsp_restart.md
+++ b/internal/agent/tools/lsp_restart.md
@@ -1,4 +1,4 @@
-Restart LSP (Language Server Protocol) clients.
+Restart one or all LSP clients by name; use when diagnostics are stale or the LSP is unresponsive.
 
 <usage>
 - Restart all running LSP clients or a specific LSP client by name
diff --git a/internal/agent/tools/references.md b/internal/agent/tools/references.md
index aff814b8ae2de0f87adeb1bffffe74ff71df7bee..ee725b81f4cb4f92bcc4dcdea78186e263f899c5 100644
--- a/internal/agent/tools/references.md
+++ b/internal/agent/tools/references.md
@@ -1,4 +1,4 @@
-Find all references to/usage of a symbol by name using the Language Server Protocol (LSP).
+Find all references to a symbol by name via LSP; more accurate than grep for code symbols.
 
 <usage>
 - Provide symbol name (e.g., "MyFunction", "myVariable", "MyType").