docs: add custom tools section to plugins documentation

1 files changed, 34 insertions, 0 deletions

diff --git a/packages/web/src/content/docs/plugins.mdx b/packages/web/src/content/docs/plugins.mdx
index 071f1d427..72758e8a3 100644
--- a/packages/web/src/content/docs/plugins.mdx
+++ b/packages/web/src/content/docs/plugins.mdx
@@ -103,3 +103,37 @@ export const EnvProtection = async ({ project, client, $, directory, worktree })
   }
 }
 ```
+
+---
+
+### Custom tools
+
+Create custom tools that opencode can use:
+
+```ts title=".opencode/plugin/custom-tools.ts"
+import type { Plugin, tool } from "@opencode-ai/plugin"
+
+export const CustomToolsPlugin: Plugin = async (ctx) => {
+  return {
+    tool: {
+      mytool: tool((zod) => ({
+        description: "This is a custom tool",
+        args: {
+          foo: zod.string(),
+        },
+        async execute(args, ctx) {
+          return `Hello ${args.foo}!`
+        },
+      })),
+    },
+  }
+}
+```
+
+The `tool` helper creates a custom tool that opencode can call. It takes a Zod schema function and returns a tool definition with:
+
+- `description`: What the tool does
+- `args`: Zod schema for the tool's arguments
+- `execute`: Function that runs when the tool is called
+
+Your custom tools will be available to opencode alongside built-in tools.