diff --git a/packages/core/src/plugin/promise.ts b/packages/core/src/plugin/promise.ts
index f372a9fbab..ec379e2ce6 100644
--- a/packages/core/src/plugin/promise.ts
+++ b/packages/core/src/plugin/promise.ts
@@ -1,7 +1,7 @@
 export * as PluginPromise from "./promise"
 
 import { Plugin } from "@opencode-ai/plugin/v2/effect"
-import type { AnyTool, RegisterOptions } from "@opencode-ai/plugin/v2/tool"
+import type { AnyTool } from "@opencode-ai/plugin/v2/tool"
 import { Effect, Scope, Stream } from "effect"
 import { Tool } from "../tool/tool"
 
@@ -114,8 +114,7 @@ export function fromPromise(plugin: PromisePlugin) {
               register(
                 host.tool.transform((draft) =>
                   callback({
-                    add: (name: string, tool: AnyTool, options?: RegisterOptions) =>
-                      draft.add(name, fromPromiseTool(tool), options),
+                    add: (tool: AnyTool) => draft.add(tool.name, fromPromiseTool(tool), tool.options),
                   }),
                 ),
               ),
diff --git a/packages/core/test/plugin/promise.test.ts b/packages/core/test/plugin/promise.test.ts
index 443cc0a8e4..e521545db6 100644
--- a/packages/core/test/plugin/promise.test.ts
+++ b/packages/core/test/plugin/promise.test.ts
@@ -106,7 +106,8 @@ describe("fromPromise", () => {
         id: "promise-tool",
         setup: async (ctx) => {
           await ctx.tool.transform((tools) => {
-            tools.add("hello", {
+            tools.add({
+              name: "hello",
               description: "Hello",
               input: Schema.Struct({ name: Schema.String }),
               output: Schema.String,
diff --git a/packages/docs/plugins.mdx b/packages/docs/plugins.mdx
index 398a79ce12..880b65cbac 100644
--- a/packages/docs/plugins.mdx
+++ b/packages/docs/plugins.mdx
@@ -282,7 +282,8 @@ export default Plugin.define({
   id: "acme.greeting",
   setup: async (ctx) => {
     await ctx.tool.transform((tools) => {
-      tools.add("greeting", {
+      tools.add({
+        name: "greeting",
         description: "Create a greeting",
         input: Schema.Struct({ name: Schema.String }),
         output: Schema.String,
@@ -295,8 +296,8 @@ export default Plugin.define({
 
 Unsupported characters in tool and group names are normalized to underscores.
 The resulting exposed key must begin with a letter and contain at most 64
-letters, digits, underscores, or hyphens. `tools.add` also accepts
-`{ group, deferred }`:
+letters, digits, underscores, or hyphens. Set `options` on the declaration to
+configure registration with `{ group, deferred }`:
 
 - `group` prefixes and groups the exposed tool name.
 - `deferred: true` makes the tool available through the deferred `execute`
diff --git a/packages/plugin/src/v2/promise/README.md b/packages/plugin/src/v2/promise/README.md
index 1310af5d13..8d2984bf92 100644
--- a/packages/plugin/src/v2/promise/README.md
+++ b/packages/plugin/src/v2/promise/README.md
@@ -91,7 +91,8 @@ Promise tools use plain object declarations with async executors:
 import { Schema } from "effect"
 
 await ctx.tool.transform((tools) => {
-  tools.add("echo", {
+  tools.add({
+    name: "echo",
     description: "Echo text",
     input: Schema.Struct({ text: Schema.String }),
     output: Schema.Struct({ text: Schema.String }),
diff --git a/packages/plugin/src/v2/promise/tool.ts b/packages/plugin/src/v2/promise/tool.ts
index 2175e78508..c804f1d1eb 100644
--- a/packages/plugin/src/v2/promise/tool.ts
+++ b/packages/plugin/src/v2/promise/tool.ts
@@ -15,6 +15,8 @@ export type Definition<
   Output extends SchemaType<any>,
   Structured extends SchemaType<any> = Output,
 > = {
+  readonly name: string
+  readonly options?: RegisterOptions
   readonly description: string
   readonly input: Input
   readonly output: Output
@@ -34,6 +36,8 @@ export type Definition<
 }
 
 export type DynamicDefinition = {
+  readonly name: string
+  readonly options?: RegisterOptions
   readonly description: string
   readonly jsonSchema: JsonSchema.JsonSchema
   readonly outputSchema?: JsonSchema.JsonSchema
@@ -73,8 +77,8 @@ export interface ToolDraft {
     Input extends SchemaType<any>,
     Output extends SchemaType<any>,
     Structured extends SchemaType<any> = Output,
-  >(name: string, tool: Definition<Input, Output, Structured>, options?: RegisterOptions): void
-  add(name: string, tool: DynamicDefinition, options?: RegisterOptions): void
+  >(tool: Definition<Input, Output, Structured>): void
+  add(tool: DynamicDefinition): void
 }
 
 export interface ToolHooks {