[BUG] Tools returning undefined/null produce invalid text content '<undefined>'/'<null>' #2529

Checks

• I have updated to the lastest minor and patch version of Strands
• I have checked the documentation and this is not expected behavior
• I have searched ./issues and there are no duplicates of my issue

Strands Version

latest

Node.js Version

20+

Operating System

macOS

Installation Method

npm

Steps to Reproduce

1. Create a tool that doesn't return a value (void/undefined):

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

const greet = tool({
  name: 'greet',
  description: 'Greet someone',
  inputSchema: z.object({ name: z.string() }),
  callback: ({ name }) => {
    console.log(`Hello, ${name}`)
    // no return value
  },
})

const agent = new Agent({ tools: [greet] })
await agent.invoke('Greet Alice')

2. Observe the tool result content block

Expected Behavior

The tool result should either:

• Have status: 'success' with an empty content array (content: []), or
• Contain a minimal valid text like 'OK' or 'success'

This is a common pattern for side-effectful tools (delete a file, send a message, etc.) that don't have a meaningful return value.

For reference, the Python SDK calls json.dumps(None) which produces the string "null", a valid JSON value.

Actual Behavior

The tool result contains new TextBlock('<undefined>') (or '<null>' for null returns). The string <undefined> is not valid JSON and looks like a placeholder/bug to both humans and models.

The relevant code is in src/tools/function-tool.ts, _wrapInToolResult():

if (value === undefined) {
  return new ToolResultBlock({
    toolUseId,
    status: 'success',
    content: [new TextBlock('<undefined>')],
  })
}

Additional Context

Found during bug bash. Severity: P3. The tool still reports status: 'success' which is correct, but the content representation is misleading.

Possible Solution

Replace the undefined/null handling with either an empty content array or a minimal valid text:

if (value === undefined || value === null) {
  return new ToolResultBlock({
    toolUseId,
    status: 'success',
    content: [],
  })
}

Related Issues

No response