{ "openapi": "3.1.1", "info": { "title": "AI Tool-Call Trace Explorer API", "version": "1.0.0", "summary": "Paste an agent transcript: see every tool call in order, with errors, timings, retries and loops.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://toolcalltraceexplorer.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Paste an agent transcript: see every tool call in order, with errors, timings, retries and loops.", "description": "Reads an AI agent transcript – OpenAI chat messages with tool_calls, OpenAI Responses function_call items, Anthropic messages with tool_use/tool_result blocks, or generic JSONL events – and rebuilds the ordered timeline of tool calls with (truncated) inputs and outputs, errors, durations, repeated identical calls (retries and loops), per-tool statistics and the slowest calls. Only execution events are analysed; hidden reasoning is never reconstructed.\n\nMethodology:\n- OpenAI chat: assistant tool_calls are matched to role \"tool\" messages by tool_call_id (legacy function_call by name). OpenAI Responses: function_call ↔ function_call_output by call_id. Anthropic: tool_use ↔ tool_result by tool_use_id; is_error is respected.\n- Generic events: start/end pairs are matched by id (or the latest open call of the same tool); single events with input + output/error count as complete calls. Durations come from duration_ms or end − start timestamps.\n- A result counts as an error when it is flagged (is_error, error field, error/fail event type) or its text starts with error/exception/traceback or mentions an HTTP 4xx/5xx status, a timeout, ENOENT or “permission denied”.\n- Repeats: calls with the same tool name and canonically identical arguments (key order ignored). ≥ loop threshold → loop; otherwise a repeat after a failed attempt → retry; else duplicate.\n- Reasoning/thinking blocks are counted but never displayed or reconstructed; only execution events (calls and results) are shown.", "tags": [ "ai-infra" ], "x-mcp-tool": "tool_call_trace_explorer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallTraceExplorerInput" }, "examples": { "example1": { "summary": "OpenAI chat transcript with a retry and a loop", "value": { "trace": "[{\"role\":\"user\",\"content\":\"What is the weather in Berlin and convert 20 EUR to USD?\"},{\"role\":\"assistant\",\"content\":null,\"tool_calls\":[{\"id\":\"call_1\",\"type\":\"function\",\"function\":{\"name\":\"get_weather\",\"arguments\":\"{\\\"city\\\":\\\"Berlin\\\"}\"}},{\"id\":\"call_2\",\"type\":\"function\",\"function\":{\"name\":\"convert_currency\",\"arguments\":\"{\\\"amount\\\":20,\\\"from\\\":\\\"EUR\\\",\\\"to\\\":\\\"USD\\\"}\"}}]},{\"role\":\"tool\",\"tool_call_id\":\"call_1\",\"content\":\"{\\\"temp_c\\\":14,\\\"conditions\\\":\\\"cloudy\\\"}\"},{\"role\":\"tool\",\"tool_call_id\":\"call_2\",\"content\":\"Error: rate limit exceeded (429)\"},{\"role\":\"assistant\",\"content\":null,\"tool_calls\":[{\"id\":\"call_3\",\"type\":\"function\",\"function\":{\"name\":\"convert_currency\",\"arguments\":\"{\\\"amount\\\":20,\\\"from\\\":\\\"EUR\\\",\\\"to\\\":\\\"USD\\\"}\"}}]},{\"role\":\"tool\",\"tool_call_id\":\"call_3\",\"content\":\"{\\\"result\\\":21.7}\"},{\"role\":\"assistant\",\"content\":null,\"tool_calls\":[{\"id\":\"call_4\",\"type\":\"function\",\"function\":{\"name\":\"search_web\",\"arguments\":\"{\\\"q\\\":\\\"Berlin weather tomorrow\\\"}\"}}]},{\"role\":\"tool\",\"tool_call_id\":\"call_4\",\"content\":\"No results\"},{\"role\":\"assistant\",\"content\":null,\"tool_calls\":[{\"id\":\"call_5\",\"type\":\"function\",\"function\":{\"name\":\"search_web\",\"arguments\":\"{\\\"q\\\":\\\"Berlin weather tomorrow\\\"}\"}}]},{\"role\":\"tool\",\"tool_call_id\":\"call_5\",\"content\":\"No results\"},{\"role\":\"assistant\",\"content\":null,\"tool_calls\":[{\"id\":\"call_6\",\"type\":\"function\",\"function\":{\"name\":\"search_web\",\"arguments\":\"{\\\"q\\\":\\\"Berlin weather tomorrow\\\"}\"}}]},{\"role\":\"tool\",\"tool_call_id\":\"call_6\",\"content\":\"No results\"},{\"role\":\"assistant\",\"content\":\"Berlin is 14 °C and cloudy; 20 EUR is about 21.70 USD.\"}]" } }, "example2": { "summary": "Generic JSONL events with timings", "value": { "format": "events", "trace": "{\"ts\":\"2026-10-12T09:00:00.000Z\",\"type\":\"tool_start\",\"id\":\"a\",\"name\":\"read_file\",\"input\":{\"path\":\"src/app.ts\"}}\n{\"ts\":\"2026-10-12T09:00:00.120Z\",\"type\":\"tool_end\",\"id\":\"a\",\"name\":\"read_file\",\"output\":\"1240 bytes\"}\n{\"ts\":\"2026-10-12T09:00:01.000Z\",\"type\":\"tool_call\",\"name\":\"run_tests\",\"input\":{\"pattern\":\"app\"},\"error\":\"Exit code 1: 2 failing\",\"duration_ms\":8400}\n{\"ts\":\"2026-10-12T09:00:10.000Z\",\"type\":\"reasoning\",\"text\":\"(hidden)\"}\n{\"ts\":\"2026-10-12T09:00:12.000Z\",\"type\":\"tool_call\",\"name\":\"edit_file\",\"input\":{\"path\":\"src/app.ts\",\"patch\":\"…\"},\"output\":\"ok\",\"duration_ms\":35}\n{\"ts\":\"2026-10-12T09:00:13.000Z\",\"type\":\"tool_call\",\"name\":\"run_tests\",\"input\":{\"pattern\":\"app\"},\"output\":\"All 14 tests passed\",\"duration_ms\":7900}" } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallTraceExplorerResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "ToolCallTraceExplorerInput": { "type": "object", "additionalProperties": false, "properties": { "trace": { "title": "Transcript or trace", "description": "JSON array / {messages:[…]} of chat messages, Responses API items, or JSON Lines events {ts, type, name, input, output, error, duration_ms}.", "type": "string", "maxLength": 2000000 }, "format": { "title": "Format", "type": "string", "enum": [ "auto", "openai", "anthropic", "events" ], "default": "auto" }, "maxChars": { "title": "Truncate inputs/outputs to", "type": "integer", "minimum": 40, "maximum": 2000, "default": 200, "x-unit": "characters" }, "loopThreshold": { "title": "Identical calls that count as a loop", "type": "integer", "minimum": 2, "maximum": 20, "default": 3 } }, "required": [ "trace" ] }, "ToolCallTraceExplorerResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "format", "messages", "calls", "stats", "repeats", "longest", "totals" ], "properties": { "format": { "type": "string", "enum": [ "openai", "anthropic", "openai-responses", "events" ] }, "messages": { "type": "integer" }, "calls": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "index", "id", "tool", "input", "output", "status", "error", "startedAt", "durationMs", "repeatOf" ], "properties": { "index": { "type": "integer" }, "id": { "type": [ "string", "null" ] }, "tool": { "type": "string" }, "input": { "type": "string" }, "output": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "ok", "error", "no-result" ] }, "error": { "type": [ "string", "null" ] }, "startedAt": { "type": [ "string", "null" ] }, "durationMs": { "type": [ "number", "null" ] }, "repeatOf": { "type": [ "integer", "null" ], "description": "Index of the first identical call (same tool and arguments)." } } } }, "stats": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "tool", "calls", "errors", "noResult", "totalMs", "avgMs", "maxMs" ], "properties": { "tool": { "type": "string" }, "calls": { "type": "integer" }, "errors": { "type": "integer" }, "noResult": { "type": "integer" }, "totalMs": { "type": [ "number", "null" ] }, "avgMs": { "type": [ "number", "null" ] }, "maxMs": { "type": [ "number", "null" ] } } } }, "repeats": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "tool", "args", "count", "calls", "kind" ], "properties": { "tool": { "type": "string" }, "args": { "type": "string" }, "count": { "type": "integer" }, "calls": { "type": "array", "items": { "type": "integer" } }, "kind": { "type": "string", "enum": [ "loop", "retry-after-error", "duplicate" ] } } } }, "longest": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "index", "tool", "durationMs" ], "properties": { "index": { "type": "integer" }, "tool": { "type": "string" }, "durationMs": { "type": "number" } } } }, "totals": { "type": "object", "additionalProperties": false, "required": [ "calls", "errors", "noResult", "distinctTools", "timedCalls", "totalToolMs", "wallClockMs", "hiddenReasoningBlocks" ], "properties": { "calls": { "type": "integer" }, "errors": { "type": "integer" }, "noResult": { "type": "integer" }, "distinctTools": { "type": "integer" }, "timedCalls": { "type": "integer" }, "totalToolMs": { "type": [ "number", "null" ] }, "wallClockMs": { "type": [ "number", "null" ] }, "hiddenReasoningBlocks": { "type": "integer" } } } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }