From 5f2945ae71dc8d44369a313bc6466c74e991eaf4 Mon Sep 17 00:00:00 2001
From: Dax Raad <d@ironbay.co>
Date: Thu, 18 Sep 2025 04:29:08 -0400
Subject: [PATCH] docs: add custom tools section to plugins documentation

---
 packages/web/src/content/docs/plugins.mdx | 34 +++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/packages/web/src/content/docs/plugins.mdx b/packages/web/src/content/docs/plugins.mdx
index 071f1d42..72758e8a 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.