Skip to content

feat(tools): show what a tool call is doing - #2138

Merged
tschellenbach merged 1 commit into
mainfrom
tool-call-display-title
Nov 19, 2026
Merged

tschellenbach merged 1 commit into
mainfrom
tool-call-display-title

Conversation

@tschellenbach

Copy link
Copy Markdown
Member

Why

While a tool runs, apps had only the tool's name and progress to show. The title a tool was declared with (display_title) reached a Chat reply's tool step but not the session socket's tool call state, and a worker's host_tools frame dropped it. Each SDK also gets a lighter way to describe a tool's parameters, which the getstream.io tool calling docs now use.

How it works

tool declared with display_title
├─ a session's own tool ─┐
├─ host_tools (worker) ──┼─> Session.toolTitle(tool)
└─ router's search ──────┘     └─ conversation.ToolTitle: "Searching the web"
                                   when nothing titled it
                                        │
                                        v
          tool_call.started / .progress / .finished  { display_title }

Changes

  • Router: ToolCallState.display_title, dispatch.Tool.DisplayTitle on host_tools, and conversation.ToolTitle shared with the Chat reply's tool step. openapi.yaml and the generated clients are regenerated (Go, JavaScript, Python, Ruby, PHP, .NET). Swift generates no ToolCallState, so it is unchanged.
  • Go: tools.DisplayTitle(title), sent on host_tools.
  • Lighter parameter declarations: typed tools in Kotlin, Swift, Dart and Rust (schemars), keyword blocks and params: in Ruby, Tools::strings in PHP, [Description] records in .NET, docstrings in Python. JavaScript's React useTool is also covered.

Validation

  • Go: internal/session, internal/conversation, internal/dispatch and sdks/go tests; TestACallIsShownDoingWhatItsToolWasDeclaredWith, TestAHostedToolKeepsWhatItsCallsAreShownDoing, TestAHostedFunctionTellsTheRouterWhatItsCallsAreShownDoing. go run ./cmd/openapi leaves the spec unchanged.
  • JavaScript npm test (735 tests), uv run dev.py check (2246 passed), and in Docker: Rust cargo test, .NET (308), PHP (343, plus PHPStan), Ruby (237, plus its generator check), Dart (flutter analyze, generator check, 293), Kotlin :core:testDebugUnitTest. Swift generate.py --check passes.
  • Not run: Swift's tests (no iOS simulator here). One Python test, test_a_user_token_cannot_be_minted_without_a_secret, fails on main as well.

A tool call's state (tool_call.started, .progress, .finished) carries display_title, the title its tool was declared with, or "Searching the web" for the router's own search, the default a Chat reply's tool step already used (conversation.ToolTitle). A worker's host_tools frame takes display_title per tool. Every SDK can declare one: Go's tools.DisplayTitle, and the Python, JavaScript, Kotlin, Swift, Dart, .NET, Ruby, Rust and PHP registries, which also get lighter ways to describe parameters. The generated clients are regenerated; Swift's generates no ToolCallState, so it is unchanged.

Co-authored-by: Cursor <cursoragent@cursor.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant