Skip to main content
Tool Gateway is in beta.
Tool Gateway records its tool calls in two places. Traces show what your agents did: which tool ran, on which server, as whom, and how the call ended. The audit log shows who called which tool and who changed a policy, for security and compliance reviews. You can record traces in two ways, and use either or both:
  • 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: true on 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 as parallel.
  • 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 as upstream_timeout or tool_call_blocked. none on success.
  • ls_tool_gateway_blocked: true when a policy blocked the call.
For how to filter runs by metadata, see Filter traces.

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 named Tool 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.
Set the headers on each tool call, not once when you create the client, so that each call nests under the run that made it. Tool Gateway writes the run with the API key that made the call. That key must be able to write traces to the agent’s project. A caller that authenticates with only an identity provider token is not traced this way. This form of tracing does not depend on the workspace setting in the next section.

Use LangChain MCP adapters

With langchain-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 the langsmith-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 named tool-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.
  1. Go to Tools > Usage.
  2. Turn on Record tool call traces.
The Usage tab lists the 100 most recent tool calls from the last 7 days, with each call’s tool, server, outcome, latency, and start time. Click a call to open its trace. To see every call, with paging and filters, click View all in tracing.
A change can take a few minutes to apply to tool calls.

Review tool calls in the audit log

Audit logs are available on Enterprise plans.
Tool Gateway records tool calls, and changes to its servers, tool kits, profiles, and policies, in your organization’s audit log. Each event records who acted, when, the operation, and whether it succeeded. A tool call event also names the tool kit, the server, and the tool. The audit log records tool calls only. It does not record requests that list tools. To view the audit log, go to Organization Settings > Audit logs. Viewing it requires the Organization Admin or Organization Operator role. For the API, filters, and retention, see Audit logs. Tool Gateway records these operations:

See also