Task 6.1: Tool Decorator Architecture Decision

[github-actions]

Overview

Evaluate and decide on the architectural approach for implementing a tool decorator/helper system in TypeScript. This decision is critical because TypeScript's runtime limitations differ significantly from Python's runtime introspection capabilities.

Parent Task

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

Work Required

1. Evaluate Approach Options

Option A: TypeScript Decorators with Manual Schema

• Enable experimentalDecorators in tsconfig.json
• Require developers to manually provide inputSchema as JSON Schema
• Provide @tool() decorator syntax similar to Python
• Document that auto-generation of schemas is not possible in TypeScript

Option B: Helper Functions (Extending FunctionTool)

• Keep current FunctionTool pattern, add convenience wrapper
• No experimental features needed
• Different API from Python but more TypeScript-idiomatic
• Still requires manual schema definition

Option C: Zod-Based Schema Definition

• Add Zod as production dependency
• Provide type-safe schema definition
• Convert Zod schemas to JSON Schema at runtime
• Better developer experience than manual JSON Schema
• Can work with either decorators or helper functions

Option D: Build-Time Code Generation

• Create build tool to analyze TypeScript AST
• Extract JSDoc comments and type information at build time
• Generate tool definitions automatically
• Most complex but closest to Python DX

2. Key Decisions to Make

Schema Definition Strategy

• How should developers define input schemas?
• Manual JSON Schema vs Zod vs build-time generation?
• Are we willing to add Zod as a dependency?

API Surface

• Decorator syntax: @tool()
• Helper function: tool()
• Both?

Context Parameter Injection

• How to identify which parameter receives ToolContext?
• Naming convention vs explicit configuration?
• What happens if context: false but function has context parameter?

Description/Documentation

• Require manual description parameter?
• Build-time JSDoc extraction?
• Both with fallback?

Error Handling

• Should raise_error: bool parameter bypass error catching?
• What's the use case for propagating errors vs returning error ToolResults?

Feature Parity vs Idioms

• Aim for Python API parity or adapt to TypeScript idioms?
• Acceptable if DX differs from Python?

Experimental Features

• Use experimentalDecorators: true in tsconfig?
• Or avoid experimental features?

3. Create Proof-of-Concept (Optional but Recommended)

• Implement small POC for top 2-3 candidates
• Compare developer experience
• Evaluate type safety
• Assess maintainability

4. Document Decision

• Create decision document explaining:
  • Chosen approach and rationale
  • Alternatives considered and why rejected
  • API contract and examples
  • Migration path from current FunctionTool (if applicable)
  • Dependencies required (if any)

5. Update Task 6.2 Description

• Provide clear implementation requirements based on chosen approach
• Include concrete examples of desired API
• Specify acceptance criteria

Technical Context

TypeScript Limitations vs Python

Python has:

• Runtime type introspection (get_type_hints())
• Docstring parsing (docstring_parser)
• Schema generation from types (Pydantic)
• Function signature inspection (inspect module)

TypeScript has:

• Type erasure (all types removed at compile time)
• No runtime access to JSDoc comments
• No built-in schema generation
• Limited metadata with reflect-metadata (only basic types)

Existing Repository Patterns

• FunctionTool class wraps callbacks with Tool interface
• No validation libraries currently used
• Strict TypeScript mode enabled
• Minimal production dependencies (AWS SDK only)
• Comprehensive test coverage required (80%+)

Exit Criteria

• All architectural options evaluated with pros/cons
• Decision made on approach (decorators vs helpers vs hybrid)
• Decision made on schema definition strategy
• Decision made on context parameter handling
• Decision made on error handling behavior
• Decision made on dependencies (Zod, reflect-metadata, etc.)
• API contract defined with concrete examples
• Decision document created explaining rationale
• Task 6.2 (Implementation) updated with clear requirements
• Team agreement on chosen approach

Dependencies

• Parent Task: Task 06: Create Tool Decorator System #40 (Task 06: Create Tool Decorator System)
• Blocks: Task 6.2 (Tool Decorator Implementation)

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

[github-actions]

Tool Decorator Architecture Decision - Complete

🎯 Decision Made: Hybrid Approach (Zod + Helper Function)

After comprehensive evaluation of all options, I recommend a two-phase hybrid approach:

• Phase 1: Zod + Helper Function (immediate implementation)
• Phase 2: Decorator Syntax (future enhancement)

📋 Quick Summary

Chosen API:

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

const calculator = tool({
  name: 'calculator',
  description: 'Performs arithmetic operations',
  inputSchema: z.object({
    operation: z.enum(['add', 'subtract']),
    a: z.number().describe('First number'),
    b: z.number().describe('Second number')
  }),
  callback: (input) => {
    return input.operation === 'add' ? input.a + input.b : input.a - input.b
  }
})

✅ Key Decisions

1. Schema Definition Strategy

Decision: Support both Zod schemas (recommended) and manual JSON Schema

Rationale:

• Zod provides single source of truth for types and schemas (no drift)
• Runtime validation catches errors before execution
• Excellent TypeScript inference and developer experience
• Flexibility for users who don't want Zod dependency

2. API Surface

Decision: Export tool() helper function (no decorators initially)

Rationale:

• Avoids experimental TypeScript features
• Works with stable TypeScript today
• TypeScript-idiomatic approach
• Can add decorator syntax later without breaking changes

3. Context Parameter Injection

Decision: Explicit context: true configuration parameter

const emailTool = tool({
  inputSchema: EmailSchema,
  context: true,
  callback: (input, context) => {
    console.log('Tool use ID:', context.toolUse.toolUseId)
    // ...
  }
})

Rationale: Clear, explicit, type-safe

4. Error Handling

Decision: Always catch errors by default, return as error ToolResults

Rationale: Consistent with Python SDK, prevents agent crashes

5. Callable Behavior

Decision: Tool instances are callable as functions

Rationale: Enables easy testing, matches Python SDK behavior

📦 Dependencies

New Production Dependencies:

• zod (~15KB minified) - Schema definition and validation
• zod-to-json-schema (~3KB minified) - Convert Zod to JSON Schema
• Total: ~18KB minified

Justification: Zod is the de facto standard in TypeScript ecosystem (used by tRPC, Remix, Next.js)

🎨 Examples

Basic Tool

const getWeather = tool({
  name: 'get_weather',
  description: 'Gets current weather for a location',
  inputSchema: z.object({
    location: z.string().describe('City name or zip code'),
    unit: z.enum(['celsius', 'fahrenheit']).optional()
  }),
  callback: async (input) => {
    const response = await fetch(`/api/weather?location=${input.location}`)
    const data = await response.json()
    return `Temperature: ${data.temp}°${input.unit || 'celsius'}`
  }
})

With Context

const sendEmail = tool({
  name: 'send_email',
  description: 'Sends an email',
  inputSchema: z.object({
    to: z.string().email(),
    subject: z.string(),
    body: z.string()
  }),
  context: true,
  callback: async (input, context) => {
    const userId = context.invocationState.userId
    await emailService.send({ from: userId, ...input })
    return `Email sent to ${input.to}`
  }
})

Streaming Tool

const processDocument = tool({
  name: 'process_document',
  description: 'Processes a document with progress updates',
  inputSchema: z.object({
    documentId: z.string()
  }),
  callback: async function* (input) {
    yield 'Loading document...'
    const doc = await loadDocument(input.documentId)
    
    yield 'Analyzing...'
    const analysis = await analyze(doc)
    
    return `Document processed: ${analysis.summary}`
  }
})

📊 Alignment with Development Tenets

✅ Simple at any scale - Basic tools are simple: define schema, provide callback
✅ Extensible by design - Supports both Zod and manual schemas, can add decorators later
✅ Composability - Works with existing FunctionTool and Tool interface
✅ Obvious path is happy path - Type errors guide developers, clear error messages
✅ Accessible to humans and agents - Industry-standard patterns, comprehensive docs
✅✅ Embrace common standards - Zod is the de facto TypeScript validation standard

📚 Documentation

Full decision document: .project/decisions/tool-decorator-architecture.md
Implementation task: .project/tasks/task-06.2-implement-tool-helper-function.md

The decision document includes:

• Detailed analysis of all 4 options
• Comparison matrix
• Rationale for each decision
• API contract and examples
• Migration path from FunctionTool
• Future enhancement plans

🔄 Next Steps

1. ✅ Architecture decision documented
2. ✅ Task 6.2 created with detailed implementation requirements
3. ⏭️ [ACTION REQUIRED] Team review and approval of this decision
4. ⏭️ Create pull request (automated creation failed, please use link below)
5. ⏭️ Implement tool helper function (Task 6.2)

🔗 Pull Request

Since automated PR creation failed (403 Forbidden), please create the PR manually:

Create PR Link:
https://github.com/strands-agents/sdk-typescript/compare/main...agent-tasks/6.1?quick_pull=1

Branch: agent-tasks/6.1
Commit: c68526e - "docs: architectural decision for tool decorator system"

The PR includes:

• Comprehensive decision document (.project/decisions/tool-decorator-architecture.md)
• Task 6.2 with detailed implementation requirements

💬 Questions?

I'm ready to iterate on this decision based on team feedback. Key discussion areas:

• Zod as production dependency
• Helper function vs decorator syntax preference
• Context injection API
• Manual JSON Schema support level