Task 6.2: Tool Decorator Implementation

[github-actions]

Overview

Implement a tool helper function system for TypeScript that allows developers to easily define tools that can be used by Strands agents. This implementation is based on the architectural decision to use Zod 4 with a helper function approach.

Parent Task

This is a sub-task of #40 (Task 06: Create Tool Decorator System)

Architecture Decision Summary

After evaluating TypeBox vs Zod and considering the repository context, the following approach was chosen:

• Schema Library: Zod 4 (includes built-in JSON Schema export)
• API Style: tool() helper function (no decorators)
• Context Injection: Always included as 2nd parameter in callbacks (optional for direct calls)
• Base Implementation: Leverage existing FunctionTool class
• Dependencies: Zod as production dependency

Rationale

• Zod 4 provides both type inference AND JSON Schema export (best of both worlds)
• Helper function approach avoids experimental TypeScript decorators
• Always including context parameter simplifies the API and matches Python SDK behavior
• Building on FunctionTool ensures consistency with existing patterns

Clarified Requirements

Design Decisions (From Review Discussion)

1. Schema Support

• ✅ Zod schemas only for initial implementation
• ✅ Design API to allow future JSON Schema support via function overloading
• ✅ Type inference only works with Zod schemas

2. Callable Behavior

The tool instance supports two usage modes:

Direct Invocation (for testing/standalone use):

const result = await myTool(input, context?)
// - Validates input with Zod
// - Returns unwrapped callback value
// - Throws on validation or execution error  
// - Context parameter is optional

Stream Invocation (Tool interface for agent use):

for await (const event of myTool.stream(context)) {
  // - Validates input with Zod
  // - Returns ToolResult (wrapped)
  // - Catches all errors into error ToolResult
  // - Context from agent is always provided
}

Rationale: This asymmetric pattern (validate input, unwrap output) is consistent with TypeScript best practices (Zod, tRPC, GraphQL). See research comment for detailed analysis.

3. Zod Version

• ✅ Use Zod 4.1.12 (latest stable as of October 2025)
• ✅ Zod 4 has built-in JSON Schema export via .toJsonSchema()
• ✅ No need for zod-to-json-schema library

4. Zod Refinements and Transforms

• ✅ Refinements (.refine()) and transforms (.transform()) are used in validation
• ✅ Leverage Zod's native JSON Schema generation (refinements/transforms may not appear in schema)
• ✅ Apply transforms before passing to callback (Zod handles via .parse())
• ✅ Document limitations in TSDoc

5. Context Parameter

• ✅ Always passed as 2nd parameter to callback
• ✅ Optional for direct invocation (not all tools need it)
• ✅ Required for .stream() method (provided by agent)
• ✅ Contains: toolUse and invocationState

6. Test Coverage

• ✅ Focus on integration testing (our code's behavior)
• ✅ Test common Zod schema types and features
• ✅ Don't extensively test Zod's validation logic (that's Zod's responsibility)
• ✅ 80%+ code coverage required

Work Required

1. Add Zod Dependency

npm install zod@^4.1.12

Files to modify:

• package.json - Add Zod to dependencies

2. Create Tool Helper Function

New file: src/tools/tool-helper.ts

Implement tool() helper function with the following signature:

import { z } from 'zod'
import type { Tool, ToolContext } from './tool'

interface ToolConfig<TInput extends z.ZodType> {
  name: string
  description: string
  inputSchema: TInput
  callback: (
    input: z.infer<TInput>,
    context?: ToolContext
  ) => Promise<unknown> | AsyncGenerator<unknown, unknown, never> | unknown
}

export function tool<TInput extends z.ZodType>(
  config: ToolConfig<TInput>
): Tool & ((input: z.infer<TInput>, context?: ToolContext) => ReturnType<typeof config.callback>) {
  // Implementation details
}

Key requirements:

• Accept Zod schema for type-safe input validation
• Convert Zod schema to JSON Schema for toolSpec.inputSchema
• Wrap callback in FunctionTool or extend it appropriately
• Return a Tool instance that is also callable as a function
• Always pass context as 2nd parameter to callback (optional in type)
• Context parameter is optional for direct calls, required for stream calls
• Handle validation errors gracefully
• Support sync, async, and async generator callbacks

3. Schema Conversion

Function: Convert Zod schemas to JSON Schema format

function zodToJsonSchema(schema: z.ZodType): JSONSchema {
  // Use Zod 4's built-in JSON Schema export
  return schema.toJsonSchema()
}

Requirements:

• Use Zod 4's built-in .toJsonSchema() method
• Refinements and transforms are used in validation but may not appear in generated schema
• Generate proper OpenAPI-compatible JSON Schema

4. Input Validation

Behavior:

• Validate input against Zod schema before calling callback
• For .stream() calls: On validation failure, return error ToolResult (don't throw)
• For direct calls: On validation failure, throw error
• Include clear error messages indicating which fields failed validation

const result = schema.safeParse(input)
if (!result.success) {
  // For stream: return createValidationErrorResult(result.error, toolUseId)
  // For direct call: throw validation error
}

5. Context Parameter Injection

Requirements:

• Context is ALWAYS the 2nd parameter (but optional in type signature)
• Context parameter is optional for direct invocation
• Context parameter is required for .stream() method invocation
• Context includes:
  • toolUse: Contains name, toolUseId, and input
  • invocationState: Caller-provided state
• Properly type the context parameter for TypeScript inference

callback: (input: z.infer<TInput>, context?: ToolContext) => ...

6. Tool Instance with Callable Behavior

Requirements:

• Returned object implements Tool interface
• Returned object is also callable as a function
• Direct call: Validates input, returns unwrapped value, throws on error
• Stream call: Validates input, returns ToolResult, catches all errors
• Supports both .stream() method and direct invocation

const myTool = tool({ ... })

// Works as Tool interface
for await (const event of myTool.stream(context)) { ... }

// Also works as function (context optional)
const result = await myTool(input)
const result2 = await myTool(input, context)

7. Streaming Support

Requirements:

• Detect callback type (sync, async, async generator)
• Wrap non-generator functions to work with stream() method
• Pass through async generator yields as ToolStreamEvents
• Wrap final return value in ToolResult
• Leverage existing FunctionTool streaming logic where possible

8. Error Handling

Requirements:

• For .stream() calls: Always catch errors in callbacks and return error ToolResults
• For direct calls: Let errors throw (no catching)
• Return errors as error ToolResults for stream calls
• Preserve error messages and stack traces for debugging
• Consistent with existing FunctionTool error handling

9. Testing

New file: src/tools/__tests__/tool-helper.test.ts

Test coverage required:

• Tool creation with various Zod schemas
• Type inference works correctly
• JSON Schema generation from Zod schemas using .toJsonSchema()
• Input validation success and failure cases
• Context parameter is optional for direct calls
• Context parameter is always passed correctly to callback
• Callable behavior (direct function invocation)
  • Direct calls validate input and throw on error
  • Direct calls return unwrapped values
  • Direct calls work with and without context
• Stream method behavior
  • Stream calls validate input and return error ToolResult
  • Stream calls return wrapped ToolResult
• Error handling differences between direct and stream calls
• Sync, async, and async generator callbacks
• Complex Zod schemas (nested objects, arrays, unions, etc.)
• Zod refinements and custom error messages
• Zod transforms are applied before callback
• Integration with existing Tool interface
• 80%+ code coverage

10. Documentation

Files to update:

• src/tools/tool-helper.ts - Comprehensive TSDoc comments
• src/tools/index.ts - Export tool helper
• README.md - Add usage examples
• AGENTS.md - Document tool helper patterns

Example usage for documentation:

import { z } from 'zod'
import { tool } from '@strands-agents/sdk'

// Basic tool
const calculator = tool({
  name: 'calculator',
  description: 'Performs arithmetic operations',
  inputSchema: z.object({
    operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
    a: z.number().describe('First operand'),
    b: z.number().describe('Second operand')
  }),
  callback: (input, context) => {
    console.log('Tool use ID:', context?.toolUse.toolUseId)
    switch (input.operation) {
      case 'add': return input.a + input.b
      case 'subtract': return input.a - input.b
      case 'multiply': return input.a * input.b
      case 'divide': return input.a / input.b
    }
  }
})

// Async tool with streaming
const fetchData = tool({
  name: 'fetch_data',
  description: 'Fetches data from an API',
  inputSchema: z.object({
    url: z.string().url(),
    method: z.enum(['GET', 'POST']).default('GET')
  }),
  callback: async function* (input, context) {
    yield 'Fetching data...'
    const response = await fetch(input.url, { method: input.method })
    yield 'Processing response...'
    const data = await response.json()
    return data
  }
})

// Tool with complex schema and transforms
const createUser = tool({
  name: 'create_user',
  description: 'Creates a new user',
  inputSchema: z.object({
    username: z.string().min(3).max(20),
    email: z.string().email(),
    age: z.number().int().positive().optional(),
    name: z.string().transform(s => s.trim().toLowerCase()),
    roles: z.array(z.enum(['admin', 'user', 'guest'])).default(['user'])
  }),
  callback: async (input, context) => {
    const userId = context?.invocationState.userId
    // Create user logic (name will be transformed to lowercase)
    return { id: 'user-123', ...input }
  }
})

// Use as Tool interface (in agent)
for await (const event of calculator.stream(toolContext)) {
  console.log(event)
}

// Or call directly (for testing/standalone)
const result = await calculator({ operation: 'add', a: 5, b: 3 })  // No context needed
const result2 = await calculator({ operation: 'add', a: 5, b: 3 }, context)  // With context

Document both usage modes clearly:

/**
 * Creates a tool from a Zod schema and callback function.
 * 
 * The returned tool can be used in two ways:
 * 
 * 1. **Direct invocation** (testing/standalone):
 *    - Validates input and throws on validation error
 *    - Returns unwrapped callback value
 *    - Context parameter is optional
 * 
 * 2. **Stream invocation** (agent use):
 *    - Validates input and returns error ToolResult on failure
 *    - Returns wrapped ToolResult
 *    - Context parameter is required (provided by agent)
 * 
 * @example
 * const myTool = tool({ ... })
 * 
 * // Direct call
 * const result = await myTool(input)
 * 
 * // Stream call (Tool interface)
 * for await (const event of myTool.stream(context)) { }
 */

Technical Context

Existing Infrastructure

• Tool interface in src/tools/tool.ts
• ToolContext interface with toolUse and invocationState
• FunctionTool class in src/tools/function-tool.ts (leverage for implementation)
• Test patterns in src/tools/__tests__/tool.test.ts

Zod 4 Features to Leverage

• Built-in JSON Schema export via .toJsonSchema()
• Type inference with z.infer<>
• Safe parsing with .safeParse()
• Schema descriptions with .describe()
• Default values and optional fields
• Refinements with .refine()
• Transforms with .transform()

Implementation Strategy

1. Start with basic tool() function that wraps FunctionTool
2. Add Zod schema validation layer
3. Convert Zod schemas to JSON Schema using .toJsonSchema()
4. Implement dual behavior (direct vs stream)
5. Ensure callable behavior works for both modes
6. Add comprehensive tests
7. Document with examples

Exit Criteria

• Architecture decision finalized (Zod 4 + helper function)
• Review complete, all clarifications addressed
• Zod dependency added to package.json
• tool() helper function implemented in src/tools/tool-helper.ts
• Zod schema to JSON Schema conversion works correctly using .toJsonSchema()
• Input validation with Zod works (success and error cases)
• Context parameter optional for direct calls, always passed to callback
• Tool instance is callable as function (both with and without context)
• Direct calls validate and throw, return unwrapped values
• Stream calls validate and catch, return ToolResult
• Tool instance implements Tool interface correctly
• Streaming support for all callback types (sync, async, generator)
• Error handling differs between direct and stream calls
• All unit tests pass with 80%+ coverage
• TSDoc documentation complete (including usage mode differences)
• tool helper exported from src/tools/index.ts
• README.md updated with examples
• AGENTS.md updated with patterns
• No TypeScript errors
• No ESLint errors
• Code properly formatted with Prettier
• Pre-commit hooks pass

Dependencies

• Parent Task: Task 06: Create Tool Decorator System #40 (Task 06: Create Tool Decorator System)
• Depends On:
  • ✓ Task 05: Create Tool Interface (Completed)
  • ✓ Task 6.1: Architecture Decision (Completed)

References

• Python decorator implementation: https://github.com/strands-agents/sdk-python/blob/main/src/strands/tools/decorator.py
• Python context parameter PR: strands-agents/harness-sdk@606f657
• Strands tool documentation: https://strandsagents.com/latest/documentation/docs/user-guide/concepts/tools/python-tools/#python-tool-decorators
• Zod documentation: https://zod.dev/
• Zod GitHub: https://github.com/colinhacks/zod

Review Notes

Clarifications Addressed

1. ✅ Schema Support: Zod-only, but designed for future JSON Schema support
2. ✅ Callable Behavior: Asymmetric pattern (research confirms this is TypeScript best practice)
3. ✅ Zod Version: Zod 4.1.12 confirmed available with built-in JSON Schema
4. ✅ Refinements/Transforms: Use Zod's native JSON Schema generation
5. ✅ Context Parameter: Optional for direct calls, required for stream
6. ✅ Test Coverage: Focus on integration testing, 80%+ coverage

Implementation Notes

• The asymmetric pattern (validate input, unwrap output for direct calls) is consistent with TypeScript ecosystem standards (Zod, tRPC, GraphQL)
• Two error handling modes are intentional and well-documented
• Building on FunctionTool ensures consistency with existing SDK patterns
• Zod 4's built-in .toJsonSchema() simplifies implementation

[zastrowm]

/strands review

Is there a way that tool could accept zod OR a JSONSchema directly - in which case the input argument would not be inferred for the callback? Could that be accomplished via function overloading?

[github-actions]

Repository Analysis & Clarifying Questions

I've analyzed the repository structure and have some questions to ensure proper implementation:

Repository Context

• Existing Infrastructure: FunctionTool class, Tool interface, ToolContext, comprehensive testing patterns
• Dependencies: Currently no Zod dependency in package.json
• Testing: Vitest with 80%+ coverage requirement, uses collectGeneratorEvents helper pattern
• Documentation: AGENTS.md, README.md, and TSDoc requirements established

---

Clarifying Questions

1. Zod vs JSON Schema Support (From @zastrowm's Comment)

Question: Should tool() support BOTH Zod schemas AND direct JSON Schema, or only Zod schemas as currently specified?

Context: @zastrowm asked about function overloading to support both approaches. If we support both:

// Option A: Zod schema (with type inference)
const tool1 = tool({
  name: 'calculator',
  description: 'Calculate',
  inputSchema: z.object({ a: z.number() }),  // Type inference works
  callback: (input, context) => input.a * 2  // `input` is typed as { a: number }
})

// Option B: JSON Schema (no type inference)
const tool2 = tool({
  name: 'calculator',
  description: 'Calculate',
  inputSchema: { type: 'object', properties: { a: { type: 'number' } } },  // No inference
  callback: (input, context) => (input as any).a * 2  // `input` is unknown
})

Recommendation: I suggest Zod-only to maintain type safety and avoid the complexity of supporting two schema systems. Users who prefer JSON Schema can easily convert it to Zod using libraries like json-schema-to-zod.

Decision needed: Zod-only, or support both?

---

2. Callable Behavior Specification

Question: What should the exact behavior be when calling a tool directly as a function?

The issue states the tool should be "callable as a function" with this example:

const result = await calculator({ operation: 'add', a: 5, b: 3 }, context)

Need clarification on:

• Should direct calls validate input against the Zod schema? (I assume yes)
• Should direct calls return a ToolResult or the unwrapped value? (Issue example suggests unwrapped)
• Should validation errors throw or return error ToolResult? (Consistency suggests throw for direct calls)

Proposed behavior:

// Direct call
const result = await myTool(input, context)  // Returns unwrapped value, throws on validation error

// Stream call (via Tool interface)
for await (const event of myTool.stream(context)) { }  // Returns ToolResult, no throwing

Does this match your expectations?

---

3. Zod 4 Availability and JSON Schema Export

Question: Is Zod 4 with built-in JSON Schema export actually available?

The issue mentions "Zod 4 includes built-in JSON Schema export" but also says "check Zod 4 release notes".

Current Status:

• Latest stable Zod version is 3.23.x
• Zod 4 is not yet released as stable
• The zod-to-json-schema library works well with Zod 3.x

Options:

1. Use Zod 3.x + zod-to-json-schema library (stable, proven)
2. Use Zod 4 beta/rc if available (cutting edge, potential instability)
3. Wait for Zod 4 stable release (delays implementation)

Recommendation: Use Zod 3.x with zod-to-json-schema for stability. We can upgrade to Zod 4's built-in export when it's stable.

Decision needed: Which approach should we take?

---

4. Handling Zod Refinements and Transforms

Question: How should we handle Zod's .refine() and .transform() methods?

const schema = z.object({
  email: z.string().email(),
  age: z.number().refine(n => n >= 18, "Must be 18+"),
  name: z.string().transform(s => s.toUpperCase())
})

Considerations:

• Refinements (.refine()): Should these validation rules be included in the JSON Schema sent to the model?

  • Some refinements can't be expressed in JSON Schema (custom logic)
  • Should we include the error messages in descriptions?

• Transforms (.transform()): Should we apply transforms to the input before passing to callback?

  • Transforms change the type (string → uppercase string)
  • LLM doesn't know about transforms
  • Applying transforms could cause confusion

Proposed approach:

1. Refinements: Include in validation (Zod handles), but complex refinements may not appear in JSON Schema
2. Transforms: Apply transforms before passing to callback (Zod handles via .parse())
3. Document limitations: Note in TSDoc that complex refinements may not be visible to the model

Does this approach work for your use cases?

---

5. Context Requirement for Direct Invocation

Question: For direct tool invocation, is it reasonable to require the ToolContext parameter?

// User must provide context even for direct calls
const result = await myTool(input, context)

Consideration: Unlike the .stream() method (which receives ToolContext from the agent), direct calls require the user to construct a ToolContext manually. This may be awkward for simple testing/usage outside an agent.

Alternative: Make context optional for direct calls:

// Direct call without context
const result = await myTool(input)

// Direct call with context
const result = await myTool(input, context)

Current issue spec: States context is always 2nd parameter. Should we keep it required, or make it optional for direct invocation?

---

6. Test Coverage Scope

Question: For the 80%+ test coverage requirement, should we extensively test Zod's validation behavior, or focus on testing our integration with Zod?

Proposed scope:

• ✅ Test that our code correctly calls schema.safeParse()
• ✅ Test handling of validation success/failure
• ✅ Test common Zod schema types (string, number, object, array)
• ✅ Test Zod refinements and transforms integration
• ❌ Don't extensively test Zod's validation logic itself (that's Zod's responsibility)

Does this testing approach meet your expectations?

---

Additional Notes

• No GitHub Workflow Changes Needed: Adding Zod as a dependency will work with existing CI/CD workflows
• Documentation Updates Required: Will update AGENTS.md with tool helper patterns, README.md with usage examples
• Single PR Scope: This task is appropriately sized for a single PR (estimated 3-4 days of work)

Please let me know your preferences on these questions when you have a chance!

[zastrowm]

/strands review update the issue based on my answers below. There's still one open question that more research could be done on

Repository Analysis & Clarifying Questions

I've analyzed the repository structure and have some questions to ensure proper implementation:

Repository Context

• Existing Infrastructure: FunctionTool class, Tool interface, ToolContext, comprehensive testing patterns
• Dependencies: Currently no Zod dependency in package.json
• Testing: Vitest with 80%+ coverage requirement, uses collectGeneratorEvents helper pattern
• Documentation: AGENTS.md, README.md, and TSDoc requirements established

Clarifying Questions

1. Zod vs JSON Schema Support (From @zastrowm's Comment)

Question: Should tool() support BOTH Zod schemas AND direct JSON Schema, or only Zod schemas as currently specified?

Context: @zastrowm asked about function overloading to support both approaches. If we support both:

// Option A: Zod schema (with type inference)
const tool1 = tool({
name: 'calculator',
description: 'Calculate',
inputSchema: z.object({ a: z.number() }), // Type inference works
callback: (input, context) => input.a * 2 // input is typed as { a: number }
})

// Option B: JSON Schema (no type inference)
const tool2 = tool({
name: 'calculator',
description: 'Calculate',
inputSchema: { type: 'object', properties: { a: { type: 'number' } } }, // No inference
callback: (input, context) => (input as any).a * 2 // input is unknown
})
Recommendation: I suggest Zod-only to maintain type safety and avoid the complexity of supporting two schema systems. Users who prefer JSON Schema can easily convert it to Zod using libraries like json-schema-to-zod.

Decision needed: Zod-only, or support both?

Zod only, but try to design it in a way that allows json-schema directly in the future

2. Callable Behavior Specification

Question: What should the exact behavior be when calling a tool directly as a function?

The issue states the tool should be "callable as a function" with this example:

const result = await calculator({ operation: 'add', a: 5, b: 3 }, context)
Need clarification on:

• Should direct calls validate input against the Zod schema? (I assume yes)
• Should direct calls return a ToolResult or the unwrapped value? (Issue example suggests unwrapped)
• Should validation errors throw or return error ToolResult? (Consistency suggests throw for direct calls)

Proposed behavior:

// Direct call
const result = await myTool(input, context) // Returns unwrapped value, throws on validation error

// Stream call (via Tool interface)
for await (const event of myTool.stream(context)) { } // Returns ToolResult, no throwing
Does this match your expectations?

What are general guidelines/best-practices here? It seems weird that input would be "enhanced" but "output" would not be, but I think I am inclined in this approach.

Could you do research/investigation?

3. Zod 4 Availability and JSON Schema Export

Question: Is Zod 4 with built-in JSON Schema export actually available?

The issue mentions "Zod 4 includes built-in JSON Schema export" but also says "check Zod 4 release notes".

Current Status:

• Latest stable Zod version is 3.23.x
• Zod 4 is not yet released as stable
• The zod-to-json-schema library works well with Zod 3.x

Options:

1. Use Zod 3.x + zod-to-json-schema library (stable, proven)
2. Use Zod 4 beta/rc if available (cutting edge, potential instability)
3. Wait for Zod 4 stable release (delays implementation)

Recommendation: Use Zod 3.x with zod-to-json-schema for stability. We can upgrade to Zod 4's built-in export when it's stable.

Decision needed: Which approach should we take?

Zod is on 4.1.12 - your information is outdated

4. Handling Zod Refinements and Transforms

Question: How should we handle Zod's .refine() and .transform() methods?

const schema = z.object({
email: z.string().email(),
age: z.number().refine(n => n >= 18, "Must be 18+"),
name: z.string().transform(s => s.toUpperCase())
})
Considerations:

• Refinements (.refine()): Should these validation rules be included in the JSON Schema sent to the model?

  • Some refinements can't be expressed in JSON Schema (custom logic)
  • Should we include the error messages in descriptions?

• Transforms (.transform()): Should we apply transforms to the input before passing to callback?

  • Transforms change the type (string → uppercase string)
  • LLM doesn't know about transforms
  • Applying transforms could cause confusion

Proposed approach:

1. Refinements: Include in validation (Zod handles), but complex refinements may not appear in JSON Schema
2. Transforms: Apply transforms before passing to callback (Zod handles via .parse())
3. Document limitations: Note in TSDoc that complex refinements may not be visible to the model

Does this approach work for your use cases?

Yes - those are used in Zod validation but not in schema generation. According to Zod:

New — Zod 4 introduces a new feature: native JSON Schema conversion. JSON Schema is a standard for describing the structure of JSON (with JSON). It's widely used in OpenAPI definitions and defining structured outputs for AI.

So we should just leverage what they generate

5. Context Requirement for Direct Invocation

Question: For direct tool invocation, is it reasonable to require the ToolContext parameter?

// User must provide context even for direct calls
const result = await myTool(input, context)
Consideration: Unlike the .stream() method (which receives ToolContext from the agent), direct calls require the user to construct a ToolContext manually. This may be awkward for simple testing/usage outside an agent.

Alternative: Make context optional for direct calls:

// Direct call without context
const result = await myTool(input)

// Direct call with context
const result = await myTool(input, context)
Current issue spec: States context is always 2nd parameter. Should we keep it required, or make it optional for direct invocation?

Don't require it - we'll always pass it as the 2nd argument, but not all function will need it

6. Test Coverage Scope

Question: For the 80%+ test coverage requirement, should we extensively test Zod's validation behavior, or focus on testing our integration with Zod?

Proposed scope:

• ✅ Test that our code correctly calls schema.safeParse()
• ✅ Test handling of validation success/failure
• ✅ Test common Zod schema types (string, number, object, array)
• ✅ Test Zod refinements and transforms integration
• ❌ Don't extensively test Zod's validation logic itself (that's Zod's responsibility)

Does this testing approach meet your expectations?

Yes

Additional Notes

• No GitHub Workflow Changes Needed: Adding Zod as a dependency will work with existing CI/CD workflows
• Documentation Updates Required: Will update AGENTS.md with tool helper patterns, README.md with usage examples
• Single PR Scope: This task is appropriately sized for a single PR (estimated 3-4 days of work)

Please let me know your preferences on these questions when you have a chance!

[github-actions]

Research Complete - Callable Behavior Analysis

I've completed research on the callable behavior pattern you asked about. Here's my analysis:

The Pattern: Asymmetric Input/Output Handling

The proposed asymmetric pattern (validate input, return unwrapped output) is a well-established best practice in TypeScript libraries:

1. Zod Itself

// Validates input, returns typed value, throws on error
const value = schema.parse(input)

// Validates input, returns wrapped result object  
const result = schema.safeParse(input)

2. tRPC Procedures

const userRouter = router({
  getUser: procedure
    .input(z.object({ id: z.string() }))  // Input validated
    .query(({ input }) => {
      return db.user.findUnique({ where: { id: input.id } })  // Output NOT wrapped
    })
})

3. Express Middleware Pattern

app.post('/users', validateBody(userSchema), (req, res) => {
  // req.body validated and enhanced
  res.json(user)  // Response not automatically wrapped
})

4. GraphQL Resolvers

resolvers: {
  Query: {
    user: (parent, args, context) => {
      // args validated against schema
      return db.findUser(args.id)  // Return value not wrapped
    }
  }
}

Why This Pattern Works

Input Validation = Safety

• Ensures function receives valid, well-typed data
• Prevents runtime errors from malformed input
• TypeScript can infer types from schema

Output Wrapping = Interface Compliance

• Only needed when function implements a specific interface
• Direct calls don't need the wrapper
• Keeps function return values simple and usable

Recommended Implementation

// Tool instance implements BOTH behaviors:

// 1. Direct call (testing/standalone use)
const result = await myTool(input, context?)
// ✅ Validates input via Zod
// ✅ Returns actual callback value (unwrapped)
// ✅ Throws on validation or execution error
// ✅ Context is optional
// Use case: Testing, standalone tool usage, composition

// 2. Stream call (Tool interface for agents)  
for await (const event of myTool.stream(context)) {
  // ✅ Validates input via Zod
  // ✅ Returns ToolResult (wrapped)
  // ✅ Catches errors into error ToolResult
  // ✅ Context from agent is always provided
  // Use case: Agent execution, framework integration
}

Trade-offs

Pros:

• ✅ Familiar pattern to TypeScript developers
• ✅ Direct calls feel like normal function calls
• ✅ Stream calls maintain Tool interface contract
• ✅ Consistent with industry best practices (Zod, tRPC, GraphQL)

Cons:

• ⚠️ Two different error handling modes (throw vs catch)
• ⚠️ Documentation must clearly explain both modes
• ⚠️ Developers need to understand which mode they're using

Conclusion

Recommendation: ✅ Proceed with the asymmetric pattern

This is not weird - it's the TypeScript standard. The asymmetry makes sense because:

1. Input validation is universally needed (safety)
2. Output wrapping is only needed for interface compliance (Tool interface)

The pattern is proven in major TypeScript libraries and provides the best developer experience for both use cases.

[github-actions]

✅ Task Review Complete - Ready for Implementation

I've completed the review of this task and updated the issue description with comprehensive implementation requirements.

Summary of Changes

Clarifications Resolved:

1. ✅ Schema support: Zod-only (designed for future JSON Schema support)
2. ✅ Callable behavior: Asymmetric pattern confirmed as TypeScript best practice
3. ✅ Zod version: 4.1.12 with built-in JSON Schema export
4. ✅ Refinements/transforms: Leverage Zod's native JSON Schema generation
5. ✅ Context parameter: Optional for direct calls, required for stream calls
6. ✅ Test coverage: Focus on integration testing (80%+ coverage)

Updated Issue Description:

• Added detailed "Clarified Requirements" section with design decisions
• Updated Zod dependency to version 4.1.12 (not 3.x)
• Clarified dual usage modes (direct invocation vs stream invocation)
• Documented asymmetric pattern rationale with industry examples
• Updated all code examples to reflect optional context parameter
• Added comprehensive documentation requirements for both usage modes
• Updated exit criteria to reflect clarified requirements

Implementation Readiness

✅ This task is ready for implementation:

• All ambiguities have been resolved
• Technical approach is clearly defined
• Requirements are comprehensive and actionable
• Code examples demonstrate expected behavior
• Testing scope is well-defined
• Documentation requirements are clear

Estimated Effort: 3-4 days for a single developer

Key Implementation Points

1. Use Zod 4.1.12 with built-in .toJsonSchema() method
2. Implement dual behavior:
   • Direct calls: validate input, throw errors, return unwrapped values
   • Stream calls: validate input, catch errors, return ToolResult
3. Context parameter: Optional for direct calls, required for stream
4. Build on FunctionTool: Leverage existing implementation
5. Comprehensive testing: 80%+ coverage focusing on integration

The issue is now fully specified and ready for a developer to pick up and implement. No further clarification is needed at this time.

[zastrowm]

/strands implement