Instrument tool calls

Tool spans explain what an agent attempted outside the model. Record the tool name, sanitized arguments, result metadata, latency, and error state as a child of the generation or reasoning span that initiated it.

Keep secrets and unnecessary personal data out of span payloads. When a tool fails, preserve the error category and retry outcome so the trace distinguishes a provider failure from a bad model decision.

The same trace can contain model generations, retrieval, and multiple tool calls; use parent spans to keep the execution tree readable.

Record a tool call

Wrap a tool function with observe, and its arguments, result, latency and any error are recorded as a child of the step that called it:

import { observe } from "tracify-sdk";

const lookupOrder = observe(
  async function lookupOrder(orderId: string) {
    return orders.find(orderId);
  },
  { type: "tool" },
);

import tracify

@tracify.observe(type="tool")
def lookup_order(order_id):
    return orders.find(order_id)

If an argument is sensitive, pass captureInput: false (capture_input=False in Python) so the arguments stay out of the trace while timing and errors are still recorded. When you already have the result and timing, record it with toolCall instead. See the TypeScript SDK and Python SDK guides.