diff --git a/docs/src/content/docs/reference/mcp-scripts.md b/docs/src/content/docs/reference/mcp-scripts.md
index 06696f49c5..93359c3c7c 100644
--- a/docs/src/content/docs/reference/mcp-scripts.md
+++ b/docs/src/content/docs/reference/mcp-scripts.md
@@ -7,6 +7,16 @@ sidebar:
 
 The [`mcp-scripts:`](/gh-aw/reference/glossary/#mcp-scripts) element allows you to define custom [MCP](/gh-aw/reference/glossary/#mcp-model-context-protocol) (Model Context Protocol) tools directly in your workflow [frontmatter](/gh-aw/reference/glossary/#frontmatter) using JavaScript, shell scripts, or Python. These tools are generated at runtime and run as an HTTP MCP server **on the GitHub Actions runner, outside the agent container**. The agent reaches the server via `host.docker.internal`, keeping tool execution isolated from the AI sandbox while still providing controlled secret access.
 
+> [!CAUTION]
+> **MCP Scripts run outside the agent sandbox and must only implement READ-ONLY operations.**
+>
+> Because MCP Scripts execute directly on the GitHub Actions runner host — not inside the isolated agent container — they can access the runner's file system, network, and environment without the safety constraints of the sandbox. Implementing **write operations** (creating files, pushing commits, calling mutating APIs, etc.) in MCP Scripts bypasses the audit trail and approval gates that protect your repository.
+>
+> - ✅ **Use MCP Scripts for**: reading data, querying APIs, fetching information, performing calculations.
+> - ❌ **Do not use MCP Scripts for**: writing files, creating issues/PRs, modifying repository content, or any other mutating action.
+>
+> For write operations, use [Safe Output Jobs](/gh-aw/reference/safe-outputs/) or [Custom Safe Output Jobs](/gh-aw/reference/custom-safe-outputs/) instead. These run in a controlled, auditable step that is separate from the AI agent's execution.
+
 ## Quick Start
 
 ```yaml wrap
@@ -336,6 +346,9 @@ Analyze provided text using the `analyze-text` tool and create a discussion with
 
 MCP Scripts tools run on the GitHub Actions **runner host** — outside the agent container — so they can access the runner's file system and environment but are isolated from the AI's own execution environment. Tools also provide secret isolation (only specified env vars are forwarded), process isolation (separate execution), and output sanitization (large outputs saved to files). Only predefined tools are available to agents.
 
+> [!CAUTION]
+> Because MCP Scripts execute outside the sandbox, **only implement READ-ONLY tools**. Write operations (file writes, API mutations, repository changes) must be handled through [Safe Output Jobs](/gh-aw/reference/safe-outputs/) or [Custom Safe Output Jobs](/gh-aw/reference/custom-safe-outputs/), which provide proper audit trails and approval gates.
+
 ## Comparison with Other Options
 
 | Feature | MCP Scripts | Custom MCP Servers | Bash Tool |