Tool Gateway is in beta.
- In your agent’s trace: Each tool call appears as a child run under the agent run that made it. Your agent sends LangSmith tracing headers with each call. See Nest tool calls under your agent run.
- In the workspace: Every tool call in the workspace becomes its own trace in one project, whatever client made it. A workspace admin turns this on. See Record every tool call in the workspace.
What a trace records
A Tool Gateway trace records metadata about the call, not the data sent to or returned by the tool. It never contains tool arguments or results. Each trace records:- Tool: The tool’s name on its server, such as
save_issue. - Server: The MCP server or built-in server that the call reached.
- Tool kit: The kit the call came through, if any.
- Acting as: Whose credential the call used: a LangSmith user, an end user named by your backend, an agent, a profile, or the workspace.
- Outcome: How the call ended. See the following table.
- Policies: The policies that blocked the call, if any. See Set policies.
- Timing: The call’s total time in Tool Gateway, and how long the MCP server took to start responding.
To find Tool Gateway runs, filter on these metadata keys:
ls_tool_gateway:trueon every Tool Gateway run.ls_tool_gateway_tool: The tool’s name on its server.ls_tool_gateway_server_id: The server’s ID, or the key of a built-in server, such asparallel.ls_tool_gateway_kit_id: The tool kit’s ID.ls_tool_gateway_outcome: One of the outcomes in the preceding table. Handle values not listed here, because Tool Gateway can add new outcomes.ls_tool_gateway_reason: A short label for why the call ended, such asupstream_timeoutortool_call_blocked.noneon success.ls_tool_gateway_blocked:truewhen a policy blocked the call.
Nest tool calls under your agent run
If you trace your agent in LangSmith, send the agent’s tracing headers with each tool call. Tool Gateway then adds a run namedTool Gateway: <server name> under the agent run that made the call. The run goes in the same project, with the tool_gateway tag.
The headers are the standard LangSmith distributed tracing headers:
langsmith-trace: Identifies the parent run.baggage: Carries the parent’s project, metadata, and tags. The Tool Gateway run inherits the parent’s metadata and tags.
Use LangChain MCP adapters
Withlangchain-mcp-adapters, add the headers in a tool interceptor. This works with any agent built on LangChain, such as one made with create_agent, Deep Agents, or LangGraph.
Use another client
Send thelangsmith-trace and baggage headers from the current run with each tools/call request. In the LangSmith SDKs, run_tree.to_headers() (Python) and runTree.toHeaders() (TypeScript) return them. For details, see Distributed tracing.
Record every tool call in the workspace
Workspace traces record every tool call in the workspace as its own trace, whatever client made the call and whoever the caller is. The traces go to a tracing project namedtool-gateway, which Tool Gateway creates when it records the first call.
Workspace traces are free and do not count toward your trace limits.
Turning workspace traces on or off requires the Workspace Admin role (workspaces:settings:manage). Viewing the traces requires permission to read runs in the tool-gateway project. For the roles, see Role-based access control.
- UI
- API
- Go to Tools > Usage.
- Turn on Record tool call traces.
Review tool calls in the audit log
Audit logs are available on Enterprise plans.
See also
- How Tool Gateway works
- Set policies
- Connect an MCP client to a tool kit
- Distributed tracing
- Audit logs
Connect these docs to your agent of choice via MCP for real-time answers.

