feat: support deriving tools from existing tools via inputSchema

strands-ts/src/tools/__tests__/tool-factory.test-d.ts

@@ -0,0 +1,24 @@
+import { describe, it, expectTypeOf } from 'vitest'
+import { z } from 'zod'
+import { tool } from '../tool-factory.js'
+
+describe('tool()', () => {
+  describe('derived tool', () => {
+    const baseTool = tool({
+      name: 'base',
+      inputSchema: z.object({ url: z.string(), method: z.enum(['GET', 'POST']) }),
+      callback: (input) => ({ fetched: input.url }),
+    })
+
+    it('infers input and return types from source tool', () => {
+      const derived = tool({
+        name: 'derived',
+        inputSchema: baseTool,
+        callback: (input) => ({ combined: `${input.method} ${input.url}` }),
+      })
+
+      expectTypeOf(derived.invoke).parameter(0).toEqualTypeOf<{ url: string; method: 'GET' | 'POST' }>()
+      expectTypeOf(derived.invoke).returns.resolves.toEqualTypeOf<{ combined: string }>()
+    })
+  })
+})

strands-ts/src/tools/__tests__/tool-factory.test.ts

@@ -110,4 +110,79 @@ describe('tool factory', () => {
       expect(myTool.description).toBe('')
     })
   })
+
+  describe('DerivedTool (inputSchema as existing tool)', () => {
+    const zodTool = tool({
+      name: 'zod_tool',
+      description: 'A Zod schema tool',
+      inputSchema: z.object({ url: z.string().url(), method: z.enum(['GET', 'POST']) }),
+      callback: async (input) => ({ fetched: input.url, method: input.method }),
+    })
+
+    const functionTool = tool({
+      name: 'function_tool',
+      description: 'A JSON schema tool',
+      inputSchema: { type: 'object', properties: { x: { type: 'number' } } },
+      callback: (input) => `got ${(input as { x: number }).x}`,
+    })
+
+    it('inherits input schema and defaults description from source tool', () => {
+      const derived = tool({
+        name: 'derived_tool',
+        inputSchema: zodTool,
+        callback: async (input) => input.url,
+      })
+
+      expect(derived).toBeInstanceOf(Tool)
+      expect(derived.name).toBe('derived_tool')
+      expect(derived.description).toBe('A Zod schema tool')
+      expect(derived.toolSpec.inputSchema).toStrictEqual(zodTool.toolSpec.inputSchema)
+    })
+
+    it('overrides description when provided', () => {
+      const derived = tool({
+        name: 'derived',
+        description: 'Custom description',
+        inputSchema: zodTool,
+        callback: async (input) => input.url,
+      })
+
+      expect(derived.description).toBe('Custom description')
+    })
+
+    it('delegates to source tool with typed input', async () => {
+      const derived = tool({
+        name: 'derived',
+        inputSchema: zodTool,
+        callback: async (input, context) => {
+          const result = await zodTool.invoke(input, context)
+          return { ...result, wrapped: true }
+        },
+      })
+
+      const result = await derived.invoke({ url: 'https://example.com', method: 'POST' })
+      expect(result).toStrictEqual({ fetched: 'https://example.com', method: 'POST', wrapped: true })
+    })
+
+    it('inherits input schema from a FunctionTool source', async () => {
+      const derived = tool({
+        name: 'derived_json',
+        inputSchema: functionTool,
+        callback: (input) => `wrapped: ${(input as { x: number }).x}`,
+      })
+
+      expect(derived.toolSpec.inputSchema).toStrictEqual(functionTool.toolSpec.inputSchema)
+      expect(await derived.invoke({ x: 42 })).toBe('wrapped: 42')
+    })
+
+    it('preserves Zod validation from source ZodTool', async () => {
+      const derived = tool({
+        name: 'derived',
+        inputSchema: zodTool,
+        callback: async (input) => input.url,
+      })
+
+      await expect(derived.invoke({ url: 'not-a-url', method: 'GET' })).rejects.toThrow()
+    })
+  })
 })

strands-ts/src/tools/tool-factory.ts

@@ -1,4 +1,5 @@
-import type { InvokableTool } from './tool.js'
+import type { InvokableTool, ToolContext } from './tool.js'
+import { Tool } from './tool.js'
 import { FunctionTool } from './function-tool.js'
 import type { FunctionToolConfig } from './function-tool.js'
 import type { JSONValue } from '../types/json.js'
@@ -15,6 +16,29 @@ function isZodType(value: unknown): value is z.ZodType {
   return value instanceof z.ZodType
 }
 
+/**
+ * Configuration for creating a tool that reuses another tool's input schema.
+ *
+ * @typeParam TInput - Input type inferred from the source tool
+ * @typeParam TReturn - Return type of the callback function
+ */
+interface DerivedToolConfig<TInput, TReturn extends JSONValue> {
+  /** The unique name of the tool */
+  name: string
+
+  /** Human-readable description of the tool's purpose. Defaults to the source tool's description. */
+  description?: string
+
+  /** An existing tool whose input schema and types will be reused */
+  inputSchema: InvokableTool<TInput, unknown>
+
+  /** Function that implements the tool logic with typed input from the source tool */
+  callback: (
+    input: TInput,
+    context?: ToolContext
+  ) => AsyncGenerator<JSONValue, TReturn, never> | Promise<TReturn> | TReturn
+}
+
 /**
  * Creates an InvokableTool from a Zod schema and callback function.
  *
@@ -36,11 +60,26 @@ export function tool<TInput extends z.ZodType, TReturn extends JSONValue = JSONV
 export function tool(config: FunctionToolConfig): InvokableTool<unknown, JSONValue>
 
 /**
- * Creates an InvokableTool from either a Zod schema or JSON schema configuration.
+ * Creates an InvokableTool that reuses another tool's input schema.
+ * The callback receives the same typed input as the source tool.
+ *
+ * @typeParam TInput - Input type inferred from the source tool
+ * @typeParam TReturn - Return type of the callback function
+ * @param config - Tool configuration with a source tool as inputSchema
+ * @returns An InvokableTool with input typed from the source tool
+ */
+export function tool<TInput, TReturn extends JSONValue = JSONValue>(
+  config: DerivedToolConfig<TInput, TReturn>
+): InvokableTool<TInput, TReturn>
+
+/**
+ * Creates an InvokableTool from a Zod schema, JSON schema, or existing tool.
  *
  * When a Zod schema is provided as `inputSchema`, input is validated at runtime and
- * the callback receives typed input. When a JSON schema (or no schema) is provided,
- * the callback receives `unknown` input with no runtime validation.
+ * the callback receives typed input. When an existing tool is provided as `inputSchema`,
+ * the callback receives input typed from that tool's generic parameters. When a JSON
+ * schema (or no schema) is provided, the callback receives `unknown` input with no
+ * runtime validation.
  *
  * @example
  * ```typescript
@@ -66,14 +105,45 @@ export function tool(config: FunctionToolConfig): InvokableTool<unknown, JSONVal
  *   },
  *   callback: (input) => `Hello, ${(input as { name: string }).name}!`,
  * })
+ *
+ * // With existing tool (typed from source tool)
+ * const positiveCalculator = tool({
+ *   name: 'positive_calculator',
+ *   description: 'Adds two positive numbers',
+ *   inputSchema: calculator,
+ *   callback: (input) => {
+ *     if (input.a < 0 || input.b < 0) throw new Error('No negatives')
+ *     return calculator.invoke(input)
+ *   },
+ * })
  * ```
  *
  * @param config - Tool configuration
  * @returns An InvokableTool that implements the Tool interface with invoke() method
  */
 export function tool(
-  config: ZodToolConfig<z.ZodType | undefined, JSONValue> | FunctionToolConfig
+  config: ZodToolConfig<z.ZodType | undefined, JSONValue> | FunctionToolConfig | DerivedToolConfig<unknown, JSONValue>
 ): InvokableTool<unknown, JSONValue> {
+  if (config.inputSchema && config.inputSchema instanceof Tool) {
+    const sourceTool = config.inputSchema
+
+    if (sourceTool instanceof ZodTool) {
+      return new ZodTool({
+        name: config.name,
+        description: config.description ?? sourceTool.description,
+        inputSchema: sourceTool.inputSchema,
+        callback: config.callback,
+      } as ZodToolConfig<z.ZodType, JSONValue>)
+    }
+
+    return new FunctionTool({
+      name: config.name,
+      description: config.description ?? sourceTool.description,
+      inputSchema: sourceTool.toolSpec.inputSchema,
+      callback: config.callback,
+    } as FunctionToolConfig)
+  }
+
   if (config.inputSchema && isZodType(config.inputSchema)) {
     return new ZodTool(config as ZodToolConfig<z.ZodType, JSONValue>)
   }

strands-ts/src/tools/zod-tool.ts

@@ -58,9 +58,8 @@ export class ZodTool<TInput extends z.ZodType | undefined, TReturn extends JSONV
 
   /**
    * Zod schema for input validation.
-   * Note: undefined is normalized to z.void() in constructor, so this is always defined.
    */
-  private readonly _inputSchema: z.ZodType
+  readonly inputSchema: TInput extends z.ZodType ? TInput : z.ZodVoid
 
   /**
    * User callback function.
@@ -75,20 +74,20 @@ export class ZodTool<TInput extends z.ZodType | undefined, TReturn extends JSONV
     const { name, description = '', inputSchema, callback } = config
 
     // Normalize undefined to z.void() to simplify logic throughout
-    this._inputSchema = inputSchema ?? z.void()
+    this.inputSchema = (inputSchema ?? z.void()) as TInput extends z.ZodType ? TInput : z.ZodVoid
     this._callback = callback
 
     let generatedSchema: JSONSchema
 
     // Handle z.void() - use default empty object schema
-    if (this._inputSchema instanceof ZodVoid) {
+    if (this.inputSchema instanceof ZodVoid) {
       generatedSchema = {
         type: 'object',
         properties: {},
         additionalProperties: false,
       }
     } else {
-      generatedSchema = zodSchemaToJsonSchema(this._inputSchema)
+      generatedSchema = zodSchemaToJsonSchema(this.inputSchema)
     }
 
     // Create a FunctionTool with a validation wrapper
@@ -101,7 +100,7 @@ export class ZodTool<TInput extends z.ZodType | undefined, TReturn extends JSONV
         toolContext: ToolContext
       ): AsyncGenerator<JSONValue, JSONValue, never> | Promise<JSONValue> | JSONValue => {
         // Only validate if schema is not z.void() (after normalization, it's never undefined)
-        const validatedInput = this._inputSchema instanceof ZodVoid ? input : this._inputSchema.parse(input)
+        const validatedInput = this.inputSchema instanceof ZodVoid ? input : this.inputSchema.parse(input)
         // Execute user callback with validated input
         return callback(validatedInput as ZodInferred<TInput>, toolContext) as
           | AsyncGenerator<JSONValue, JSONValue, never>
@@ -157,7 +156,7 @@ export class ZodTool<TInput extends z.ZodType | undefined, TReturn extends JSONV
    */
   async invoke(input: ZodInferred<TInput>, context?: ToolContext): Promise<TReturn> {
     // Only validate if schema is not z.void() (after normalization, it's never undefined)
-    const validatedInput = this._inputSchema instanceof ZodVoid ? input : this._inputSchema.parse(input)
+    const validatedInput = this.inputSchema instanceof ZodVoid ? input : this.inputSchema.parse(input)
 
     // Execute callback with validated input
     const result = this._callback(validatedInput as ZodInferred<TInput>, context)