> This page is for Agent Handler. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.merge.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server. # Tool Call Logs > What's in the Agent Handler Tool Call Logs, how to filter them, and how to debug a failure end to end from the dashboard. Every tool call that runs through Agent Handler - successful, failed, redacted, blocked - is captured with full context in the [Logs dashboard](https://ah.merge.dev/logs/tool-calls). 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](/merge-agent-handler/observe/api-request-logs). ## What's captured For each tool call, the log row includes: * **Tool name** - namespaced as `__`, 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](#correlating-with-your-agents-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](/merge-agent-handler/observe/stream-logs-to-a-siem) (see the [API reference](/merge-agent-handler/agent-handler) 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](/merge-workforce/rollout/workforce-cli#following-a-prompt-across-both-logs) 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": 1. **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. 2. **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. 3. **Read the arguments.** Did the model pass what you expected? If not, the fix is usually a [Tool Description Override](/merge-agent-handler/build/tools/tool-description-overrides) or a [Tool Input Override](/merge-agent-handler/build/tools/tool-input-overrides) to constrain what the model can produce. 4. **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. 5. **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](/merge-agent-handler/observe/audit-trail#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](/merge-agent-handler/administer/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](/merge-agent-handler/observe/webhooks) to land them in your own warehouse, or [stream them to a SIEM](/merge-agent-handler/observe/stream-logs-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](/merge-agent-handler/secure/violations-and-alerts). ## Next Debug your backend's calls to the Agent Handler API with [API Request Logs](/merge-agent-handler/observe/api-request-logs).