diff --git a/internal/mcp/actions.go b/internal/mcp/actions.go
index 48db76a..128596a 100644
--- a/internal/mcp/actions.go
+++ b/internal/mcp/actions.go
@@ -16,7 +16,7 @@ func registerActions(s *sdk.Server, o Options) {
 		name, description string
 		properties        map[string]any
 	}{
-		{"run_command", "Run one local bounded command through broker preparation and approval. Use literal argv or an explicit shell script; 120 second default, 600 maximum. Process and destructive commands always need a person.", map[string]any{"argv": map[string]any{"type": "array", "items": map[string]string{"type": "string"}, "minItems": 1}, "script": map[string]any{"type": "string", "minLength": 1}, "cwd": map[string]string{"type": "string"}, "timeout_seconds": map[string]any{"type": "integer", "minimum": 0, "maximum": 600}, "network": map[string]string{"type": "boolean"}}},
+		{"run_command", "Run one local bounded command through broker preparation and approval. Use literal argv or an explicit shell script; 120 second default, 600 maximum. Process and destructive commands always need a person. Commands run with HOME and TMPDIR in a private, initially empty scratch directory, so tools that default to the home directory see no user caches, config or credentials and act on scratch instead, and with PATH=/usr/bin:/bin:/usr/sbin:/sbin. To run other programs, set PATH in a script, such as PATH=/opt/homebrew/bin:$PATH npm test, since many of them start their interpreter through /usr/bin/env. Writes outside the project and scratch are refused.", map[string]any{"argv": map[string]any{"type": "array", "items": map[string]string{"type": "string"}, "minItems": 1}, "script": map[string]any{"type": "string", "minLength": 1}, "cwd": map[string]string{"type": "string"}, "timeout_seconds": map[string]any{"type": "integer", "minimum": 0, "maximum": 600}, "network": map[string]string{"type": "boolean"}}},
 		{"answer_prompt", "Answer one pending local Claude permission prompt. Always requires a person in every mode.", map[string]any{"id": map[string]string{"type": "string"}, "allow": map[string]string{"type": "boolean"}}},
 		{"ack_inbox", "Acknowledge a local inbox id or all local items.", map[string]any{"id": map[string]string{"type": "string"}, "all": map[string]string{"type": "boolean"}}},
 		{"jump", "Jump to a local session terminal. Never types into the terminal.", map[string]any{"session_id": map[string]string{"type": "integer"}}},
diff --git a/site/src/content/docs/reference/mcp-tools.mdx b/site/src/content/docs/reference/mcp-tools.mdx
index c099661..788dd42 100644
--- a/site/src/content/docs/reference/mcp-tools.mdx
+++ b/site/src/content/docs/reference/mcp-tools.mdx
@@ -378,7 +378,7 @@ No inputs.
 
 ### run_command
 
-Run one local bounded command through broker preparation and approval. Use literal argv or an explicit shell script; 120 second default, 600 maximum. Process and destructive commands always need a person.
+Run one local bounded command through broker preparation and approval. Use literal argv or an explicit shell script; 120 second default, 600 maximum. Process and destructive commands always need a person. Commands run with HOME and TMPDIR in a private, initially empty scratch directory, so tools that default to the home directory see no user caches, config or credentials and act on scratch instead, and with PATH=/usr/bin:/bin:/usr/sbin:/sbin. To run other programs, set PATH in a script, such as PATH=/opt/homebrew/bin:$PATH npm test, since many of them start their interpreter through /usr/bin/env. Writes outside the project and scratch are refused.
 
 | Input | Type | Required | Description |
 |---|---|---|---|