Tool Call Logs

Every tool call that runs through Agent Handler - successful, failed, redacted, blocked - is captured with full context in the Logs dashboard. This is the artifact you’ll use to debug the agent, audit who did what, and answer the questions your security team will ask once a customer files a support ticket.

This page covers Tool Call Logs - individual tool executions made by the agent. For the underlying HTTP requests Agent Handler made to the provider to complete each tool call, see API Request Logs.

What’s captured

For each tool call, the log row includes:

Tool name - namespaced as <Connector>__<tool>, like slack__post_message.
Registered User - whose credentials ran the call, with a link to their detail page.
Tool Pack - which pack the call came through.
Status - success, error, or blocked-by-rule.
Latency - total time from receipt to response.
Arguments - exactly what the agent passed in, post-redaction.
Result - exactly what was returned, post-redaction.
Redactions - every Security Gateway match on the call, with the rule that fired.
Errors - for failed calls, the error class and message from the Connector.
Custom headers - any X- headers your client sent on the request, useful for tracing.
Request ID - the id Agent Handler assigned the request, returned to the agent in the MCP response _meta and in the X-Request-ID header. Filterable, on an exact match of the full id.
Trace and turn ids - client_trace_id and turn_id, when the calling agent sends them. See Correlating with your agent’s own traces.
Timestamp - when the call started.

Everything is searchable, and the full row is exportable — from the dashboard, or programmatically from the GET /api/v1/logs/tool-calls/ endpoint, which is how you stream them into a SIEM (see the API reference for the schema).

Filtering

The filter bar covers the dimensions you’ll reach for:

Registered User. Find every call a specific end user made. Type to search by origin_user_id or name.
Tool name. Narrow to a single tool, or to all tools from one Connector by selecting the prefix.
Tool Pack. Useful when you have more than one pack and want to scope debugging.
Status. Successful calls only, errors only, blocked-by-rule only.
Date range. Last 15 minutes, last hour, last 24 hours, or a custom window.
Custom header values. If you set X-Mcp-Session-Id or any other X- header on the MCP request, you can filter by it. This is how you correlate a session in your own UI with the underlying tool calls.

Filters compose. “All slack__post_message calls for user_a3f9b2 in the last hour with status error” is one combined query.

Correlating with your agent’s own traces

A tool call is one step inside a larger unit of work: a user prompt that the agent answered with several model requests and several tool calls. Two fields let you reassemble that unit without threading an identifier of your own through every call.

Field	Where it comes from	What it groups
`client_trace_id`	The 32-hex trace id in the W3C `traceparent` header	Every request the agent made while answering one prompt
`turn_id`	`X-Merge-Turn-Id` if you send it, otherwise the `turn_id` inside Codex CLI’s `x-codex-turn-metadata` header	One turn of the conversation

Both are read from the request headers rather than the payload, so they survive redaction. Both are opaque ids, and Agent Handler does not interpret them.

Claude Code sends the same traceparent trace id on every model request and every HTTP MCP tool call in a prompt, but only while its OpenTelemetry tracing is on with an otlp exporter and CLAUDE_CODE_PROPAGATE_TRACEPARENT=1 is set; the Workforce CLI sets all of this with mfw env, and mfw chat sends an X-Merge-Turn-Id per prompt. Codex CLI sends its turn metadata on model requests only, not on tools/call, so for Codex the id appears on the LLM side alone. If you are building your own client, set X-Merge-Turn-Id yourself and it wins over any header-derived value.

The parsing rules match Merge Gateway’s exactly, so for Workforce traffic the same ids appear in both products’ logs and you can join a tool call to the model request that decided to make it.

Both fields are exposed on GET /api/v1/logs/tool-calls/ alongside the rest of the row.

Drilling into a single call

Click any row to open the full call detail. You see:

The full arguments JSON.
The full result JSON.
The redaction trail - every entity matched, which rule, which fields were affected.
The Connector’s request to the third party (URL, method, headers; body redacted) and the third party’s raw response (also redacted).
A latency breakdown across auth, security gateway, Connector dispatch, and third-party round-trip.

For a failed call, you also get the error class (auth_error, not_found, rate_limit_exceeded, connector_error) and the message returned upstream.

Debugging a failure

The flow for “the agent’s tool call didn’t do what I expected”:

Find the call. Filter to the Registered User and the tool, narrow by time. The call should be there within seconds of the agent running.
Check status. If it’s a success but the result was wrong, the issue is upstream - the third party returned what it returned. If it’s an error, read the error class.
Read the arguments. Did the model pass what you expected? If not, the fix is usually a Tool Description Override or a Tool Input Override to constrain what the model can produce.
Read the redaction trail. If a field is missing from the result, a rule probably redacted it. The redaction trail tells you which rule. Adjust the rule, scope it to a different Tool Pack, or accept the redaction.
Check the Connector request. For auth_error, the user’s stored credentials are bad - re-run Link or Magic Link for that Connector. For not_found, the resource doesn’t exist or the user doesn’t have access. For rate_limit_exceeded, you (or your customer) have hit the third party’s quota.

Retention and export

Tool Call Logs are kept for your organization’s data retention window. Past it, individual calls aren’t queryable through the dashboard or the API, and the window also caps how wide a Usage API request can be.

If you need a longer history, forward events as they happen rather than planning to fetch them later. Subscribe to the tool_call and tool_call_error webhooks to land them in your own warehouse, or stream them to a SIEM.

Bulk export is available from the dashboard for any filtered view. CSV with one row per call.

If you’ve passed origin_company_id on your Registered Users, the Company’s detail page has a pre-filtered tool-call view - useful for “show me everything Acme did this week.” For investigation flows starting from a security alert, see Violations and alerts.

Debug your backend’s calls to the Agent Handler API with API Request Logs.