docs: clarify tool name collision precedence (#14313)

Co-authored-by: Aiden Cline <[email protected]>

2 files changed, 30 insertions, 0 deletions

diff --git a/packages/web/src/content/docs/custom-tools.mdx b/packages/web/src/content/docs/custom-tools.mdx
index 80a192369..4586343f0 100644
--- a/packages/web/src/content/docs/custom-tools.mdx
+++ b/packages/web/src/content/docs/custom-tools.mdx
@@ -79,6 +79,32 @@ This creates two tools: `math_add` and `math_multiply`.
 
 ---
 
+#### Name collisions with built-in tools
+
+Custom tools are keyed by tool name. If a custom tool uses the same name as a built-in tool, the custom tool takes precedence.
+
+For example, this file replaces the built-in `bash` tool:
+
+```ts title=".opencode/tools/bash.ts"
+import { tool } from "@opencode-ai/plugin"
+
+export default tool({
+  description: "Restricted bash wrapper",
+  args: {
+    command: tool.schema.string(),
+  },
+  async execute(args) {
+    return `blocked: ${args.command}`
+  },
+})
+```
+
+:::note
+Prefer unique names unless you intentionally want to replace a built-in tool. If you want to disable a built in tool but not override it, use [permissions](/docs/permissions).
+:::
+
+---
+
 ### Arguments
 
 You can use `tool.schema`, which is just [Zod](https://zod.dev), to define argument types.
diff --git a/packages/web/src/content/docs/plugins.mdx b/packages/web/src/content/docs/plugins.mdx
index 411b827d2..a8be79821 100644
--- a/packages/web/src/content/docs/plugins.mdx
+++ b/packages/web/src/content/docs/plugins.mdx
@@ -308,6 +308,10 @@ The `tool` helper creates a custom tool that opencode can call. It takes a Zod s
 
 Your custom tools will be available to opencode alongside built-in tools.
 
+:::note
+If a plugin tool uses the same name as a built-in tool, the plugin tool takes precedence.
+:::
+
 ---
 
 ### Logging