@@ -9,6 +9,8 @@ Zed supports many external agents, including CLI-based ones, through the [Agent
Zed supports [Gemini CLI](https://github.com/google-gemini/gemini-cli) (the reference ACP implementation), [Claude Agent](https://platform.claude.com/docs/en/agent-sdk/overview), [Codex](https://developers.openai.com/codex), [GitHub Copilot](https://github.com/github/copilot-language-server-release), and [additional agents](#add-more-agents) you can configure.
+For Zed's built-in agent and the full list of tools it can use natively, see [Agent Tools](./tools.md).
+
> Note that Zed's interaction with external agents is strictly UI-based; the billing, legal, and terms arrangement is directly between you and the agent provider.
> Zed does not charge for use of external agents, and our [zero-data retention agreements/privacy guarantees](./ai-improvement.md) are **_only_** applicable for Zed's hosted models.
@@ -19,10 +19,14 @@ Gets errors and warnings for either a specific file or the entire project, usefu
When a path is provided, shows all diagnostics for that specific file.
When no path is provided, shows a summary of error and warning counts for all files in the project.
+**Example:** After editing `src/parser.rs`, call `diagnostics` with that path to check for type errors immediately. After a larger refactor touching many files, call it without a path to see a project-wide count of errors before deciding what to fix next.
+
### `fetch`
Fetches a URL and returns the content as Markdown. Useful for providing docs as context.
+**Example:** Fetching a library's changelog page to check whether a breaking API change was introduced in a recent version before writing integration code.
+
### `find_path`
Quickly finds files by matching glob patterns (like "\*_/_.js"), returning matching file paths alphabetically.
@@ -31,6 +35,8 @@ Quickly finds files by matching glob patterns (like "\*_/_.js"), returning match
Searches file contents across the project using regular expressions, preferred for finding symbols in code without knowing exact file paths.
+**Example:** To find every call site of a function before renaming it, search for `parse_config\(` — the regex matches the function name followed by an opening parenthesis, filtering out comments or variable names that happen to contain the string.
+
### `list_directory`
Lists files and directories in a given path, providing an overview of filesystem contents.
@@ -55,6 +61,8 @@ Allows the Agent to work through problems, brainstorm ideas, or plan without exe
Searches the web for information, providing results with snippets and links from relevant web pages, useful for accessing real-time information.
+**Example:** Looking up whether a known bug in a dependency has been patched in a recent release, or finding the current API signature for a third-party library when the local docs are out of date.
+
## Edit Tools
### `copy_path`
@@ -73,6 +81,8 @@ Deletes a file or directory (including contents recursively) at the specified pa
Edits files by replacing specific text with new content.
+**Example:** Updating a function signature — the agent identifies the exact lines to replace and provides the updated version, leaving the surrounding code untouched. For widespread renames, it pairs this with `grep` to find every occurrence first.
+
### `move_path`
Moves or renames a file or directory in the project, performing a rename if only the filename differs.
@@ -89,8 +99,12 @@ Saves files that have unsaved changes. Used when files need to be saved before f
Executes shell commands and returns the combined output, creating a new shell process for each invocation.
+**Example:** After editing a Rust file, run `cargo test --package my_crate 2>&1 | tail -30` to confirm the changes don't break existing tests. Or run `git diff --stat` to review which files have been modified before wrapping up a task.
+
## Other Tools
### `spawn_agent`
-Spawns a subagent with its own context window to perform a delegated task. Each subagent has access to the same tools as the parent agent.
+Spawns a subagent with its own context window to perform a delegated task. Useful for running parallel investigations, completing self-contained tasks, or performing research where only the outcome matters. Each subagent has access to the same tools as the parent agent.
+
+**Example:** While refactoring the authentication module, spawn a subagent to investigate how session tokens are validated elsewhere in the codebase. The parent agent continues its work and reviews the subagent's findings when it completes — keeping both context windows focused on a single task.