diff --git a/pkg/cli/functions.go b/pkg/cli/functions.go
index dcbe241..ea8a9c3 100644
--- a/pkg/cli/functions.go
+++ b/pkg/cli/functions.go
@@ -57,7 +57,7 @@ For directories, size represents the number of entries in that directory.`
 Each line of the file is prefixed with its line number and a tabs (\t) to make
 it make it easier to see which lines to change for other modifications.
 
-Example:
+Example result:
 {
 	"message": "success", // if successful, or a different message indicating failure
 	"result": "1\tthe contents\n2\tof the file\n"
@@ -65,14 +65,24 @@ Example:
 
 	WRITE_FILE_DESCRIPTION = `Write the provided contents to a file relative to the current working directory.
 
-Result is returned as JSON in the following format:
+Note: only use this tool when you've been explicitly asked to create or write to a file.
+
+When using this function, you do not need to share the content you intend to write with the user first.
+
+Example result:
 {
 	"message": "success", // if successful, or a different message indicating failure
 }`
 
-	FILE_INSERT_LINES = `Insert lines into a file.`
+	FILE_INSERT_LINES_DESCRIPTION = `Insert lines into a file, must specify path.
 
-	FILE_REPLACE_LINES = `Replace or remove a range of lines within a file.`
+Make sure your inserts match the flow and indentation of surrounding content.`
+
+	FILE_REPLACE_LINES_DESCRIPTION = `Replace or remove a range of lines within a file, must specify path.
+
+Useful for re-writing snippets/blocks of code or entire functions.
+
+Be cautious with your edits. When replacing, ensure the replacement content matches the flow and indentation of surrounding content.`
 )
 
 var AvailableTools = map[string]AvailableTool{
@@ -171,7 +181,7 @@ var AvailableTools = map[string]AvailableTool{
 	"file_insert_lines": {
 		Tool: openai.Tool{Type: "function", Function: openai.FunctionDefinition{
 			Name:        "file_insert_lines",
-			Description: FILE_INSERT_LINES,
+			Description: FILE_INSERT_LINES_DESCRIPTION,
 			Parameters: FunctionParameters{
 				Type: "object",
 				Properties: map[string]FunctionParameter{
@@ -223,7 +233,7 @@ var AvailableTools = map[string]AvailableTool{
 	"file_replace_lines": {
 		Tool: openai.Tool{Type: "function", Function: openai.FunctionDefinition{
 			Name:        "file_replace_lines",
-			Description: FILE_REPLACE_LINES,
+			Description: FILE_REPLACE_LINES_DESCRIPTION,
 			Parameters: FunctionParameters{
 				Type: "object",
 				Properties: map[string]FunctionParameter{