Tool State Snapshot for Debugging Prompt Template

This prompt is a diagnostic probe for AI operations engineers and platform developers who need to understand what an agent believed about its tool state at the exact moment a failure occurred. When a multi-step agent produces an incorrect result, refuses to proceed, or enters a retry loop, the root cause is almost always a mismatch between the agent's internal state representation and the actual state of its tools. This prompt forces the agent to dump every tool call it has made, every pending operation it is tracking, every cached result it is holding, and every context dependency it is relying on into a structured, timestamped snapshot. The output is designed to be consumed by a human operator during incident response or by an automated analysis pipeline that compares the snapshot against ground-truth tool logs.

This prompt is not a replacement for structured logging, OpenTelemetry tracing, or tool-level audit infrastructure. It is a prompt-level debugging tool that surfaces the agent's belief state—what the agent thinks happened, which may differ from what actually happened. Use it as a checkpoint injected into the agent's context at a known point in the workflow, or trigger it from an error handler when a tool call fails, a validation check fails, or the agent exceeds a retry budget. The snapshot includes tool call IDs, arguments, return values, timestamps, pending operations, cached results with age metadata, and any context dependencies the agent is tracking. For high-risk domains, the snapshot must be routed to a human reviewer before any corrective action is taken, and the output must be scrubbed of sensitive data before storage.

Do not use this prompt as a general-purpose logging mechanism or as a substitute for proper observability instrumentation. It is a targeted debugging tool for production incidents where the agent's reasoning trace is insufficient to explain the failure. Before deploying this prompt, ensure your agent's context window has enough space for the snapshot output without evicting critical instructions. After capturing the snapshot, compare it against your tool execution logs to identify state mismatches, stale cache entries, and missing dependencies. The next step is to feed the identified discrepancies into your state reconciliation or rollback workflow.

This prompt template is designed to be injected into an agent's context immediately after a failure or at a specific checkpoint. Its sole purpose is to force a structured, machine-readable dump of the agent's current operational state. This output is not for end-users; it is a diagnostic artifact for developers and AI operations teams to replay, analyze, and identify the root cause of incorrect tool selection, stale data usage, or context corruption.

codeCopy
You are a diagnostic subroutine. Your only task is to generate a complete, structured snapshot of the current tool-use session state. Do not perform any new tool calls or continue the prior task. Output the snapshot in valid JSON that strictly conforms to the [OUTPUT_SCHEMA] below.

[OUTPUT_SCHEMA]
{
  "session_id": "string, the active session identifier",
  "snapshot_timestamp": "string, ISO 8601 timestamp of this snapshot",
  "active_plan": {
    "goal": "string, the high-level objective of the current task",
    "current_step": "string, description of the step being executed when the snapshot was taken",
    "remaining_steps": ["string, ordered list of planned but unexecuted steps"]
  },
  "tool_call_history": [
    {
      "call_id": "string, unique identifier for the tool call",
      "tool_name": "string",
      "arguments": {},
      "status": "string, one of: 'success', 'failure', 'timeout', 'pending'",
      "result_summary": "string, a concise summary of the result or error message, truncated to 200 characters",
      "cache_status": "string, one of: 'live', 'cached', 'stale', 'unknown'",
      "timestamp": "string, ISO 8601 timestamp of the call"
    }
  ],
  "pending_tool_calls": [
    {
      "call_id": "string",
      "tool_name": "string",
      "arguments": {},
      "reason_pending": "string, why this call has not been executed yet"
    }
  ],
  "current_context_metadata": {
    "total_tokens_used": "integer, estimated token count of the current context window",
    "key_data_entities": ["string, list of critical data points currently in context (e.g., user IDs, order numbers)"],
    "stale_context_flags": ["string, list of any data known to be outdated or invalidated"]
  },
  "failure_context": {
    "last_error_message": "string, the last observed error or exception, if any",
    "suspected_failure_reason": "string, a brief hypothesis for the failure based on available context, or 'unknown'"
  }
}

[CONSTRAINTS]
1. The output must be a single, valid JSON object. No markdown fences, no explanatory text outside the JSON.
2. If a field's value is unknown or not applicable, use `null` for strings and `[]` for arrays. Do not omit fields.
3. When summarizing tool results, redact any values that match common PII patterns (e.g., emails, credit card numbers, SSNs). Replace them with the string `[REDACTED]`.
4. Base all information strictly on the conversation history and system context provided. Do not hallucinate tool calls or state.

To adapt this template, replace the [OUTPUT_SCHEMA] and [CONSTRAINTS] placeholders with your specific requirements. The schema provided is a strong default for debugging multi-step tool use, but you should extend it to include domain-specific fields like user_id, tenant_id, or deployment_version. The PII redaction constraint is critical for production debugging workflows where logs may be shared or stored with lower security controls. Always pair this prompt with a post-processing validation step that checks the JSON structure against your schema before the snapshot is written to your observability platform.

The Tool State Snapshot prompt is designed to be injected into an agent's execution loop at a specific point in time, typically triggered by an error boundary, a scheduled health check, or a manual debug command. The harness should capture the agent's full runtime context—including pending tool calls, cached results, active session metadata, and the current reasoning trace—and pass it into the prompt as structured input. This is not a prompt that runs continuously; it is a diagnostic probe that fires on demand. The primary injection points are: (1) inside a try/catch block wrapping tool execution, where an unhandled exception triggers a snapshot before the agent attempts recovery; (2) at the end of a multi-step tool sequence when a validator detects an unexpected state; and (3) via an operator command that pauses the agent and requests a debug dump. In each case, the harness must freeze the state atomically to avoid capturing a moving target.

To wire this into an application, build a capture_tool_state() function that collects the following from the agent runtime before calling the model: the full list of tool definitions with their current schemas, the ordered history of tool calls with arguments and return values (or error messages), any pending tool calls that have not yet been dispatched, the session identifier and user context metadata, the current context window utilization in tokens, and the agent's last internal reasoning output if available. This function should serialize the state into a JSON object that maps to the [TOOL_STATE_JSON] placeholder in the prompt template. The harness must then call the model with the prompt, parse the structured output against the defined [OUTPUT_SCHEMA], and validate that all required fields—such as pending_calls, cached_results, context_metadata, and anomalies—are present and correctly typed. If validation fails, retry once with a stricter schema reminder; if it fails again, log the raw output and escalate to a human operator rather than silently proceeding with incomplete debug data.

Logging and security are critical because this prompt captures the agent's full internal state, which may include sensitive user data, API keys in tool arguments, or proprietary business logic. Before writing the snapshot to any persistent log, the harness must run a redaction pass that strips or masks PII, credentials, and tokens matching known secret patterns. The redacted snapshot should be written to a structured logging system with a unique snapshot_id, a timestamp, the trigger reason, and the agent's session identifier. Never log the raw, unredacted snapshot to a shared observability platform. For high-risk production systems, require human approval before a snapshot is generated outside of automated error boundaries—an operator should explicitly confirm the debug action. The next step after implementing this harness is to test it against known failure modes: a tool returning malformed JSON, a timeout on a long-running call, a cache returning stale data, and a context window overflow. Each scenario should produce a valid, complete snapshot that an engineer can use to diagnose the root cause without needing to reproduce the failure live.