Tool calls

A tool call is a single tool invocation inside a trace. Record it with trace.recordTool() / trace.record_tool() after the tool returns.

Record a tool call

TypeScript
Python

await lemma.trace({ name: "support-agent", input: userMessage }, async (trace) => {
  const docs = await searchDocs(userMessage);

  trace.recordTool({
    name: "search_docs",
    input: { query: userMessage },
    output: docs,
    durationMs: 25,
    toolParameters: { query: "string" },
  });

  return answerFromDocs(docs);
});

def run(trace):
    docs = search_docs(user_message)

    trace.record_tool(
        name="search_docs",
        input={"query": user_message},
        output=docs,
        duration_ms=25,
        tool_parameters={"query": "string"},
    )

    return answer_from_docs(docs)

lemma.trace("support-agent", run, input=user_message)

If the tool belongs under a measured parent span, record it as a child of that span:

TypeScript
Python

const span = trace.startSpan("retrieve-context");
const docs = await searchDocs(userMessage);

span.recordTool({
  name: "search_docs",
  input: { query: userMessage },
  output: docs,
  durationMs: 25,
});

span = trace.start_span(name="retrieve-context")
docs = search_docs(user_message)

tool = trace.start_tool(
    name="search_docs",
    input={"query": user_message},
    parent_id=span.id,
)
tool.end(output=docs, duration_ms=25)

If the helper only has IDs, attach the tool from the client. This detached helper API is TypeScript-specific:

lemma.recordTool({
  traceId,
  parentSpanId: spanId,
  name: "search_docs",
  input: { query },
  output: docs,
  durationMs: 25,
});

traceId is required for detached tools. When the tool belongs under a span, parentSpanId is required; missing IDs warn and no-op. Pass durationMs when you already measured the tool call. If you omit it, Lemma splits the parent span’s remaining unclaimed duration equally across siblings that also omitted duration.

Show a tool call as an assistant message

When a successful tool sends text directly to the user, set userFacingMessage / user_facing_message to the exact text they received. Lemma displays it as an assistant message while preserving complete input and output in the span detail.

TypeScript
Python

const input = { message: "Your order arrives Friday." };
const result = await sendWhatsApp(input);

trace.recordTool({
  name: "send_whatsapp",
  input,
  output: result,
  userFacingMessage: input.message,
});

tool_input = {"message": "Your order arrives Friday."}
result = send_whatsapp(tool_input)

trace.record_tool(
    name="send_whatsapp",
    input=tool_input,
    output=result,
    user_facing_message=tool_input["message"],
)

Lemma does not inspect your tool’s input schema. Omit this field for internal tools or unsuccessful sends; their existing rendering remains unchanged.

Measure a live tool call

Use startTool() / start_tool() when you want a handle before the tool finishes. End it only after the tool returns or fails.

TypeScript
Python

const tool = trace.startTool({
  name: "search_docs",
  input: { query },
});

try {
  const docs = await searchDocs(query);
  tool.end({ output: docs, durationMs: 25 });
  return docs;
} catch (error) {
  tool.end({ error });
  throw error;
}

tool = trace.start_tool(
    name="search_docs",
    input={"query": query},
)

try:
    docs = search_docs(query)
    tool.end(output=docs, duration_ms=25)
    return docs
except Exception as error:
    tool.end(error=error)
    raise

What the SDK records

Field	Client sends	Ingest normalizes to
Tool kind	`type: "tool"`	`openinference.span.kind: "tool"`
Tool name	span `name`	`tool.name`
Arguments	`input`	`input.value`, `ai.toolCall.args`
Result	`output`	`output.value`, `ai.toolCall.result`
User-facing message	`userFacingMessage` / `user_facing_message`	`lemma.tool.kind: "user_message"`, `lemma.tool.message`
Contract props	Native props such as `toolDescription` and `toolParameters`; raw `attributes` for escape-hatch keys	Flattened OpenInference-style attributes

See Native contract props and Client fields vs ingest normalization.

Record failures

TypeScript
Python

try {
  const customer = await lookupCustomer(customerId);
  trace.recordTool({ name: "lookup_customer", input: { customerId }, output: customer });
  return customer;
} catch (error) {
  trace.recordTool({
    name: "lookup_customer",
    input: { customerId },
    status: "ERROR",
    error,
  });
  throw error;
}

try:
    customer = lookup_customer(customer_id)
    trace.record_tool(
        name="lookup_customer",
        input={"customer_id": customer_id},
        output=customer,
    )
    return customer
except Exception as error:
    trace.record_tool(
        name="lookup_customer",
        input={"customer_id": customer_id},
        status="ERROR",
        error=error,
    )
    raise

Capture arguments and results only when safe. Redact secrets, credentials, and sensitive user data before passing them to traced tools.

Getting Started

Instrumentation

Integrations

Connections

Record a tool call

Show a tool call as an assistant message

Measure a live tool call

What the SDK records

Record failures

Next steps

Spans

Threads & context

​Record a tool call

​Show a tool call as an assistant message

​Measure a live tool call

​What the SDK records

​Record failures

​Next steps

Spans

Threads & context

Record a tool call

Show a tool call as an assistant message

Measure a live tool call

What the SDK records

Record failures

Next steps