agent2: Clean up tool descriptions (#36619)

schemars was passing along the newlines from the doc comments. This
should make these closer to the markdown file versions we had in the old
agent.

Release Notes:

- N/A

crates/agent2/src/tools/copy_path_tool.rs

@@ -8,16 +8,11 @@ use serde::{Deserialize, Serialize};
 use std::sync::Arc;
 use util::markdown::MarkdownInlineCode;
 
-/// Copies a file or directory in the project, and returns confirmation that the
+/// Copies a file or directory in the project, and returns confirmation that the copy succeeded.
-/// copy succeeded.
-///
 /// Directory contents will be copied recursively (like `cp -r`).
 ///
-/// This tool should be used when it's desirable to create a copy of a file or
+/// This tool should be used when it's desirable to create a copy of a file or directory without modifying the original.
-/// directory without modifying the original. It's much more efficient than
+/// It's much more efficient than doing this by separately reading and then writing the file or directory's contents, so this tool should be preferred over that approach whenever copying is the goal.
-/// doing this by separately reading and then writing the file or directory's
-/// contents, so this tool should be preferred over that approach whenever
-/// copying is the goal.
 #[derive(Debug, Serialize, Deserialize, JsonSchema)]
 pub struct CopyPathToolInput {
     /// The source path of the file or directory to copy.
@@ -33,12 +28,10 @@ pub struct CopyPathToolInput {
     /// You can copy the first file by providing a source_path of "directory1/a/something.txt"
     /// </example>
     pub source_path: String,
-
     /// The destination path where the file or directory should be copied to.
     ///
     /// <example>
-    /// To copy "directory1/a/something.txt" to "directory2/b/copy.txt",
+    /// To copy "directory1/a/something.txt" to "directory2/b/copy.txt", provide a destination_path of "directory2/b/copy.txt"
-    /// provide a destination_path of "directory2/b/copy.txt"
     /// </example>
     pub destination_path: String,
 }

crates/agent2/src/tools/create_directory_tool.rs

@@ -9,12 +9,9 @@ use util::markdown::MarkdownInlineCode;
 
 use crate::{AgentTool, ToolCallEventStream};
 
-/// Creates a new directory at the specified path within the project. Returns
+/// Creates a new directory at the specified path within the project. Returns confirmation that the directory was created.
-/// confirmation that the directory was created.
 ///
-/// This tool creates a directory and all necessary parent directories (similar
+/// This tool creates a directory and all necessary parent directories (similar to `mkdir -p`). It should be used whenever you need to create new directories within the project.
-/// to `mkdir -p`). It should be used whenever you need to create new
-/// directories within the project.
 #[derive(Debug, Serialize, Deserialize, JsonSchema)]
 pub struct CreateDirectoryToolInput {
     /// The path of the new directory.

crates/agent2/src/tools/delete_path_tool.rs

@@ -9,8 +9,7 @@ use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 use std::sync::Arc;
 
-/// Deletes the file or directory (and the directory's contents, recursively) at
+/// Deletes the file or directory (and the directory's contents, recursively) at the specified path in the project, and returns confirmation of the deletion.
-/// the specified path in the project, and returns confirmation of the deletion.
 #[derive(Debug, Serialize, Deserialize, JsonSchema)]
 pub struct DeletePathToolInput {
     /// The path of the file or directory to delete.

crates/agent2/src/tools/edit_file_tool.rs

@@ -34,25 +34,21 @@ const DEFAULT_UI_TEXT: &str = "Editing file";
 ///    - Use the `list_directory` tool to verify the parent directory exists and is the correct location
 #[derive(Debug, Serialize, Deserialize, JsonSchema)]
 pub struct EditFileToolInput {
-    /// A one-line, user-friendly markdown description of the edit. This will be
+    /// A one-line, user-friendly markdown description of the edit. This will be shown in the UI and also passed to another model to perform the edit.
-    /// shown in the UI and also passed to another model to perform the edit.
     ///
-    /// Be terse, but also descriptive in what you want to achieve with this
+    /// Be terse, but also descriptive in what you want to achieve with this edit. Avoid generic instructions.
-    /// edit. Avoid generic instructions.
     ///
     /// NEVER mention the file path in this description.
     ///
     /// <example>Fix API endpoint URLs</example>
     /// <example>Update copyright year in `page_footer`</example>
     ///
-    /// Make sure to include this field before all the others in the input object
+    /// Make sure to include this field before all the others in the input object so that we can display it immediately.
-    /// so that we can display it immediately.
     pub display_description: String,
 
     /// The full path of the file to create or modify in the project.
     ///
-    /// WARNING: When specifying which file path need changing, you MUST
+    /// WARNING: When specifying which file path need changing, you MUST start each path with one of the project's root directories.
-    /// start each path with one of the project's root directories.
     ///
     /// The following examples assume we have two root directories in the project:
     /// - /a/b/backend
@@ -61,22 +57,19 @@ pub struct EditFileToolInput {
     /// <example>
     /// `backend/src/main.rs`
     ///
-    /// Notice how the file path starts with `backend`. Without that, the path
+    /// Notice how the file path starts with `backend`. Without that, the path would be ambiguous and the call would fail!
-    /// would be ambiguous and the call would fail!
     /// </example>
     ///
     /// <example>
     /// `frontend/db.js`
     /// </example>
     pub path: PathBuf,
-
     /// The mode of operation on the file. Possible values:
     /// - 'edit': Make granular edits to an existing file.
     /// - 'create': Create a new file if it doesn't exist.
     /// - 'overwrite': Replace the entire contents of an existing file.
     ///
-    /// When a file already exists or you just created it, prefer editing
+    /// When a file already exists or you just created it, prefer editing it as opposed to recreating it from scratch.
-    /// it as opposed to recreating it from scratch.
     pub mode: EditFileMode,
 }
 

crates/agent2/src/tools/find_path_tool.rs

@@ -31,7 +31,6 @@ pub struct FindPathToolInput {
     /// You can get back the first two paths by providing a glob of "*thing*.txt"
     /// </example>
     pub glob: String,
-
     /// Optional starting position for paginated results (0-based).
     /// When not provided, starts from the beginning.
     #[serde(default)]

crates/agent2/src/tools/grep_tool.rs

@@ -27,8 +27,7 @@ use util::paths::PathMatcher;
 /// - DO NOT use HTML entities solely to escape characters in the tool parameters.
 #[derive(Debug, Serialize, Deserialize, JsonSchema)]
 pub struct GrepToolInput {
-    /// A regex pattern to search for in the entire project. Note that the regex
+    /// A regex pattern to search for in the entire project. Note that the regex will be parsed by the Rust `regex` crate.
-    /// will be parsed by the Rust `regex` crate.
     ///
     /// Do NOT specify a path here! This will only be matched against the code **content**.
     pub regex: String,

crates/agent2/src/tools/list_directory_tool.rs

@@ -10,14 +10,12 @@ use std::fmt::Write;
 use std::{path::Path, sync::Arc};
 use util::markdown::MarkdownInlineCode;
 
-/// Lists files and directories in a given path. Prefer the `grep` or
+/// Lists files and directories in a given path. Prefer the `grep` or `find_path` tools when searching the codebase.
-/// `find_path` tools when searching the codebase.
 #[derive(Debug, Serialize, Deserialize, JsonSchema)]
 pub struct ListDirectoryToolInput {
     /// The fully-qualified path of the directory to list in the project.
     ///
-    /// This path should never be absolute, and the first component
+    /// This path should never be absolute, and the first component of the path should always be a root directory in a project.
-    /// of the path should always be a root directory in a project.
     ///
     /// <example>
     /// If the project has the following root directories:

crates/agent2/src/tools/move_path_tool.rs

@@ -8,14 +8,11 @@ use serde::{Deserialize, Serialize};
 use std::{path::Path, sync::Arc};
 use util::markdown::MarkdownInlineCode;
 
-/// Moves or rename a file or directory in the project, and returns confirmation
+/// Moves or rename a file or directory in the project, and returns confirmation that the move succeeded.
-/// that the move succeeded.
 ///
-/// If the source and destination directories are the same, but the filename is
+/// If the source and destination directories are the same, but the filename is different, this performs a rename. Otherwise, it performs a move.
-/// different, this performs a rename. Otherwise, it performs a move.
 ///
-/// This tool should be used when it's desirable to move or rename a file or
+/// This tool should be used when it's desirable to move or rename a file or directory without changing its contents at all.
-/// directory without changing its contents at all.
 #[derive(Debug, Serialize, Deserialize, JsonSchema)]
 pub struct MovePathToolInput {
     /// The source path of the file or directory to move/rename.

crates/agent2/src/tools/open_tool.rs

@@ -8,19 +8,15 @@ use serde::{Deserialize, Serialize};
 use std::{path::PathBuf, sync::Arc};
 use util::markdown::MarkdownEscaped;
 
-/// This tool opens a file or URL with the default application associated with
+/// This tool opens a file or URL with the default application associated with it on the user's operating system:
-/// it on the user's operating system:
 ///
 /// - On macOS, it's equivalent to the `open` command
 /// - On Windows, it's equivalent to `start`
 /// - On Linux, it uses something like `xdg-open`, `gio open`, `gnome-open`, `kde-open`, `wslview` as appropriate
 ///
-/// For example, it can open a web browser with a URL, open a PDF file with the
+/// For example, it can open a web browser with a URL, open a PDF file with the default PDF viewer, etc.
-/// default PDF viewer, etc.
 ///
-/// You MUST ONLY use this tool when the user has explicitly requested opening
+/// You MUST ONLY use this tool when the user has explicitly requested opening something. You MUST NEVER assume that the user would like for you to use this tool.
-/// something. You MUST NEVER assume that the user would like for you to use
-/// this tool.
 #[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
 pub struct OpenToolInput {
     /// The path or URL to open with the default application.

crates/agent2/src/tools/read_file_tool.rs

@@ -21,8 +21,7 @@ use crate::{AgentTool, ToolCallEventStream};
 pub struct ReadFileToolInput {
     /// The relative path of the file to read.
     ///
-    /// This path should never be absolute, and the first component
+    /// This path should never be absolute, and the first component of the path should always be a root directory in a project.
-    /// of the path should always be a root directory in a project.
     ///
     /// <example>
     /// If the project has the following root directories:
@@ -34,11 +33,9 @@ pub struct ReadFileToolInput {
     /// If you want to access `file.txt` in `directory2`, you should use the path `directory2/file.txt`.
     /// </example>
     pub path: String,
-
     /// Optional line number to start reading on (1-based index)
     #[serde(default)]
     pub start_line: Option<u32>,
-
     /// Optional line number to end reading on (1-based index, inclusive)
     #[serde(default)]
     pub end_line: Option<u32>,

crates/agent2/src/tools/thinking_tool.rs

@@ -11,8 +11,7 @@ use crate::{AgentTool, ToolCallEventStream};
 /// Use this tool when you need to work through complex problems, develop strategies, or outline approaches before taking action.
 #[derive(Debug, Serialize, Deserialize, JsonSchema)]
 pub struct ThinkingToolInput {
-    /// Content to think about. This should be a description of what to think about or
+    /// Content to think about. This should be a description of what to think about or a problem to solve.
-    /// a problem to solve.
     content: String,
 }
 

crates/agent2/src/tools/web_search_tool.rs

@@ -14,7 +14,7 @@ use ui::prelude::*;
 use web_search::WebSearchRegistry;
 
 /// Search the web for information using your query.
-/// Use this when you need real-time information, facts, or data that might not be in your training. \
+/// Use this when you need real-time information, facts, or data that might not be in your training.
 /// Results will include snippets and links from relevant web pages.
 #[derive(Debug, Serialize, Deserialize, JsonSchema)]
 pub struct WebSearchToolInput {