Tool

TypeScript SDK reference

A tool invocation. Emits an execute_tool span carrying the tool name, the JSON-encoded arguments, the tool-call id, and the result.

Created by weave.startTool() (or turn.startTool(), or llm.startTool()) and terminated with end(). Assign result before calling end() to record the tool’s output on the span.

Defined in: src/genai/tool.ts:43

Example

const tool = weave.startTool({
  name: tc.function.name,
  args: tc.function.arguments,
  toolCallId: tc.id,
});
try {
  tool.result = await wikipediaSearch(JSON.parse(tc.function.arguments));
} finally {
  tool.end();
}

Extends

• SpanBase

Properties

args

readonly args: string

Defined in: src/genai/tool.ts:52

---

name

readonly name: string

Defined in: src/genai/tool.ts:51

---

result

optional result: string

Tool output as a string. Recorded on gen_ai.tool.call.result at end().

Defined in: src/genai/tool.ts:47

---

toolCallId

readonly toolCallId: string

Defined in: src/genai/tool.ts:53

Methods

addEvent()

Deprecated. Record this data via setAttributes instead. OpenTelemetry is phasing out the Span Event API (Span.addEvent). This method still works and existing span-event data stays valid. See https://opentelemetry.io/blog/2026/deprecating-span-events/

addEvent(name, attributes?, startTime?): this

Add a named event to the span. Useful for marking non-span moments such as context compaction, tool-loop detection, or guardrail trips. Warns and no-ops after end(). Mirrors OTel Span.addEvent.

Defined in: src/genai/spanBase.ts:82

Parameters

name

string

attributes?

Attributes

startTime?

TimeInput

Returns

this

Example

span.addEvent('context_compacted', {removedMessages: 12});

Inherited from

SpanBase.addEvent

---

end()

end(opts?): void

Flush result to the span and close it. Idempotent. Pass error to mark the span as failed; pass endTime to backdate the close.

Defined in: src/genai/tool.ts:87

Parameters

opts?

SpanEndOptions

Returns

void

---

setAttributes()

setAttributes(attributes): this

Set multiple attributes on the span at once. Warns and no-ops after end(). Mirrors OTel Span.setAttributes (and the Python SDK’s set_attributes).

Defined in: src/genai/spanBase.ts:63

Parameters

attributes

Attributes

Returns

this

Example

span.setAttributes({'weave.tag': 'prod', 'gen_ai.response.id': id});

Inherited from

SpanBase.setAttributes