Address some feedback in the tools documentation (#5827)

docs/concepts/tools.md

@@ -2,8 +2,8 @@
 
 Tools are Python packages that provide command-line interfaces. Tools can be invoked without
 installation using `uvx`, in which case their dependencies are installed in a temporary virtual
-environment isolated from the current project. Alternatively, tools can be installed with
-`uv tool install`, in which case their executables are placed in the `PATH` — an isolated virtual
+environment isolated from the current project. Tools can also be installed with `uv tool install`,
+in which case their executables are [available on the `PATH`](#the-path) — an isolated virtual
 environment is still used but it is not treated as disposable.
 
 !!! note
@@ -13,9 +13,12 @@ environment is still used but it is not treated as disposable.
 
 ## Tool environments
 
-Tools are installed into virtual environments which are created in the uv tools directory. When
-running tools with `uvx` or `uv tool run`, the virtual environments are stored in the uv cache
-directory and are treated as disposable.
+When running a tool with `uvx` or `uv tool run`, a virtual environment is stored in the uv cache
+directory and is treated as disposable. The environment is cached to reduce the overhead of
+invocations.
+
+When installing a tool with `uv tool install`, a virtual environment is created in the uv tools
+directory.
 
 ### Tools directory
 
@@ -67,12 +70,14 @@ All tool environment mutations will reinstall the tool executables, even if they
 
 ### Including additional dependencies
 
-Additional packages can be included during tool invocations and installations:
+Additional packages can be included during tool invocations:
 
 ```console
-$ uvx --with <extra-package> <tool-package>
+$ uvx --with <extra-package> <tool>
 ```
 
+And installations:
+
 ```console
 $ uv tool install --with <extra-package> <tool-package>
 ```
@@ -90,13 +95,13 @@ will fail and the command will error.
 
 ## Tool executables
 
-Tool executables are all console entry points, script entry points, and binary scripts provided by a
-Python package. Tool executables are symlinked into the `bin` directory on Unix and copied on
+Tool executables include all console entry points, script entry points, and binary scripts provided
+by a Python package. Tool executables are symlinked into the `bin` directory on Unix and copied on
 Windows.
 
-### `bin` directory
+### The `bin` directory
 
-Executables are installed into the user's `bin` directory following the XDG standard, e.g.,
+Executables are installed into the user `bin` directory following the XDG standard, e.g.,
 `~/.local/bin`. Unlike other directory schemes in uv, the XDG standard is used on _all platforms_
 notably including Windows and macOS — there is no clear alternative location to place executables on
 these platforms. The installation directory is determined from the first available environment
@@ -114,13 +119,13 @@ The `bin` directory must be in the `PATH` variable for tool executables to be av
 shell. If it is not in the `PATH`, a warning will be displayed. The `uv tool update-shell` command
 can be used to add the `bin` directory to the `PATH` in common shell configuration files.
 
-### Overriding executables
+### Overwriting executables
 
 Installation of tools will not overwrite executables in the `bin` directory that were not previously
 installed by uv. For example, if `pipx` has been used to install a tool, `uv tool install` will
 fail. The `--force` flag can be used to override this behavior.
 
-## `uv tool run` vs `uv run`
+## Relationship to `uv run`
 
 The invocation `uv tool run <name>` is nearly equivalent to:
 
@@ -135,3 +140,4 @@ However, there are a couple notable differences when using uv's tool interface:
 - The `--no-project` flag is not needed — tools are always run isolated from the project.
 - If a tool is already installed, `uv tool run` will use the installed version but `uv run` will
   not.
+- The project will be built and installed instead of using an editable installation

docs/guides/tools.md

@@ -3,7 +3,7 @@
 Many Python packages provide applications that can be used as tools. uv has specialized support for
 easily invoking and installing tools.
 
-## Using `uvx`
+## Running tools
 
 The `uvx` command invokes a tool without installing it.
 
@@ -39,9 +39,11 @@ $ uvx pycowsay hello from uv
 
 ```
 
+Tools are installed into temporary, isolated environmnets when using `uvx`.
+
 ## Commands with different package names
 
-When you invoke `uvx ruff`, uv installs the `ruff` package which provides the `ruff` command.
+When `uvx ruff` is invoked, uv installs the `ruff` package which provides the `ruff` command.
 However, sometimes the package and command names differ.
 
 The `--from` option can be used to invoke a command from a specific package, e.g. `http` which is
@@ -77,7 +79,7 @@ Note the `@` syntax cannot be used for anything other than an exact version.
 
 The `--from` option can also be used to install from alternative sources.
 
-To pull from git:
+For example, to pull from git:
 
 ```console
 $ uvx --from git+https://github.com/httpie/cli httpie
@@ -93,8 +95,8 @@ $ uvx --with mkdocs-material mkdocs --help
 
 ## Installing tools
 
-If a tool is used often, it can be useful to install it to a persistent environment and add it to
-the `PATH` instead of invoking `uvx` repeatedly.
+If a tool is used often, it is useful to install it to a persistent environment and add it to the
+`PATH` instead of invoking `uvx` repeatedly.
 
 To install `ruff`: